Upload runs

Three supported paths get a kensho-results/ directory into your Kaizen project:

1. Browser drag-and-drop — fastest for local testing
2. kensho push from the CLI — best for ad-hoc CI uploads
3. GitHub Action — declarative, runs on every push
4. VS Code extension — coming soon

All three call the same /v1/ingest/kensho/init + /v1/ingest/kensho/finalize endpoints. Idempotent on (workspace, project, runId).

1. Drag-and-drop in the browser

1. Open your project in Kaizen
2. Click Upload run (top right)
3. Drag the entire kensho-results/ folder, or a .zip of it, into the drop zone
4. The browser hashes attachments client-side, requests presigned URLs, uploads in parallel
5. The run appears as In progress while the worker finalizes; refresh to see it land

This path is great for one-off local runs you want to share with the team. For CI use one of the headless paths below.

2. kensho push from the CLI

Best for CI jobs and ad-hoc terminal use.

One-time login (interactive)

npx kensho login
# opens a browser, drops a token in your OS keychain

Push the latest run

npx kensho push --workspace acme --project acme-web

CI / token-based push (no browser)

KENSHO_TOKEN=krt_xxx npx kensho push --workspace acme --project acme-web --strict

| Flag | Purpose | |---|---| | --workspace / --project | Target identifiers | | --token / KENSHO_TOKEN | Skip the keychain | | --label k=v | Attach run metadata (e.g. --label release=1.4.0) — repeatable | | --dry-run | Validate + plan upload, transmit nothing | | --no-attachments | Skip uploads (fast, useful for debugging) | | --strict | Exit non-zero on any warnings — recommended for CI gates |

Full reference in CLI: kensho push.

3. GitHub Action

# .github/workflows/test.yml
name: tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22' }
      - run: pnpm install
      - run: pnpm exec playwright install --with-deps
      - run: pnpm exec playwright test
      - name: Push Kensho report to Kaizen
        if: always()
        uses: kaizenreport/kensho-action@v1
        with:
          workspace: acme
          project: acme-web
          token: ${{ secrets.KAIZEN_TOKEN }}
          strict: true

The action wraps kensho push, exposes the same flags as inputs, and adds:

• A pull-request comment with the run summary + diff vs base
• A check run with pass-rate, flake count, regressions
• An artifact with the full kensho-report/ static site

4. VS Code extension (coming soon)

Right-click any kensho-results/ folder in the VS Code explorer → Push to Kaizen. The extension reuses the same token from kensho login.

What happens server-side

For each upload:

1. The CLI reads kensho-results/run.json + cases/*.json
2. POSTs init with attachment manifest (sha256 + size). Server replies with presigned PUT URLs for any attachments not already in S3
3. Uploads attachments in parallel (existing ones are skipped)
4. POSTs finalize with the validated run.json payload
5. Server validates against the canonical Kensho v1 schema, persists the run + case_runs + step_events, computes regression vs the previous run on the same branch, enqueues post-ingest analysis (flake recompute, defect re-link, executions auto-fill), returns a summary
6. Re-pushing the same (workspace, project, runId) returns the existing internal run ID — no duplicates

A failed validation returns the exact JSON-Schema path that didn't match — fix locally with npx kensho validate.

Closing a run

Manually close a run from the project's Runs tab when the underlying CI job finishes. Closed runs become part of history and contribute to flake calculations. The CLI / GitHub Action close runs automatically once finalize succeeds — manual close is only needed for live runs that streamed in piecemeal.