# Use case: parallel e2e (Playwright) and CI on Shark

> **Planned, not yet measured.** This is a design note. Nothing on this page has been run or measured as a CI
> workload. Only the building blocks it cites exist and are measured ([numbers.md](../numbers.md)); the end-to-end
> numbers do not exist yet.

## The problem

An e2e suite split into N shards wants N clean machines at the same moment, each with the app, its dependencies, a
browser and a database, and then wants them gone. On always-on runners you pay for the runners while they wait; on
fresh VMs you pay a boot, a checkout and a dependency install per shard.

## The design

1. **One Space per pipeline, prepared once.** A first command checks out the commit and installs dependencies
   (`git clone`, `npm ci`, `npx playwright install` within the egress policy). That Space's files are the
   checkout every shard reads.
2. **One copy per shard.** Each shard gets its own Space whose files start from the prepared one, so it can write
   freely (test artifacts, a modified `.env`) without touching the others. SharkFS is content-addressed, so a copy is
   a new reference to the same commit and only the bytes a shard writes are new.
3. **One VM per shard command.** `npx playwright test --shard=i/N` runs in its own lease. Shards start as a burst.
4. **Postgres per shard.** Each shard Space declares `[postgres] version = "17"` and gets its own database, already
   initialized, woken from a snapshot on first connection. No shared test database, no cleanup between shards.
5. **Collect and drop.** The CI job reads exit codes and outputs from the exec responses, copies reports out, and
   deletes the shard Spaces.

```sh
# sketch of the per-shard call (the copy step is the missing piece, see below)
curl -fsS -X POST "$SHARK_API/spaces/$SHARD_SPACE/exec" -H "Authorization: Bearer $SHARK_API_TOKEN" \
  -d "{\"cmd\":\"npx playwright test --shard=$I/$N\",\"op_id\":\"$PIPELINE-shard-$I\",\"timeout_s\":110}"
```

## What exists today, and what is missing

| piece | today |
|---|---|
| fresh VM per command, bursts | exists; a burst of 100 creates + first command measured (P85) |
| per-Space Postgres woken from snapshot | exists; measured with `psql` (P85 H5a) |
| exactly-once retries by `op_id` | exists |
| copy (fork) of a Space | exists in the Space library and local CLI only; **no API endpoint yet** |
| shared read-only base for many Spaces | `-base-layer`, experimental, server-wide (not per pipeline) |
| commands longer than the server's `-exec-timeout` (default 120 s) | not over the synchronous API; long suites need the timeout raised or splitting |
| getting artifacts (reports, traces, videos) out | no download endpoint; today via a command (`cat`, `base64`) or by uploading from inside the VM where egress allows |
| browsers in the lease image | not verified; depends on the guest root filesystem |
| measured end-to-end CI times | **none** |

## What would be measured (to pre-register before any claim)

Wall time of the full suite at N shards vs the same suite on the team's current runners; compute seconds billed per
pipeline; time from "pipeline starts" to "all shards running"; flake rate vs current runners; failures per 1,000
shards. Thresholds are written before the first run; until then, no performance claim about CI.