How to Integrate E2E Testing

Use the scaffold command to greatly simplify integrating E2E testing!

Background

Scaffold

Getting Started

Create a declarative scaffold config at .stoobly/scaffold.yml. This file maps 1:1 to scaffold CLI commands and can be applied, shared, and version-controlled:

# .stoobly/scaffold.yml
version: 1
commands:
  - resource: app
    action: create
    options:
      app_name: <APP-NAME>
      # For E2E testing, add plugin: [playwright] or plugin: [cypress]
      plugin: [playwright]

  - resource: service
    action: create
    options:
      service_name: <SERVICE-NAME>
      hostname: <SERVICE-HOSTNAME>
      scheme: <SERVICE-SCHEME>
      port: <SERVICE-PORT>

Then validate and apply the config:

stoobly-agent scaffold apply .stoobly/scaffold.yml --dry-run
stoobly-agent scaffold apply .stoobly/scaffold.yml

Recommended: For E2E testing, include plugin: [playwright] or plugin: [cypress] in the app step. This sets up the necessary configuration files and dependencies for your chosen test framework.

For the full scaffold apply walkthrough and config schema:

Applying a Scaffold Config

To learn about the individual commands scaffold apply runs under the hood:

app create

How to Scaffold an App

service create

Scaffolding a Service

Example

# .stoobly/scaffold.yml
version: 1
commands:
  - resource: app
    action: create
    options:
      app_name: stoobly
      plugin: [playwright]

  - resource: service
    action: create
    options:
      service_name: docs.stoobly.com
      hostname: docs.stoobly.com
      scheme: https
      port: 443

stoobly-agent scaffold apply .stoobly/scaffold.yml --dry-run
stoobly-agent scaffold apply .stoobly/scaffold.yml

For Cypress, use plugin: [cypress] instead. You can also use both: plugin: [playwright, 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.enable();
});

For complete documentation on using the JavaScript client library:

JS Client

Check in .stoobly/scaffold.yml to version control so you can re-apply or update the scaffold later. To learn more:

How to Update a Scaffold

Next Steps

Save the app scaffold in version control

Check in .stoobly/scaffold.yml, 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.