# Testing reference The Playwright fixture and account helpers from `deepspace/testing`. ```ts import { test, expect, loadAllTestAccounts, pickTestAccounts, findTestAccountByName, ensureStorageState, newSignedInContext, getStatePathForEmail, } from 'deepspace/testing' import type { MultiplayerUser, UsersFixture, TestAccount, EnsureStorageStateOptions, } from 'deepspace/testing' ``` Imported only inside Playwright spec files. ## `test` and `expect` Re-exports from Playwright with the `users` fixture pre-installed: ```ts import { test, expect } from 'deepspace/testing' test('A sends, B sees', async ({ users }) => { const [alice, bob] = await users(2) // ... }) ``` The fixture caches `storageState` per account and app origin, so each test account signs in once per target app - not once per test. A cached file is validated against the app before reuse (a session probe plus an identity match, once per worker process); a missing, dead, or wrong-account state triggers one fresh sign-in that overwrites it, so a stale cache can never silently sign a test in as the wrong user or against the wrong origin. **Requires `baseURL`** in `tests/playwright.config.ts`. The scaffold sets this; tests error with `users fixture requires a baseURL` if it's missing. ## `users(N | string[], options?)` - the fixture ```ts type UsersFixture = ( selector: number | string[], options?: { label?: string }, ) => Promise interface MultiplayerUser { context: BrowserContext page: Page email: string name: string /** Test account user ID, if known from the accounts registry. */ userId?: string } ``` ```ts // First N accounts by createdAt const [a, b] = await users(2) // Specific accounts by name const [alice, bob] = await users(['Alice', 'Bob']) // First N filtered by label const [team] = await users(1, { label: 'team-fixture' }) ``` Contexts auto-close when the test finishes - no manual cleanup needed for contexts. You still need to clean up records you create during the test (see [Testing guide → Test data cleanup](/guides/testing#test-data-cleanup)). ## Escape hatches When the fixture is too high-level, import the underlying helpers directly: | Helper | Signature | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `loadAllTestAccounts()` | `() => TestAccount[]` - every cached account (sync) | | `pickTestAccounts(n, opts?)` | `(n: number, opts?: { label?: string }) => TestAccount[]` (sync); throws if not enough accounts | | `findTestAccountByName(name)` | `(name: string) => TestAccount` (sync); throws if not found | | `ensureStorageState(browser, account, baseURL, options?)` | Sign in once and return the cached `storageState` path | | `newSignedInContext(browser, account, baseURL, options?)` | One-liner for a signed-in `BrowserContext` | | `getStatePathForEmail(email, baseURL)` | Direct cache-path lookup, keyed by account and app origin | All three account loaders read from `~/.deepspace/test-accounts.json` synchronously - they don't return promises. ### `TestAccount` ```ts interface TestAccount { email: string password: string name?: string label?: string | null id?: string userId?: string createdAt?: number } ``` Loaded from `~/.deepspace/test-accounts.json`, populated by `npx deepspace test accounts create`. `createdAt` is a numeric epoch millisecond timestamp, not an ISO string. ### `EnsureStorageStateOptions` ```ts interface EnsureStorageStateOptions { /** Force a fresh sign-in even if a cached state validates. */ force?: boolean } ``` Reuse is gated by validation, not by file age - there is no `maxAgeMs`. A cached state is reused only when it still authenticates as the right account against the target origin; otherwise it is refreshed regardless of how recently it was written. ### `ensureStorageState` / `newSignedInContext` signatures ```ts function ensureStorageState( browser: Browser, account: { email: string; password: string }, baseURL: string, options?: EnsureStorageStateOptions, ): Promise function newSignedInContext( browser: Browser, account: { email: string; password: string }, baseURL: string, options?: EnsureStorageStateOptions, ): Promise ``` `browser` is always the first argument, then the account record, then `baseURL`, then options. ## Patterns ### Multiplayer test ```ts import { test, expect } from 'deepspace/testing' test('shared state syncs', async ({ users }) => { const [a, b] = await users(2) await a.page.goto('/board') await b.page.goto('/board') await a.page.getByTestId('add-card-btn').click() await a.page.getByTestId('card-title-input').fill('Hello') await a.page.getByTestId('save-card-btn').click() await expect(b.page.getByText('Hello')).toBeVisible() }) ``` ### Reusing a signed-in context outside the fixture ```ts import { test } from '@playwright/test' import { ensureStorageState, loadAllTestAccounts } from 'deepspace/testing' test('custom flow', async ({ browser }) => { const accounts = loadAllTestAccounts() const statePath = await ensureStorageState(browser, accounts[0], 'http://localhost:5173') const context = await browser.newContext({ storageState: statePath }) // ... use context.newPage(), etc. await context.close() }) ``` ## See also * [Testing guide](/guides/testing) - full workflow, test extension checklist, debugging * [CLI test command](/cli-reference/commands#test) - runner flags * [CLI `test accounts` command](/cli-reference/commands#test-accounts) - provisioning the account pool