@devant-net/cypress-reporter

Cypress plugin that streams runs, results, and artifacts into Devant Cloud.

Install

bun add -D @devant-net/cypress-reporter cypress

Configure

In your cypress.config.ts:

import { defineConfig } from "cypress";
import { devqReporter } from "@devant-net/cypress-reporter";

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      devqReporter(on, config);
      return config;
    },
  },
  video: true,
  screenshotOnRunFailure: true,
});

You can pass options inline…

setupNodeEvents(on, config) {
  devqReporter(on, config, {
    apiUrl: "https://acme.devq.cloud",
    apiToken: process.env.DEVQ_TOKEN,
    projectId: 1,
    runName: `PR ${process.env.GITHUB_PR_NUMBER}`,
  });
  return config;
},

…or set them via env (preferred in CI):

| Var | Default | Notes | |---|---|---| | DEVQ_API_URL | http://localhost:32124 | Your tenant's URL | | DEVQ_TOKEN | dev-admin-token | Bearer token (use a real CI token in CI) | | DEVQ_PROJECT_ID | 1 | Devant Cloud project id | | DEVQ_RUN_NAME | Cypress — <ISO date> | Display name on the run | | DEVQ_RUN_ID | unset | If set, attach to an existing run (orchestration) |

Cypress hides process.env from the plugin scope unless you mirror values into config.env. The reporter reads both, so either approach works:

// cypress.config.ts
env: {
  DEVQ_TOKEN: process.env.DEVQ_TOKEN,
  DEVQ_PROJECT_ID: process.env.DEVQ_PROJECT_ID,
}

How tests bind to test cases

The reporter resolves each Cypress test against a Devant Cloud test_case row in this order:

1. @DEF-AB12 style tag anywhere in the describe/it title path → GET /v1/test-cases/by-key/DEF-AB12.
2. Exact name match in the project. The case name is the leaf it() title (e.g. adds 2 todos), not the full describe path → GET /v1/test-cases?search=….
3. Auto-create → POST /v1/test-cases. The reporter prints:

   [devq] minted DEF-XYZ9 for "TodoMVC > adds 2 todos"
          — add '@DEF-XYZ9' to a describe/it title to bind it

Once you embed the tag, future runs (even with renames) keep the same case:

describe("TodoMVC", () => {
  it("adds 2 todos @DEF-XYZ9", () => { /* … */ });
});

Suites

The enclosing describe() chain becomes the case's suite. The reporter sends it as suite_path (/-joined); Devant Cloud upserts the suite hierarchy by name and files the case under it. A suite assigned manually in the UI is never overwritten.

describe("Checkout", () => {            // suite: Checkout
  describe("payment", () => {           // suite: Checkout / payment
    it("declines an expired card @DEF-AB12", () => { /* … */ });
  });                                   // name: "declines an expired card @DEF-AB12"
});

Case names are unique per project, not per suite. Two suites that each have an it("loads") collide on the same name — bind them with distinct @KEY tags so they resolve by key instead of by name.

CI metadata

Auto-detected for GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure DevOps, plus a generic CI=true fallback. Populates the ci_* columns on the run so the dashboard can deep-link to commits/PRs and the CI workflow page.

Coverage

If @cypress/code-coverage is installed and writes Istanbul output to .nyc_output/, the reporter picks it up in after:run and submits a summary to POST /v1/runs/:id/coverage. Lines, branches, functions, and statements percentages all render on the run detail page.

What gets sent

| Cypress hook | Devant Cloud call | |---|---| | before:run | POST /v1/runs (with CI auto-detected) | | after:spec | GET /v1/test-cases/by-key/... (or search/create) per test → POST /v1/runs/:id/results (carries suite_path from the describe chain) → POST /v1/runs/:id/results/:rid/attempts/:aid/artifacts (multipart) for screenshots/video on failure | | after:run | POST /v1/runs/:id/coverage (if .nyc_output/ exists) → POST /v1/runs/:id/complete (unless DEVQ_RUN_ID set) → flush queue |

All requests use bearer auth and have bounded retry (3× exponential backoff with jitter for 5xx + 429 + network errors; 4xx fails fast).

Limitations

• No per-step output. Cypress doesn't expose individual command-level details to plugin hooks the way Playwright's reporter API does, so the steps[] array on each attempt is empty. Test- and attempt-level results, errors, durations, and artifacts are all captured.
• Screenshots/videos only on failure. Cypress only persists screenshots on failure by default and writes a single video per spec. The reporter attaches both to the last attempt of any failing test.