Reporter CLI

Since 0.14.0 the reporter package has a command next to the reporter itself. It has one job: mark a run as cancelled in Squally when your CI cancelled the job before the reporter could say so.

npx squally-reporter cancel [--job-key <key>]

Why it exists

On GitHub Actions a cancelled workflow sends SIGINT to the test step’s shell, not to Playwright. Playwright is killed, the reporter never reports the end, and the run stays Running until Squally’s hourly check ends it as incomplete after the run timeout. The command closes that gap from a step that runs only when the job was cancelled.

GitHub Actions

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      SQUALLY_INGEST_KEY: ${{ secrets.SQUALLY_INGEST_KEY }}
    steps:
      # …checkout, setup-node, npm ci, playwright install
      - name: Run Playwright tests
        run: npx playwright test
      - name: Mark Squally run cancelled
        if: ${{ cancelled() }}
        run: npx squally-reporter cancel

• The key on the job. The step reads SQUALLY_INGEST_KEY (and SQUALLY_INGEST_URL, for a Squally other than https://app.squally.dev) like the reporter does, so set them in the job’s env:, not only on the test step.
• The job key on the job. If the job uses SQUALLY_CI_JOB_KEY, set it at job level too, or pass it with --job-key. The command builds the run’s id the same way the reporter did; without the key it names another run, or none.
• fail-fast: false on a sharded or matrix job. With GitHub’s default fail-fast: true, one failing shard cancels the others, their cancel steps run, and the whole run shows as Cancelled instead of Failed.

On another CI, the same command works in whatever step your CI runs when a job is cancelled: it reads the same variables as the reporter.

What it does

It sends one request to Squally with the run’s CI run id - the id the reporter sent from the same job (SQUALLY_CI_RUN_ID, else the provider’s own id, with the job key in it). Squally marks every shard of that run that is still running as cancelled, and a sharded run whose other shards have not started yet as a whole. Results sent afterwards are discarded; the tests that finished stay in the run.

Either way the run ends as Cancelled. Who reports it first decides the source the run page and the read API show:

• Playwright noticed the cancel. A shard was running tests and Playwright itself received the SIGINT - for example because the step starts it with exec, so Playwright is the step’s top-level process. Playwright stops, the reporter sends what finished and reports the cancel: the run page says Cancelled via the reporter, cancellation.source is reporter. The cancel step then only marks the rest of the run - shards that had not started - and prints (0 shards); the source stays reporter.
• Nobody had reported it. No shard was running tests when the workflow was cancelled - a shard was still installing, say - or the SIGINT never reached Playwright. The cancel step marks the run: the run page says Cancelled via the CLI, cancellation.source is cli.

See Cancelled runs.

It prints one line:

Line	Meaning
Marked run #N as cancelled in Squally (X shards)	The run was marked; X is how many of its shards were still running. 0 shards: none was running any more - the reporter had already reported the cancel, or the shards that had not started were marked as part of the run.
Nothing to cancel: no run recorded for <id>	No run with this id: the job was cancelled before its first test, so the reporter never created one. Nothing is created.
Run already finished	The run had ended already - the reporter reported the end itself, or another shard’s step got there first.

Exit codes

It never fails the step. The exit code is 0 for every cancel, also when something goes wrong - each of these prints one warning:

• no ingest key, or a read key (sqly_ro_…) instead of the ingest key;
• no CI run id in the environment (not a CI job, and no SQUALLY_CI_RUN_ID);
• Squally not reachable, or no answer within 30 seconds;
• 401 (wrong key), 404 (a Squally without this command) or a 5xx. A 5xx and a network error are retried once.

Exit code 2 only for wrong arguments: an unknown command, an unknown option, or --job-key without a value. npx squally-reporter --help prints the usage.