Running and uploading

The CLI has two ways to upload the suites of easytrace.config.json:

	easytrace run -- <command>	easytrace upload
Runs your tests	Yes, the command after --	No
Which reports	Only files written during this run	Every file that matches, whatever its age
Exit code	Your command's exit code	0 (1 with --strict if the upload failed)
Use it for	Everyday runs, locally and in CI	Uploading after a separate test step, re-uploading

Both upload every suite of the config — or only the ones named with --suite — as one build.

easytrace run

easytrace run -- pnpm test
easytrace run --suite unit -- vitest run --reporter=json --outputFile.json=.easytrace/vitest.json

1. The CLI notes the start time and starts the command without a shell, attached to your terminal. Ctrl+C is passed to the command; press it twice to stop immediately.
2. When the command ends — passed or failed — every suite whose report was written after the start time is uploaded. A suite whose file is older (left over from an earlier run) is skipped:

   EasyTrace: no report for suite "e2e" from this run (.easytrace/playwright.json) — skipped.

3. The CLI exits with the command's exit code (128 + n when it was killed by signal n, 127 when it couldn't be started). Upload problems are only warnings; with --strict, a failed upload after passing tests exits 1.

To chain commands, pass a shell explicitly:

easytrace run -- sh -c 'pnpm test:unit; unit=$?; pnpm test:e2e && exit $unit'

Without a config file or without credentials, the tests still run and keep their exit code; the CLI prints why nothing was uploaded.

easytrace upload

pnpm test:json                         # tests write their reports
pnpm exec easytrace upload             # upload every suite of the config
pnpm exec easytrace upload --suite server --suite web
pnpm exec easytrace upload --dry-run   # show what would be uploaded, send nothing

Because upload doesn't know when the tests ran, it uploads any matching file — including a report from yesterday. Name the suites you just ran with --suite, or delete .easytrace/ before running the tests.

Uploading files directly

With file arguments, upload ignores the config's suites and uploads those files as one run:

easytrace upload "reports/*.xml" --suite integration
easytrace upload results.json --format jest-json --coverage coverage/coverage-final.json

Builds

Every run or upload invocation is one build:

• In CI the build id comes from the CI (GitHub Actions run id + attempt, GitLab pipeline, CircleCI workflow, Jenkins build), so separate jobs of the same pipeline — a unit job and an e2e job — end up in the same build.
• On a machine a new build id is generated per invocation. Uploading twice creates two builds.
• EASYTRACE_BUILD_ID (or --build-id on upload) overrides it, e.g. to merge shards run on different machines of an unknown CI.

What the CLI prints

Uploaded 1 failed, 2 flaky, 212 passed from 3 files (suite unit) · coverage 82.4% lines → https://app.easytrace.dev/app/runs/…
Uploaded 48 passed from 1 file (suite e2e) → https://app.easytrace.dev/app/runs/…
Build 18342917-1: 2 suites uploaded.

One Uploaded line per suite; the Build line follows only when more than one suite was uploaded. Warnings start with EasyTrace:. See Troubleshooting for each one.