How to Integrate E2E Testing

Use the scaffold command to greatly simplify integrating E2E testing!

Background

Scaffold

Getting Started

Create and run a bash script with the following contents:

stoobly-agent scaffold app create <APP-NAME> --plugin playwright

stoobly-agent scaffold service create \
    --hostname <SERVICE-HOSTNAME> \
    --scheme <SERVICE-SCHEME> \
    --port <SERVICE-PORT> \
    <SERVICE-NAME>

Recommended: For E2E testing, include --plugin playwright or --plugin cypress when creating the app scaffold. This sets up the necessary configuration files and dependencies for your chosen test framework.

To learn about each individual command:

app create

How to Scaffold an App

service create

Scaffolding a Service

Example

stoobly-agent scaffold app create stoobly --plugin playwright

stoobly-agent scaffold service create \
    --hostname docs.stoobly.com \
    --scheme https \
    --port 443 \
    docs.stoobly.com

For Cypress, use --plugin cypress instead. You can also use both: --plugin playwright --plugin cypress

Using the JavaScript Client Library

Recommended: Use the Stoobly JavaScript client library (stoobly) to integrate Stoobly directly into your Playwright or Cypress tests. This approach provides programmatic control over recording, mocking, and scenario management from within your test code.

The JavaScript client library simplifies E2E testing by allowing you to:

• Intercept requests automatically from Playwright or Cypress without manual proxy configuration

• Control recording and mocking directly in your test code

• Manage scenarios programmatically (create, switch, and manage test scenarios)

• Configure URL filtering to specify which requests to intercept

Quick Start:

1. Install the library:

npm install stoobly --save-dev

1. Use the interceptor in your tests:

import Stoobly from 'stoobly';

const stoobly = new Stoobly();
const interceptor = stoobly.playwrightInterceptor({
  urls: [new RegExp('https://api.example.com/.*')],
});

test.beforeEach(async ({ page }) => {
  interceptor.withPage(page);
  await interceptor.apply();
});

For complete documentation on using the JavaScript client library:

JS Client

Saving the commands in a script will be useful for updating the scaffold in the future. To learn more:

How to Update a Scaffold

Next Steps

Save the app scaffold in version control

Check in the app and all of its services into your version control such as Git.

Run workflows in the following order

First, to run a workflow:

How to Run a Workflow

Before running another workflow, it is recommended to stop the current workflow:

How to Stop a Workflow

1

Run record workflow

This allows you to check if all your scaffolded services run and can record requests.

2

Run mock workflow

This allows you to check if the previously recorded requests are mocked. Your E2E tests or app should now be able to send requests to the mocked services.

3

Run test workflow

Finally, add a command to run the E2E tests to the entrypoint service as part of its custom docker compose file. Next, run the test workflow to check if tests pass locally. Once the test workflow passes, you can now use it in your CI pipelines.