CI integration

Nijam is built to run in CI. You don’t pass commit, branch, PR, or author by hand - the Playwright reporter detects them automatically from your CI provider, so each run lands in history with full context.

The reporter prints the run’s dashboard link to stdout - both when the run starts and when it finishes - so it lands right in your CI run logs (and your terminal locally):

[nijam] run started - view it at https://www.nijam.dev/...
...
[nijam] run finalized (12/14 passed) - view it at https://www.nijam.dev/...

Most CI log viewers make the URL clickable - open it to jump straight from the build to the run in Nijam. Set silent: true to suppress all [nijam] output.

What’s detected

Commit, branch, PR number, CI run id, CI run URL, and the git author (email + name). Resolution order, per field:

CI-specific environment variables (see below)
Generic GIT_* / BRANCH / COMMIT_SHA variables
A git log / git rev-parse shell-out
Empty (branch is left unset → the dashboard shows “No Branch Info”)

Supported providers

Detected from GITHUB_SHA, GITHUB_REF_NAME, GITHUB_HEAD_REF, GITHUB_RUN_ID, GITHUB_REPOSITORY, GITHUB_SERVER_URL.

name: e2e
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
        env:
          NIJAM_API_KEY: ${{ secrets.NIJAM_API_KEY }}

Detected from CI_COMMIT_SHA, CI_COMMIT_REF_NAME, CI_PIPELINE_ID, CI_MERGE_REQUEST_IID, GITLAB_USER_EMAIL, GITLAB_USER_NAME, CI_COMMIT_AUTHOR.

e2e:
  image: mcr.microsoft.com/playwright:latest
  script:
    - npm ci
    - npx playwright test
  variables:
    NIJAM_API_KEY: $NIJAM_API_KEY

Detected from CIRCLE_SHA1, CIRCLE_BRANCH, CIRCLE_BUILD_NUM, CIRCLE_PULL_REQUEST, CIRCLE_BUILD_URL.

jobs:
  e2e:
    docker: [{ image: mcr.microsoft.com/playwright:latest }]
    steps:
      - checkout
      - run: npm ci
      - run: npx playwright test
        environment:
          NIJAM_API_KEY: $NIJAM_API_KEY

Detected from BITBUCKET_COMMIT, BITBUCKET_BRANCH, BITBUCKET_PR_ID, BITBUCKET_BUILD_NUMBER, BITBUCKET_REPO_FULL_NAME, BITBUCKET_GIT_HTTP_ORIGIN.

pipelines:
  default:
    - step:
        image: mcr.microsoft.com/playwright:latest
        script:
          - npm ci
          - npx playwright test

Sharded runs

Splitting a suite across CI jobs all clubs into one Nijam run (they share the CI run id), and a failure in any job flips that run to Failing right away. The dashboard shows running / failing live until the run completes - and how it completes depends on how you split:

--shard=i/N - auto-detected from config.shard. Each test is tagged with its 1-based shard index (i of N); each shard streams its results and reports when it finishes, and because Playwright knows the total, Nijam completes the run once every shard has reported. Nothing to configure - no extra step.
A matrix where each job runs different specs (no --shard - e.g. one spec file per job) - here Playwright reports no total, so you supply one. The simplest way: set NIJAM_SHARD_INDEX (this job’s shard number, 1 to N, unique per job) and NIJAM_SHARD_TOTAL (N) on each job. The reporter sends them as its shard, so Nijam knows the total, auto-completes once all N jobs report, and stamps each job’s machine - no post-matrix step. If you can’t assign unique indices, set autoComplete: false (or NIJAM_AUTO_COMPLETE=false) instead and add one post-matrix step that calls POST /v1/runs/complete.

Auto-detected - each shard self-reports and the run completes once all four are in. No autoComplete, no completion step.

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test --shard=${{ matrix.shard }}/4
        env:
          NIJAM_API_KEY: ${{ secrets.NIJAM_API_KEY }}

Give each job a unique NIJAM_SHARD_INDEX (1 to N) and the shared NIJAM_SHARD_TOTAL (N). Nijam then knows the total, so the run auto-completes once all N jobs report and each job’s tests are stamped with its machine, no summary job needed. Native --shard always wins over these vars, so they only apply to a manual split.

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - { specs: "cart.spec.ts checkout.spec.ts", index: 1 }
          - { specs: "billing.spec.ts search.spec.ts", index: 2 }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test ${{ matrix.specs }}
        env:
          NIJAM_API_KEY: ${{ secrets.NIJAM_API_KEY }}
          NIJAM_SHARD_INDEX: ${{ matrix.index }} # 1-based, unique per job
          NIJAM_SHARD_TOTAL: "2" # number of jobs

The fallback when you can’t assign per-job shard indices: NIJAM_AUTO_COMPLETE=false stops every job finalizing, and a final summary job completes the run once - pass the CI run id the jobs shared (GITHUB_RUN_ID) so it targets the right run.

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        spec: [cart, checkout, billing, search] # one spec per job
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test ${{ matrix.spec }}.spec.ts
        env:
          NIJAM_API_KEY: ${{ secrets.NIJAM_API_KEY }}
          NIJAM_AUTO_COMPLETE: "false" # don't finalize per job

  summary:
    needs: [test] # after every spec job
    if: always() # complete even if some failed
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -sf -X POST "https://api.nijam.dev/v1/runs/complete" \
            -H "Authorization: Bearer ${{ secrets.NIJAM_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "{\"projectId\":\"<your-project-id>\",\"ciRunId\":\"$GITHUB_RUN_ID\",\"ciRunAttempt\":\"$GITHUB_RUN_ATTEMPT\"}"

parallel + --shard is auto-detected, same as GitHub - no completion step. (For a spec-per-job matrix on GitLab, set NIJAM_AUTO_COMPLETE=false and add a needs: [e2e] job that POSTs to /v1/runs/complete with ciRunId=$CI_PIPELINE_ID.)

e2e:
  parallel: 4
  image: mcr.microsoft.com/playwright:latest
  script:
    - npm ci
    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
  variables:
    NIJAM_API_KEY: $NIJAM_API_KEY

Only the manual-complete fallback calls /v1/runs/complete, and its ciRunId must equal the value the jobs sent - the same one the reporter detects (GITHUB_RUN_ID, CI_PIPELINE_ID, …), shared across every job in the run. On providers whose CI run id is job-level (e.g. CircleCI’s CIRCLE_BUILD_NUM), pass the shared workflow id through to the final step instead. Single-job, --shard, and NIJAM_SHARD_* runs need none of this - they complete on their own.

Other CI systems

On a provider not listed above, set the generic variables and the reporter picks them up:

Variable	Maps to
`COMMIT_SHA`	commit
`BRANCH`	branch
`CI_RUN_ID`	CI run id
`CI_URL`	CI run URL

If none are set, the reporter still falls back to git, so local runs are attributed too. The full variable list lives in the CI variables reference.

What you need to push runs

To send runs and reports to Nijam, the reporter needs two things - set both in playwright.config.ts:

projectId - which project to push to. Not a secret; it just identifies the project.
apiKey - the only secret. Store it as NIJAM_API_KEY in your CI secrets and reference it via the environment.

Everything else - commit, branch, PR, CI link, author - is detected automatically.