Collections

A collection is a named set of scenarios you run together — typically smoke (fast, key flows) and regress (the full sweep).

Run a collection

cd unotest && npx @unotest/web collection smoke --workers=4

Flag	Effect
--workers=N	run N scenarios in parallel (overrides the manifest for this run)
--bail	stop after the first failure
--headed	run with a visible browser

Parallelism per collection

Set a default worker count in the collection’s YAML — every run of the collection (CLI, CI, viewer) picks it up:

description: fast key flows
workers: 4
scenarios:
  - login
  - checkout/guest

workers is an integer ≥ 1; omit it for serial runs. The --workers=N flag overrides the manifest for a single run.

Preparing the environment

A suite that needs a seeded database or a reset fixture says so in its own YAML, and every run of it prepares the same way — a scheduled tick, a CI run, the Run button in the viewer:

description: fast key flows
prepare: "node scripts/seed.mjs"
scenarios:
  - login
  - checkout/guest

The command runs from the project root, inside the same queue slot as the suite (preparing touches the target, which is exactly what the queue serialises) and before the first scenario. If it fails, the run exits 94 — the environment was not prepared and nothing was tested, which is a different alert from a red suite (exit 1).

--no-prepare skips it for one run, for an environment somebody else prepared. A schedules entry may name a prepare of its own; that one wins for its tick (a nightly reseed the hourly run must not do).

Browser window per collection

Since 0.49.0. A suite that needs the real browser window — screenshots of a page at its natural width, a run on a browser profile, where setViewport(null) is refused — sets it for its own runs:

description: screenshots on the real window
viewport: null
scenarios:
  - shots/gallery

viewport: null is the real window; {width: 390, height: 844} an emulated size. It replaces the project’s viewport for every scenario of this collection and nowhere else: the same scenario run on its own keeps the project’s window. Headless, the real window’s size comes from --window-size in launch.args. A viewport: null next to a project device is refused before the first scenario starts.

In the viewer

The viewer manages collections visually: create, rename, reorder by drag, set the workers count, and run the whole set. During a run you see per-scenario status, a progress bar, and a one-click abort. Outside the viewer the same progress is the run’s own journal — see Watching a collection run.

In CI

Collections are the natural CI unit — run smoke on every push, regress nightly. See Run in CI.