# How to Integrate E2E Testing

Use the scaffold command to greatly simplify integrating E2E testing!

## Background

{% content-ref url="../core-concepts/scaffold" %}
[scaffold](https://docs.stoobly.com/core-concepts/scaffold)
{% endcontent-ref %}

## Getting Started

Create and run a bash script with the following contents:

```bash
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>
```

{% hint style="info" %}
**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.
{% endhint %}

To learn about each individual command:

`app create`

{% content-ref url="how-to-integrate-e2e-testing/how-to-scaffold-an-app" %}
[how-to-scaffold-an-app](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-scaffold-an-app)
{% endcontent-ref %}

`service create`

{% content-ref url="how-to-integrate-e2e-testing/how-to-scaffold-an-app/scaffolding-a-service" %}
[scaffolding-a-service](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-scaffold-an-app/scaffolding-a-service)
{% endcontent-ref %}

### Example

```bash
stoobly-agent scaffold app create stoobly --plugin playwright

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

{% hint style="info" %}
For Cypress, use `--plugin cypress` instead. You can also use both: `--plugin playwright --plugin cypress`
{% endhint %}

## Using the JavaScript Client Library

{% hint style="info" %}
**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.
{% endhint %}

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:

```bash
npm install stoobly --save-dev
```

2. Use the interceptor in your tests:

```typescript
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:

{% content-ref url="../faq/scaffold/e2e-testing/js-client" %}
[js-client](https://docs.stoobly.com/faq/scaffold/e2e-testing/js-client)
{% endcontent-ref %}

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

{% content-ref url="how-to-integrate-e2e-testing/how-to-update-a-scaffold" %}
[how-to-update-a-scaffold](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-update-a-scaffold)
{% endcontent-ref %}

## 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:

{% content-ref url="how-to-integrate-e2e-testing/how-to-run-a-workflow" %}
[how-to-run-a-workflow](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-run-a-workflow)
{% endcontent-ref %}

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

{% content-ref url="how-to-integrate-e2e-testing/how-to-stop-a-workflow" %}
[how-to-stop-a-workflow](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-stop-a-workflow)
{% endcontent-ref %}

{% stepper %}
{% step %}
**Run record workflow**

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

{% step %}
**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.
{% endstep %}

{% step %}
**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.
{% endstep %}
{% endstepper %}