Client environment variables

The @s4labs/pixmoat-playwright client reads these variables from the environment of the Playwright process. Set them as CI/CD variables in your pipeline, or in your shell when you run tests locally. Options you pass in code, such as a snapshot() option or a reporter option, take priority over the matching variable.

For how the variables fit into a working setup, see Connect Playwright.

Connection and build

Variable	Default	What it does	When to set it
`PIXMOAT_TOKEN`	—	Project access token the client sends with every request.	Always, unless `PIXMOAT_MODE` is `local`. The client stops with an error when it’s missing. Store it as a masked CI/CD variable.
`PIXMOAT_PROJECT`	—	Slug of the pixmoat project that receives the screenshots.	Always, unless `PIXMOAT_MODE` is `local`. The client stops with an error when it’s missing.
`PIXMOAT_URL`	`https://app.pixmoat.com`	Base URL of the pixmoat app. A trailing slash is removed.	Only when you reach pixmoat through a proxy or a different host.
`PIXMOAT_BRANCH`	—	Git branch the build belongs to. pixmoat uses it to pick baselines.	Whenever the client creates the build. In GitLab CI, use `$CI_COMMIT_BRANCH` (or `$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` in merge request pipelines).
`PIXMOAT_COMMIT`	—	Full commit SHA the build belongs to.	Whenever the client creates the build. In GitLab CI, use `$CI_COMMIT_SHA`.
`PIXMOAT_GITLAB_FREE_QUEUE`	Unset	Set to `1` for GitLab Free queue integration captures on MR pipelines. Other pipeline sources keep ordinary branch capture.	In repositories using the Free merge queue.
`PIXMOAT_QUEUE_TARGET_SHA`	Unset	Full target HEAD commit SHA fetched before a Free queue capture. The client verifies that it is an ancestor of Git HEAD.	Export from the queue capture preparation script.
`PIXMOAT_PR`	—	Merge request or pull request number, as a whole number. It’s shown next to the build in the builds list and included in webhook payloads. Baselines are chosen by branch, not by this number. A value that isn’t a number is ignored.	In merge request pipelines. In GitLab CI, use `$CI_MERGE_REQUEST_IID`.
`PIXMOAT_CI_URL`	—	Pipeline or job URL shown on the build, so reviewers can jump back to CI.	Optional, in CI. In GitLab CI, use `$CI_PIPELINE_URL`.
`PIXMOAT_BUILD_ID`	—	ID of an existing build. When it’s set, the client adds screenshots to that build instead of creating one, and it doesn’t send `.pixmoat.yaml` or the `CODEOWNERS` file. `startBuild()` also sets it for the worker processes it starts.	When a previous step already created the build and you want this run to add to it.
`PIXMOAT_REQUEST_TIMEOUT_MS`	`30000`	Time limit for each request to pixmoat, in milliseconds. A request that takes longer fails, so an unreachable server can’t hang the CI job. A value that isn’t a number is ignored.	When uploads of large screenshots over a slow network time out.
`PIXMOAT_CODEOWNERS`	Discovery on	The client reads your repository’s `CODEOWNERS` file (from the root, `.github/`, `.gitlab/`, `.bitbucket/` or `docs/`) and sends it with the build, so pixmoat can suggest reviewers. `0` or `false` turns this off.	When you don’t want the file sent to pixmoat.

Capture defaults

These set defaults for every snapshot() call. A per-snapshot option wins over the variable.

Variable	Default	What it does	When to set it
`PIXMOAT_VIEWPORTS`	—	Comma-separated viewport sizes, such as `1280x720,375x812`. Each snapshot is captured once per viewport.	When every snapshot should cover the same set of screen sizes.
`PIXMOAT_BROWSERS`	—	Comma-separated browsers, such as `chromium,firefox,webkit`. Each snapshot is captured once per browser. Browsers other than the one running the test open a fresh page without your test’s cookies or login.	When every snapshot should cover several browsers.
`PIXMOAT_DPR`	The browser context’s device scale factor, or `1`	Device pixel ratio: `1`, `2` or `3`. Values outside that range are clamped with a warning. A fraction is cut to its whole number, so `2.5` becomes `2`.	When you want high-density screenshots without changing the Playwright context.
`PIXMOAT_FULLPAGE`	`false`	`true` or `1` captures the full scrollable page instead of the viewport.	When most of your snapshots should be full-page.
`PIXMOAT_PERFORMANCE`	`false`	`true` or `1` collects performance metrics (Core Web Vitals) with each snapshot.	When you want performance numbers next to your visual results.
`PIXMOAT_ELEMENT_MAP`	`true`	Collects a map of page elements with each snapshot, so a diff can name the element that changed. `false` or `0` turns it off.	When collecting the map slows down very large pages.
`PIXMOAT_SKIP_MANIFEST`	`false`	`true` or `1` uploads every screenshot in full. Normally the client first asks pixmoat which screenshots it already has, and skips uploading unchanged ones.	When you’re debugging uploads. It makes runs slower and uses more bandwidth.

Local mode

Variable	Default	What it does	When to set it
`PIXMOAT_MODE`	`ci`	`ci` uploads screenshots to pixmoat. `local` writes PNG files and an `index.json` to disk and makes no network calls, so `PIXMOAT_TOKEN` and `PIXMOAT_PROJECT` aren’t needed. Any other value is treated as `ci`. Each Playwright worker overwrites `index.json` with only its own screenshots, so run local mode with one worker.	Set `local` on your own machine for quick feedback without creating builds.
`PIXMOAT_OUT_DIR`	`.pixmoat/current`	Folder where local mode writes screenshots. Ignored in `ci` mode.	When `.pixmoat/current` doesn’t suit your repository layout.

Reporter (beta)

The Playwright reporter is in beta; see Reporter (beta) before you use it. These variables affect only the reporter. The snapshot() fixture doesn’t read them.

Variable	Default	What it does	When to set it
`PIXMOAT_FAIL_ON_BLOCKED`	`true`	Makes the reporter fail the Playwright run when the build is blocked (a project in blocking mode with unreviewed changes). `false` or `0` turns this off. The reporter’s `failOnBlocked` option overrides it.	When you want the reporter to upload without failing the run.
`PIXMOAT_REPORT_DIR`	`pixmoat-report`	Folder where the reporter writes `pixmoat.env`, `junit.xml` and `report.html`. The reporter’s `reportDir` option overrides it.	When your CI expects report artifacts in another folder.

Variables the reporter writes

The reporter writes these to pixmoat.env in the report folder, so a GitLab artifacts:reports:dotenv report can pass them to later jobs. You don’t set them yourself.

Variable	Value
`PIXMOAT_REVIEW_URL`	Link to the build’s review page.
`PIXMOAT_BUILD_ID`	ID of the build the run uploaded to.
`PIXMOAT_CI_STATUS`	`passed`, `failed` or `blocked`, or `unknown` when pixmoat didn’t report a status.

GitLab merged-result metadata

In CI mode, the client detects CI_MERGE_REQUEST_EVENT_TYPE=merged_result and reads CI_MERGE_REQUEST_SOURCE_BRANCH_SHA, CI_MERGE_REQUEST_TARGET_BRANCH_SHA, CI_MERGE_REQUEST_TARGET_BRANCH_NAME, CI_COMMIT_SHA, and CI_PIPELINE_ID. The source branch name and MR number fall back to CI_MERGE_REQUEST_SOURCE_BRANCH_NAME and CI_MERGE_REQUEST_IID. Full commit SHAs and positive numeric IDs are required. Local mode ignores this metadata. Merge-train pipelines are rejected.

PIXMOAT_COMMIT does not override the source SHA for an integration capture. startBuild() creates a new integration build and shares its ID with workers. The reporter creates a new integration build too. PIXMOAT_FAIL_ON_BLOCKED=false does not disable integration validation failure. See Capture the proposed merge.