Agent? Fetch sharkmagic.si/docs/llms.txt or this page as markdown
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); 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#
- One Space per pipeline, prepared once. A first command checks out the commit and installs dependencies
(
git clone,npm ci,npx playwright installwithin the egress policy). That Space's files are the checkout every shard reads. - 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. - One VM per shard command.
npx playwright test --shard=i/Nruns in its own lease. Shards start as a burst. - 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. - Collect and drop. The CI job reads exit codes and outputs from the exec responses, copies reports out, and deletes the shard Spaces.
# 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.