[Docs]: page.route* aren't mocks but stubs

[victorherraiz]

Page(s)

https://playwright.dev/java/docs/mock

Description

The Route API is currently implemented as a test double, but in my opinion, it functions more as a stub rather than a mock. I did not find (or perhaps I missed) any mechanism to verify interactions after test execution.

Mocks are superior in several scenarios, as they enable interaction verification and stricter control over test behavior. This is particularly useful for ensuring that specific methods are called with the expected arguments and produce better errors.

For reference, here are some well-known tools that differentiate between mocks and stubs effectively:

• Mockito (Java)
• WireMock
• Sinon.js (JavaScript)
• Martin Fowler's article: Mocks Aren't Stubs

It would be beneficial to enhance the Route API to support mock-like behavior, allowing developers to verify interactions and ensure precise request matching.

[yury-s]

Thanks for the report! Could you clarify what specific changes you'd propose? Are you looking for an API to assert request handling after execution, or something else? A concrete example of the desired behavior would help us evaluate this better.

[victorherraiz]

Thanks @yury-s

Currently, the documentation uses the term "Mock" in the context of routing and intercepting requests. However, based on the implementation, it seems that "Stub" would be a more accurate term, as the functionality primarily focuses on providing predefined responses rather than verifying interactions.

I propose two potential improvements:

• Simple Change: Update the documentation to replace the term "Mock" with "Stub" where appropriate. This would better align with the actual behaviour of the feature.
• Advanced Feature (Optional): Introduce actual mocking capabilities that allow for post-execution assertions. This would enable users to verify interactions with the route and inspect side effects. For example:

    
    const mock = await page.route('**', async route => {
      const json = [{ name: 'Strawberry', id: 21 }];
      await route.fulfill({ json });
    });

    // Perform interactions (when)
    await page.click('#get-fruits-button');

    // Verify mock interactions (then) (naive impl)
    expect(mock.interactions.length).isEqualTo(1);
    expect(mock.interactions[0].method).isEqualTo('POST');
    expect(mock.interactions[0].body).isEqualTo({ /* Expected request body */ });

This would provide a more robust testing framework, allowing developers to not only stub responses but also assert that the correct interactions occurred during the test.

Benefits:

• The simple change improves clarity and accuracy in the documentation.
• The advanced feature would enhance the testing capabilities, making it easier to validate complex workflows and side effects, and producing clearer errors in the correct verification line.

[yury-s]

Thanks for the suggestion! I understand the distinction you’re making, but for consistency across our docs we’ll continue using the current wording. At this point we’re not planning to rename or reframe the API terminology. There are also no plans at the moment for adding more advanced builtin mocking.