zephyr-playwright-reporter

Small Zephyr Scale for Jira Cloud integration for Playwright: after the run it collects per-test results, ensures the configured test-cycle folder exists, creates a new test cycle, and uploads via the custom automation API (POST /automations/executions/custom), packaging { version: 1, executions } as zephyr-executions.json inside a ZIP.

This package does not read process.env. The consuming Playwright project passes options from playwright.config.ts (read env vars there and forward values).

Install

From your Playwright project:

npm install -D zephyr-playwright-reporter

Requires Node.js 18+ and @playwright/test (peer dependency).

playwright.config.ts

Use dotenv (or your own loader) in the config file, then pass ZephyrScaleReporterOptions:

import { defineConfig } from '@playwright/test';
import dotenv from 'dotenv';

dotenv.config({ path: '.env' });

export default defineConfig({
  reporter: [
    ['list'],
    [
      'zephyr-playwright-reporter/reporter',
      {
        authorizationToken: process.env.ZEPHYR_TOKEN,
        projectKey: process.env.ZEPHYR_PROJECT_KEY,
        cycleFolderName: 'Automation',
        cycleNamePrefix: 'My Product E2E',
        jiraBaseUrl: process.env.ZEPHYR_JIRA_BASE_URL,
        jiraScaleAppsPath: process.env.ZEPHYR_SCALE_APPS_PATH,
      },
    ],
  ],
});

Reporter options

| Option | Purpose | | -------------------- | ------------------------------------------------------------------------------------------------- | | disabled | When true, the reporter is a no-op (tests run normally, nothing is uploaded). Default: false. | | authorizationToken | Zephyr API bearer token. Required for upload. | | projectKey | Jira / Zephyr project key (e.g. PROJECT_KEY). Required for upload. | | apiBaseUrl | Zephyr REST root including /v2. Defaults to the US Scale endpoint. | | cycleFolderName | Test-cycle folder; created if missing. Default: Playwright. | | cycleNamePrefix | Prefix used in "{prefix} [{UTC}]" cycle names. Default: E2E. | | jiraBaseUrl | Atlassian site, e.g. https://acme.atlassian.net. Used to build the Jira deep link. | | jiraScaleAppsPath | uuid1/uuid2 segment under /apps/ (from a Zephyr Scale URL in Jira). |

To gate uploading on an env var, derive disabled in your config — e.g. disabled: process.env.ZEPHYR_REPORT === 'false'.

When jiraBaseUrl and jiraScaleAppsPath are both set, the reporter prints a Jira link like:

https://acme.atlassian.net/jira/software/projects/PROJECT_KEY/apps/<uuid1>/<uuid2>#/v2/testCycle/PROJECT_KEY-R21

Test titles

Only tests that map to a Zephyr case are uploaded. Either:

• Start the leaf title with [PROJ-Tn], e.g. [PROJECT_KEY-T2] Login happy path, or
• Set annotation { type: 'zephyrTestCaseKey', description: 'PROJECT_KEY-T2' }.