npm package: @id1man23/cypress-action-capture
Description: Cypress action capture plugin with configurable selectors and request filters.
Latest version: 0.1.4

# @id1man23/cypress-action-capture

Capture user interactions and selected network activity during Cypress tests.

## Install

```bash
npm install -D @id1man23/cypress-action-capture
```

## Cypress setup

Register node tasks in your Cypress config:

```js
const registerActionCaptureTasks = require('@id1man23/cypress-action-capture/node');

module.exports = {
  env: {
    actionCapture: {
      requests: {
        mode: 'all',
      },
    },
  },
  e2e: {
    setupNodeEvents(on, config) {
      registerActionCaptureTasks(on, config);
      return config;
    },
  },
};
```

Register support hooks in your Cypress support file:

```js
import {
  registerActionCaptureConfigInheritance,
  registerActionCaptureSupport,
} from '@id1man23/cypress-action-capture/support';

registerActionCaptureConfigInheritance();
registerActionCaptureSupport();
```

## Usage

Enable recording for a single test:

```js
it('creates an order', { recordActions: true }, () => {
  cy.visit('/orders');
  cy.get('[data-cy="create-order"]').click();
});
```

Enable recording for a suite with overrides:

```js
describe(
  'checkout',
  {
    recordActions: {
      requests: {
        mode: 'all',
        methods: ['GET', 'POST'],
      },
    },
  },
  () => {
    it('submits payment', () => {
      cy.visit('/checkout');
    });
  },
);
```

Manual control is also available:

```js
cy.startActionCapture({
  requests: {
    mode: 'include',
    includePatterns: ['/api/orders/**'],
  },
});

cy.get('[data-cy="submit"]').click();

cy.stopActionCapture();
```

## What gets captured

- Clicks
- Text input
- Select changes
- Key presses
- Navigation events
- `fetch` and `XMLHttpRequest` requests/responses

Captured actions are written to `cypress-action-capture.log` in the project root by default. Override the file name with Cypress env `actionCaptureLogFileName`.

## Configuration

The package already includes a built-in default `recordActions` config. You do not need to copy this object into `cypress.config`.

This default config is applied automatically whenever recording is enabled with `recordActions: true` or `cy.startActionCapture()`.

```js
{
  enabled: false,
  clearLogOnStart: true,
  selectors: {
    strategyOrder: ['testguid', 'data-cy', 'data-testid', 'name', 'text', 'css'],
  },
  requests: {
    mode: 'platform',
    includePatterns: ['/platform'],
    excludePatterns: [],
    methods: [],
  },
}
```

Add to Cypress manually only the package registration:

```js
const registerActionCaptureTasks = require('@id1man23/cypress-action-capture/node');

module.exports = {
  env: {
    actionCapture: {
      requests: {
        mode: 'all',
      },
    },
  },
  e2e: {
    setupNodeEvents(on, config) {
      registerActionCaptureTasks(on, config);
      return config;
    },
  },
};
```

```js
import {
  registerActionCaptureConfigInheritance,
  registerActionCaptureSupport,
} from '@id1man23/cypress-action-capture/support';

registerActionCaptureConfigInheritance();
registerActionCaptureSupport();
```

### Global override in `cypress.config`

If you want to redefine the package defaults once for the whole project, set `actionCapture` in your global Cypress config source.

```js
const registerActionCaptureTasks = require('@id1man23/cypress-action-capture/node');

module.exports = {
  env: {
    actionCapture: {
      enabled: true,
      clearLogOnStart: false,
      selectors: {
        strategyOrder: ['data-cy', 'data-testid', 'css'],
      },
      requests: {
        mode: 'include',
        includePatterns: ['/api/**'],
        excludePatterns: ['/analytics/**'],
        methods: ['GET', 'POST'],
      },
    },
  },
  e2e: {
    setupNodeEvents(on, config) {
      registerActionCaptureTasks(on, config);
      return config;
    },
  },
};
```

This global config is merged with the built-in defaults.

Important:

- global `actionCapture` config does not start recording by itself
- recording still starts only when you explicitly use `recordActions: true`, `recordActions: { ... }`, or `cy.startActionCapture()`
- use the global config only to redefine default selector and request behavior

### Config source: `Cypress.expose()` and `Cypress.env()`

The package supports both global config sources:

- `Cypress.expose('actionCapture')`
- `Cypress.env('actionCapture')`

Resolution order:

1. The package first tries `Cypress.expose('actionCapture')`
2. If it is not available, it falls back to `Cypress.env('actionCapture')`

This means:

- projects that use `Cypress.expose()` can keep that style
- projects that use standard `Cypress.env()` can keep that style too
- package users do not need to choose a special mode manually

Example with `expose`:

```js
module.exports = {
  expose: {
    actionCapture: {
      requests: {
        mode: 'all',
      },
    },
  },
};
```

Example with `env`:

```js
module.exports = {
  env: {
    actionCapture: {
      requests: {
        mode: 'all',
      },
    },
  },
};
```

### How to override it

Override the global/default config per test:

```js
it('captures only selected requests', {
  recordActions: {
    requests: {
      mode: 'include',
      includePatterns: ['/api/orders/**'],
      methods: ['POST'],
    },
  },
}, () => {
  cy.visit('/orders');
});
```

Override the global/default config for a whole suite:

```js
describe('checkout', {
  recordActions: {
    clearLogOnStart: false,
    selectors: {
      strategyOrder: ['data-cy', 'data-testid', 'css'],
    },
  },
}, () => {
  it('submits payment', () => {
    cy.visit('/checkout');
  });
});
```

Override the global/default config for manual recording:

```js
cy.startActionCapture({
  requests: {
    mode: 'all',
    excludePatterns: ['/analytics/**'],
  },
});
```

### `selectors.strategyOrder`

Controls how element selectors are generated. Supported strategies:

- `testguid`
- `data-cy`
- `data-testid`
- `name`
- `text`
- `css`

### `requests`

- `mode: 'platform'` uses `includePatterns` and defaults to `/platform`
- `mode: 'include'` captures only matching `includePatterns`
- `mode: 'all'` captures all requests
- `excludePatterns` removes matching requests
- `methods` limits capture to specific HTTP methods

## Notes

- The package export `@id1man23/cypress-action-capture/support` resolves to `./src/support/index.js` and that file is present in this repository.
- The node entry point is `@id1man23/cypress-action-capture/node`.