# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stoobly.com/guides/how-to-integrate-e2e-testing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.