CI setup

SootSim has two distinct CI lanes:

1. Test lanes — run flows or suites, emit JUnit, upload screenshots or logs. These do not need a SootSim account.
2. Cloud preview lanes — publish shareable /preview/<id> links from CI. These require a paid plan plus a SOOTSIM_API_KEY.

GitHub Actions: test lane

name: sootsim tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: npx playwright install chromium

      - run: bun dev &
      - run: |
          for i in $(seq 1 60); do
            curl -sf http://localhost:8081 > /dev/null && break
            sleep 2
          done

      - run: npx sootsim test --flows --reporter junit

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: sootsim-test-report
          path: sootsim-results.xml

GitHub Actions: cloud preview lane

Preview uploads are different from plain test artifacts. They authenticate against SootSim cloud, so this lane requires:

• a Personal or Team plan
• a SOOTSIM_API_KEY secret

Use Personal when the lane belongs to your own repo. Use Team when the lane should draw from a shared org pool or participate in shared team workflows.

Create the key once from a signed-in machine:

sootsim keys create ci-github-actions

Then store the returned secret in GitHub Actions as SOOTSIM_API_KEY and use it in the workflow:

name: sootsim preview
on: [pull_request]

jobs:
  preview:
    runs-on: ubuntu-latest
    env:
      SOOTSIM_API_KEY: ${{ secrets.SOOTSIM_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: npx playwright install chromium

      - run: bun dev &
      - run: |
          for i in $(seq 1 60); do
            curl -sf http://localhost:8081 > /dev/null && break
            sleep 2
          done

      - run: npx sootsim flow flows/smoke.yaml --preview

Use sootsim flow --preview when the CI lane already runs a flow. If you already have a captured session plus recording artifacts, use sootsim upload --video ... --events ... instead.

Other CI systems

The same split applies outside GitHub Actions:

• test lanes only need Node, Playwright, the app dev server, and the sootsim CLI
• cloud preview lanes additionally need a paid plan and SOOTSIM_API_KEY

Output you can keep

• JUnit XML — from --reporter junit
• Screenshots — from flow capture or sootsim screenshot
• Videos — from sootsim record
• Cloud previews — from sootsim flow --preview or sootsim upload

Related

• Preview uploads & sharing
• sootsim upload
• sootsim flow