> For the complete documentation index, see [llms.txt](https://docs.stoobly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoobly.com/faq/scaffold/e2e-testing/js-client/cypress.md).

# Cypress

### Cypress Integration

#### Q: How do I integrate Stoobly with Cypress tests?

**A:** Create a Stoobly instance and Cypress interceptor, then call `enable()` in your `beforeEach` hook.

**Example:**

```javascript
import Stoobly from 'stoobly';
import { RecordPolicy, RecordOrder, RecordStrategy } from 'stoobly/constants';

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

describe('My Tests', () => {
  // Use function() form to access Mocha context
  beforeEach(function () {
    // Derive hierarchical scenario name from the test path
    const scenarioName = this.test.titlePath().join(' > ');
    interceptor.withScenarioName(scenarioName);

    // Enable interceptor in beforeEach
    interceptor.enable();
  });

  it('can fetch data', () => {
    cy.visit('https://example.com');
    // Your test code here
  });
});
```

#### Q: Why must I call `enable()` in `beforeEach` for Cypress?

**A:** Cypress automatically clears all intercepts before every test, so you must reapply the Stoobly interceptor in `beforeEach`.

**Example:**

```javascript
describe('API Tests', () => {
  beforeEach(function () {
    // Required: Reapply interceptor for each test
    // Cypress clears cy.intercept between tests
    const scenarioName = this.test.titlePath().join(' > ');
    interceptor.withScenarioName(scenarioName);
    interceptor.enable();
  });

  it('test 1', () => {
    // Interceptor is active
  });

  it('test 2', () => {
    // Interceptor must be reapplied (done in beforeEach)
  });
});
```

#### Q: How do I record requests in Cypress tests?

**A:** Set **`mode: InterceptMode.record`** in the interceptor settings (constructor options) and call `enable()` as usual, **or** call `enable({ mode: InterceptMode.record })` in `beforeEach`.

**Example:**

```javascript
import Stoobly from 'stoobly';
import { InterceptMode, RecordPolicy, RecordOrder, RecordStrategy } from 'stoobly/constants';

const stoobly = new Stoobly();
const interceptor = stoobly.cypressInterceptor({
  urls: ['https://api.example.com/users'],
  mode: InterceptMode.record,
  record: {
    policy: RecordPolicy.All,
    order: RecordOrder.Overwrite,
    strategy: RecordStrategy.Full,
  }
});

describe('Record Requests', () => {
  beforeEach(function () {
    const scenarioName = this.test.titlePath().join(' > ');
    interceptor.withScenarioName(scenarioName);
    interceptor.enable();
  });

  it('records API calls', () => {
    cy.visit('https://example.com');
    // All API requests matching urls will be recorded
  });
});
```

#### Q: What's the warning about synchronous requests in Cypress?

**A:** Synchronous XMLHttpRequest calls will cause Cypress to hang. Avoid using synchronous requests when Stoobly interceptor is active.

**Example:**

```javascript
// BAD: Synchronous request (will hang Cypress)
const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.example.com/data', false); // false = synchronous
xhr.send();

// GOOD: Asynchronous request (works correctly)
const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.example.com/data', true); // true = asynchronous
xhr.send();

// BETTER: Use fetch or Cypress commands
cy.request('GET', 'https://api.example.com/data');
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/faq/scaffold/e2e-testing/js-client/cypress.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.