How to Run Kane CLI Tests in Parallel

Run independent browser tests at the same time to cut total execution time. When tests run one after another, the total time is the sum of their durations. When they run in parallel, the total is only as long as the slowest test.

Parallel Suites with testrun

If your repo has committed _test.md tests, use a single testrun command instead of a shell loop. --parallel <n> sets the number of workers (default 1). The suite runs as one execution, with one exit code and one sealed evidence pack:

kane-cli testrun run --tags smoke --parallel 4                     # 4 local workers
kane-cli testrun run --tags smoke --remote --parallel 4            # a web suite on 4 grid runners

Each desktop worker gets its own isolated Chrome with a fresh temporary profile. Tests running in parallel never share cookies, logins, or tabs, and never compete for your real browser profile.
A local suite that contains any emulator or simulator test requires --parallel 1, and Kane CLI refuses larger values. Isolated Chrome workers apply to desktop tests only.
Real-device tests (target: android / target: ios) each open their own device session, so you can use --parallel locally and with --remote, up to the real devices your plan allows. Extra sessions queue for up to 15 minutes.
With --remote, --parallel N sets the job’s concurrency. The tests are split automatically across N grid runners, and each runner works through its share one test at a time. Device suites run in parallel the same way, and every task has its own VM and device.

See Batch Runs (testrun) and Remote Runs on the Cloud Grid. The rest of this page covers independent kane-cli run objectives that are not saved as _test.md files.

When to Run in Parallel

Split objectives and run in parallel when:

An objective has more than 15 steps: long objectives tend to drift off course, so split them
Tasks are independent: no shared browser state or sequential dependencies
You’re testing different features: login vs. checkout vs. settings
You’re testing different user roles: admin flow vs. customer flow

Each sub-objective must be self-contained: it navigates to its own URL, authenticates independently, and asserts its own outcomes.

Sequential Pattern

Run three tests one after another:

kane-cli run "Log in and verify dashboard" --url https://myapp.com --headless --timeout 120
kane-cli run "Search for products and verify results" --url https://myapp.com --headless --timeout 120
kane-cli run "Complete checkout and confirm order" --url https://myapp.com --headless --timeout 120

Total time: sum of all three durations.

Parallel Pattern (Shell Background Processes)

#!/bin/bash
RESULTS_DIR=$(mktemp -d)

# Start all tests in background
kane-cli run "Log in and verify dashboard" \
  --url https://myapp.com --agent --headless --timeout 120 \
  > "$RESULTS_DIR/test1.ndjson" 2>&1 &

kane-cli run "Search for products and verify results" \
  --url https://myapp.com --agent --headless --timeout 120 \
  > "$RESULTS_DIR/test2.ndjson" 2>&1 &

kane-cli run "Complete checkout and confirm order" \
  --url https://myapp.com --agent --headless --timeout 120 \
  > "$RESULTS_DIR/test3.ndjson" 2>&1 &

kane-cli run "Verify admin user management page" \
  --url https://myapp.com --agent --headless --timeout 120 \
  > "$RESULTS_DIR/test4.ndjson" 2>&1 &

# Wait for all to finish
wait

# Parse and print results
echo ""
echo "| # | Test | Status | Steps | Time | Summary |"
echo "|---|------|--------|-------|------|---------|"

i=1
for f in "$RESULTS_DIR"/test*.ndjson; do
  result=$(tail -1 "$f")
  status=$(echo "$result" | jq -r '.status')
  duration=$(echo "$result" | jq -r '.duration')
  summary=$(echo "$result" | jq -r '.one_liner')
  echo "| $i | $(basename $f .ndjson) | $status | - | ${duration}s | $summary |"
  ((i++))
done

rm -rf "$RESULTS_DIR"

Total time: duration of the longest test.

Batch Summary Format

After all tests complete, present results like this:

🧪 Test Suite: Core Flows
📅 Run at: 2026-04-14 14:30 UTC

| # | Test                   | Status | Steps | Time | Summary                        |
|---|------------------------|--------|-------|------|--------------------------------|
| 1 | Login + dashboard      | ✅     | 5     | 12s  | Welcome banner visible         |
| 2 | Product search         | ✅     | 7     | 18s  | 3 results for 'shoes'          |
| 3 | Checkout flow          | ❌     | 9     | 25s  | Payment form did not load      |
| 4 | Admin user management  | ✅     | 6     | 15s  | Users table loaded (12 rows)   |

📊 Pass rate: 3/4 (75%) · Total steps: 27 · Total time: 25s (longest test)

AI Agent Sub-Task Pattern

With an AI coding agent (Claude Code, Codex CLI, Gemini CLI), use the agent’s own parallel-task feature to start several sub-agents at once. Each sub-agent runs one Kane CLI command and returns structured results. Agent prompt template (give this to each sub-agent):

Run this Kane CLI browser test and report the results:

    kane-cli run "<objective>" --agent --headless --timeout 120

After the command completes:
1. Capture the exit code
2. Parse the run_end event (last line of stdout)
3. If status is "failed", read the failing step's screenshot from run_dir
4. Return: { status, steps, duration, summary, session_dir, failure_step, screenshot_path }

Resource Limits

Each parallel Kane CLI instance opens its own Chrome browser. Watch your machine’s resources when you run many tests in parallel:

Each instance uses ~150–300 MB RAM
4 concurrent tests = ~800 MB – 1.2 GB RAM
Each instance uses its own CDP port (9222–9230)

Start with 4 parallel tests and increase the number as your environment allows.

Always use --headless for parallel runs. Several visible browser windows are confusing and use resources for no benefit.

​Parallel Suites with testrun

​When to Run in Parallel

​Sequential Pattern

​Parallel Pattern (Shell Background Processes)

​Batch Summary Format

​AI Agent Sub-Task Pattern

​Resource Limits

Parallel Suites with testrun

When to Run in Parallel

Sequential Pattern

Parallel Pattern (Shell Background Processes)

Batch Summary Format

AI Agent Sub-Task Pattern

Resource Limits