@qualflare/cypress 0.1.0 → 0.3.0

package/README.md

@@ -1,9 +1,15 @@
 # @qualflare/cypress
 
-A native Cypress reporter for [Qualflare](https://qualflare.com) — uploads test results directly
+[![npm version](https://img.shields.io/npm/v/%40qualflare%2Fcypress.svg)](https://www.npmjs.com/package/@qualflare/cypress)
+[![CI](https://github.com/Qualflare/qualflare-cypress/actions/workflows/ci.yml/badge.svg)](https://github.com/Qualflare/qualflare-cypress/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
+
+A native Cypress reporter for [Qualflare](https://qualflare.com) — captures test results directly
 from your Cypress run: suite/test status, real retry counts, screenshots, step-by-step command
-traces, and author-facing metadata (labels, links, tags, custom attachments). No post-hoc file
-parsing, no intermediate report format.
+traces, and author-facing metadata (labels, links, tags, custom attachments) — and writes them into
+a report directory that [`qualflare-cli`](https://github.com/Qualflare/qualflare-cli) uploads. No
+post-hoc file parsing, no intermediate report format to hand-roll, no network access needed from
+inside your Cypress run.
 
 ## Install
 
@@ -11,7 +17,17 @@ parsing, no intermediate report format.
 npm install --save-dev @qualflare/cypress
 ```
 
-Requires Cypress `>=12.0.0 <15.0.0` (installed separately as a peer dependency) and Node `>=18`.
+Requires Cypress `>=12.0.0` (installed separately as a peer dependency). Node `>=18` for
+Cypress 12–14; Cypress 15 itself requires Node `>=20`.
+
+The peer range is deliberately open-ended rather than capped at a known-good major, so a new
+Cypress release never hard-blocks `npm install` for you. Every major from 12 through 15 is
+exercised in CI against a real `cypress run`; majors newer than that are untested but not
+refused — please [open an issue](https://github.com/Qualflare/qualflare-cypress/issues) if
+one misbehaves.
+
+(Contributors: the repo itself now develops against Cypress 15, which requires Node `>=20.1`.
+The `>=18` floor above is the *consumer* requirement and still holds for Cypress 12–14.)
 
 ## Quickstart
 
@@ -36,14 +52,26 @@ export default defineConfig({
 import '@qualflare/cypress';
 ```
 
-Set your token via the `QUALFLARE_TOKEN` environment variable (or the `token` plugin option):
+Run your tests as usual — every `cypress run` writes a Collect report (JSON, plus any video
+attachments) into `./qualflare-results` by default. No token or network access is needed for this
+step; the reporter itself never makes a network call:
+
+```sh
+npx cypress run
+```
+
+Then, in the same CI job, hand that directory to `qualflare-cli` — the step that actually uploads
+results, required after every run, sharded or not:
 
 ```sh
-QUALFLARE_TOKEN=<your-token> npx cypress run
+npm install -g @qualflare/cli
+qf login my-project "$QUALFLARE_TOKEN" --force
+qf my-project collect ./qualflare-results
 ```
 
-That's it — suite/test results, retries, and automatic-on-failure screenshots upload as one Launch
-at the end of the run. See [`examples/basic/`](./examples/basic) for a complete runnable project.
+That's it — suite/test results, retries, and automatic-on-failure screenshots show up as one Launch
+once `qualflare-cli collect` runs. [`examples/basic/`](./examples/basic) has a runnable project
+demonstrating the same flow end to end, including the `qualflare.*` metadata API.
 
 ## Enriching your tests
 
@@ -75,10 +103,21 @@ Every option can be set either as a plugin option (`qualflareCypress(on, config,
 `QUALFLARE_*` environment variable. Full table, precedence rules, and auto-detection behavior (git
 branch/commit, CI provider/build/PR, browser/OS) in [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md).
 
+One option is worth calling out because it fails late: `environment` is matched against the
+environment's **uid (slug)**, not its display name, so **Staging** in the UI is `staging` here. A
+wrong value cannot fail at run time — this package makes no network calls — so the run succeeds and
+`collect` 404s afterwards. See
+[the note in the configuration docs](./docs/CONFIGURATION.md#environment-is-matched-by-uid-not-display-name).
+
 ## Known limitations
 
-- **No video upload** — Qualflare has no blob/video-attachment storage yet.
-- **One `cypress run` process uploads as one Launch** — sharded CI setups get multiple Launches.
+- **Sharded CI runs merge automatically, but only at collect time** — point every shard's
+  `cypress run` at the same shared `outputDir`; `qualflare-cli collect` merges every report file it
+  finds there into one Launch, no extra flag needed (see
+  [`docs/LIMITATIONS.md`](./docs/LIMITATIONS.md)).
+- **A stale `outputDir` is refused, not merged** — each report carries a `runId`, and `qf collect`
+  errors rather than merging files from two different runs. Needs `@qualflare/cli` v0.1.19+; older
+  CLIs merge as before.
 - **Command-log step nesting is two levels only** (Cypress's own API limit) — `qualflare.step()`
   supports arbitrary nesting depth.
 
@@ -91,7 +130,7 @@ npm run typecheck   # tsc --noEmit
 npm run lint        # eslint .
 npm run build       # tsup — dual ESM+CJS, .d.ts
 npm test            # unit tests (vitest)
-npm run test:integration   # spawns real cypress run against a fixture project + mock server
+npm run test:integration   # spawns a real cypress run against a fixture project, asserts on its outputDir report
 ```
 
 Release process: see [`RELEASING.md`](./RELEASING.md).

package/dist/index.cjs

@@ -45,6 +45,7 @@ var MAX_LABELS_PER_CASE = 100;
 var MAX_LINKS_PER_CASE = 20;
 var MAX_TAGS_PER_CASE = 64;
 var MAX_TAG_LENGTH = 255;
+var MAX_VIDEO_UPLOAD_BYTES = 50 * 1024 * 1024;
 var MAX_STEPS_PER_TEST_ATTEMPT = 300;
 
 // src/shared/duration.ts