npm package: @supatest/cypress-reporter
Description: Supatest Cypress reporter - stream test results to Supatest dashboard
Latest version: 0.0.6

# @supatest/cypress-reporter

Supatest reporter for Cypress - stream test results to the Supatest dashboard in real-time.

## Installation

```bash
npm install @supatest/cypress-reporter --save-dev
# or
yarn add @supatest/cypress-reporter --dev
# or
pnpm add @supatest/cypress-reporter --save-dev
```

## Requirements

- Node.js >= 18.0.0
- Cypress >= 12.0.0

## Usage

Add the reporter plugin to your `cypress.config.ts` (or `cypress.config.js`):

```typescript
// cypress.config.ts
import { defineConfig } from 'cypress';
import supatestPlugin from '@supatest/cypress-reporter';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      supatestPlugin(on, config, {
        projectId: process.env.SUPATEST_PROJECT_ID,
        apiKey: process.env.SUPATEST_API_KEY,
      });
      return config;
    },
  },
});
```

### JavaScript

```javascript
// cypress.config.js
const { defineConfig } = require('cypress');
const supatestPlugin = require('@supatest/cypress-reporter').default;

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      supatestPlugin(on, config, {
        projectId: process.env.SUPATEST_PROJECT_ID,
        apiKey: process.env.SUPATEST_API_KEY,
      });
      return config;
    },
  },
});
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `projectId` | `string` | - | **Required.** Your Supatest project ID. Can also be set via `SUPATEST_PROJECT_ID` env var. |
| `apiKey` | `string` | - | **Required.** Your Supatest API key. Can also be set via `SUPATEST_API_KEY` env var. |
| `apiUrl` | `string` | `https://code-api.supatest.ai` | API endpoint URL. |
| `uploadAssets` | `boolean` | `true` | Whether to upload screenshots and videos. |
| `maxConcurrentUploads` | `number` | `5` | Maximum concurrent attachment uploads. |
| `retryAttempts` | `number` | `3` | Number of retry attempts for failed API calls. |
| `timeoutMs` | `number` | `30000` | Timeout for API calls in milliseconds. |
| `dryRun` | `boolean` | `false` | Log payloads instead of sending to API. Useful for debugging. |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `SUPATEST_PROJECT_ID` | Your Supatest project ID |
| `SUPATEST_API_KEY` | Your Supatest API key |
| `SUPATEST_API_URL` | Custom API endpoint (optional) |
| `SUPATEST_DRY_RUN` | Set to `true` to enable dry-run mode |

## Stable Test IDs

For consistent test tracking across runs, you can assign stable IDs to tests using the `@id:` tag:

```javascript
describe('Login', () => {
  it('@id:TC-001 should login with valid credentials', () => {
    // Test implementation
  });

  it('@id:TC-002 should show error for invalid password', () => {
    // Test implementation
  });
});
```

If no explicit ID is provided, the reporter generates a stable hash based on the spec file path and test title hierarchy.

## Test Tagging

Add tags to your test titles for better organization and filtering in the dashboard:

```javascript
describe('Authentication Tests', () => {
  it('@auth @smoke @priority:high Valid user can login', () => {
    // ...
  });

  it('@auth @owner:team-auth @test_type:regression Locked user cannot login', () => {
    // ...
  });
});
```

### Supported Tags

| Tag Format | Example | Description |
|------------|---------|-------------|
| `@tagname` | `@smoke`, `@auth` | Simple tags for categorization |
| `@owner:name` | `@owner:team-auth` | Assign test ownership |
| `@priority:level` | `@priority:critical` | Priority: `critical`, `high`, `medium`, `low` |
| `@feature:name` | `@feature:login` | Feature grouping |
| `@test_type:type` | `@test_type:regression` | Test type: `smoke`, `e2e`, `regression`, `integration`, `unit` |
| `@slow` | `@slow` | Mark test as expected to be slow |
| `@flaky` | `@flaky` | Mark test as known flaky |

## CI/CD Integration

The reporter automatically detects and captures CI/CD context from:

- GitHub Actions
- GitLab CI
- Jenkins
- CircleCI
- Travis CI
- Buildkite
- Azure Pipelines

Git information (branch, commit, author) is automatically extracted from both CI environment variables and local git repository.

## Features

- Real-time test result streaming
- Screenshot and video uploads
- Retry tracking and flaky test detection
- Git and CI/CD metadata collection
- Browser information capture
- Non-blocking uploads (won't slow down your tests)
- Graceful error handling

## Example

```typescript
// cypress.config.ts
import { defineConfig } from 'cypress';
import supatestPlugin from '@supatest/cypress-reporter';

export default defineConfig({
  e2e: {
    baseUrl: 'https://example.com',
    video: true,
    screenshotOnRunFailure: true,
    setupNodeEvents(on, config) {
      supatestPlugin(on, config, {
        projectId: 'proj_abc123',
        apiKey: 'sk_test_xyz789',
        uploadAssets: true,
      });
      return config;
    },
  },
});
```

## License

ISC