PaperClipAI/tests/perf/collections/README.md

Tasks and Inbox cold-open checks

Run against a disposable local instance with production UI assets. The suite creates 220 unassigned backlog tasks and 110 board approvals. It does not invoke a model. The origin must be a loopback address.

pnpm --filter @paperclipai/ui build
PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:3219 \
  pnpm exec playwright test --config tests/perf/collections/playwright.config.ts

Start the isolated instance with PAPERCLIP_UI_DEV_MIDDLEWARE=false to serve the production build. The instance and its database must be disposable. These tests retain and reuse their fixture in test-results/collections/fixture.json; they only replace it when the previous company's API returns 404. Other errors fail.

The journeys check desktop and phone row budgets, incremental scrolling, retained row identity and height, shared count-only navigation, the Coordinator Inbox with Streamlined UI disabled, and the page-owned Needs You feed and Needs attention task index. Screenshots and failure traces stay in test-results. Request counts and row budgets are acceptance checks. They do not establish an end-to-end latency improvement. Measure cold, warm, and Back timings separately with the same fixture, assets, cache, viewport, and CPU/network settings.

parent-context.spec.ts holds the complete Mine response, including parent metadata, then checks row geometry through deferred visible diagnostics. Mine uses one assembled source read; it does not fetch parent or failed-task context from the browser before reveal. Recent retains its separate index/context path. startup-regressions.spec.ts covers session bootstrap and legacy fallback, partial source errors, resolved failure context, scoped 429 recovery, and archive/Undo persistence. Its authenticated session and failed-run responses are simulated transport fixtures over a real local board. They do not prove hosted login or model execution. The embedded bootstrap case holds separate company/access responses until Mine rows appear. Initial WebSocket reconciliation may request those endpoints in the background; their responses must not block the first rows. Missing or mismatched bootstrap data still requires the ordinary fallback reads. The two 429 cases keep the existing automatic backoff and Retry-After policy. They allow 45 seconds for its bounded retry window before exercising manual Retry. Other cases keep the normal short assertion timeout. Timing samples do not accelerate the browser clock.

mine-workspaces.spec.ts guards Mine against waiting on a company-wide execution-workspace list. Its fixture (workspace-fixture.ts) adds a company with 6,000 execution workspaces, 4,000 of them created for finished tasks, and 12 Mine tasks that each run in their own isolated workspace. The API cannot create execution workspaces, so this fixture writes those rows to the instance database. Set PAPERCLIP_CONFIG to the disposable instance's config.json (embedded PostgreSQL), or PAPERCLIP_COLLECTION_PERF_DATABASE_URL to its loopback database. The fixture is retained in test-results/collections/workspace-fixture.json with the same 404 rule as the main fixture. The spec routes isolated workspaces on for its own pages. It checks that Mine requests only ids-filtered workspace summaries for the workspaces its rows reference, that rows appear while those reads are held when neither the Workspace column nor workspace grouping is active, and that the Workspace column still shows each row's workspace name. Its timing case turns on the real isolated-workspaces setting, restores it, and records cold time from navigation start to the first Mine row (two frames after mount) over PAPERCLIP_COLLECTION_PERF_TIMING_RUNS runs (default and minimum 5). It records a native scenario without request interception and a separate diagnostic scenario that delays workspace reads by 3 seconds. The timings are attached evidence, not budgets.

recent-task-open.spec.ts covers opening a task from the sidebar's Recents. It gives eight fixture tasks twelve saved comments each and seeds them as the account's Recents. An idle Projects page must make exactly one issues/chat-bootstrap request (at most ten tasks) and no per-task reads. Clicking a preloaded task must show its latest comment without any of the chat's first-frame reads (core issue, recent comments, comment input facts, recent activity, recent runs, interactions, attachments, live and active run). The full detail read and the task page's other side reads still follow the first frame; the spec records them as an annotation. Its timing cases measure click to the latest comment on screen over at least 5 fresh browser contexts (empty HTTP cache and storage apart from Recents), natively and with 150 ms added to every API response. They also record the idle page's API request count. The timings are attached evidence, not budgets.

Run these focused browser checks before the full collection suite:

PAPERCLIP_COLLECTION_PERF_BASE_URL=http://127.0.0.1:<candidate-ui-port> \
  pnpm exec playwright test --config tests/perf/collections/playwright.config.ts \
  parent-context.spec.ts startup-regressions.spec.ts

To collect timings, build the pinned baseline production assets once and retain that output. Build candidate UI assets only when their inputs change. Serve both outputs from stable loopback origins. If server behavior changes, each origin must proxy its matching pinned API revision against the same disposable database. Using the candidate API for both arms proves only a UI comparison. Keep agents and external providers inactive. Neither arm may migrate or reseed the shared fixture during a comparison.

The harness checks the configured API against each UI proxy, records HTML and entry-asset SHA-256 receipts, and records both serving API revisions. Supply full source SHAs to label the client artifacts, then run:

INBOX_BASELINE_URL=http://127.0.0.1:<baseline-port> \
INBOX_CANDIDATE_URL=http://127.0.0.1:<candidate-port> \
INBOX_BASELINE_API_URL=http://127.0.0.1:<baseline-api-port> \
INBOX_CANDIDATE_API_URL=http://127.0.0.1:<candidate-api-port> \
INBOX_BASELINE_SOURCE_REVISION=<full-baseline-sha> \
INBOX_CANDIDATE_SOURCE_REVISION=<full-candidate-sha> \
  node --import ./server/node_modules/tsx/dist/loader.mjs \
  tests/perf/collections/measure-mine-context.ts

The script retains a four-parent, 30-child fixture, archives three completed parents, and enables the personal Coordinator preference. Both APIs must expose that same company. It runs five alternating pairs by default. INBOX_PAIRS, INBOX_FIXTURE_FILE, and INBOX_OUTPUT override the count and evidence paths. No request interception is used in timings. INBOX_NETWORK_LATENCY_MS accepts an integer from 0 to 2000 and defaults to 0 (native loopback). A nonzero value uses Chromium CDP network emulation on every page, with unlimited throughput and unchanged CPU. Record native and 100 ms latency runs in separate INBOX_OUTPUT files; each sample labels its scenario. CDP specifies minimum request-to-response-header latency. This controlled extra round-trip scenario tests serial request dependencies; it does not prove hosted latency or reproduce the full staging network.

By default, INBOX_HTTP_CACHE=warm warms each browser context once, then reloads the document for each initial sample. This retains HTTP cache while clearing app query state. INBOX_HTTP_CACHE=cold uses fresh browser contexts; INBOX_HTTP_CACHE=both records these scenarios separately. Warm Recent-to-Mine navigation and task-to-Mine Back retain query state. Use INBOX_HEADFUL=1 and PAPERCLIP_PLAYWRIGHT_CHANNEL=chrome when installed Chrome is the intended browser.

Initial readiness requires visible Mine rows plus two animation frames. The report retains every sample and failure, exact row membership/order, row geometry, asset identities, full API resource timings, request statuses and primary-request start. Health, session, board access, companies and preferences remain timing controls. A faster initial total alone does not attribute a gain to its final context response. The fixed post-reveal window defaults to two seconds; INBOX_TAIL_MS changes it, up to 30 seconds. Counts retain 429s and unfinished requests rather than treating them as successful work. Use the same immutable asset cache policy on both origins and stop builds and suites during timing runs.

Startup cases also check that shared collection controls do not require the task-detail bundle before reveal, even when a different organization is remembered. Code warms after the collection paints, or on task-link intent. A successful immutable response allows module preloading to compile the cached chunk without executing it. A failed fetch leaves the collection usable and permits navigation without a document reload. Direct task URLs preload their static dependencies while identity is pending. These cases must run with production assets: development modules do not exercise the bundle boundaries.

The functional cases route feature settings and delayed responses. Routing disables browser HTTP caching. For warm-cache timings, set the real local feature settings and use fresh browser contexts without request interception. Keep normal cache writes enabled so code warmed after paint can be used on the next task open. Retain intercepted runs as separate diagnostic evidence. Match the server's hashed asset cache policy (public, max-age=31536000, immutable); Vite preview's default no-cache policy adds revalidation that the shipped server does not require. Keep HTML uncached and return 404 for missing assets.