Files
deepseek-harness/packages/test-support/client-runtime/src/assembly/test-client.ts
T

365 lines
14 KiB
TypeScript

/**
* Whole-client test carrier: boots an {@link AssemblyPlan} through the
* production `bootClient` over an in-process module table, with a
* `RemoteMock` installed as the Connection carrier through `__DSH_TRANSPORT__.rpc`.
* @module @deepseek-ai/dsh-client-test-runtime/src/assembly/test-client
*/
import { Context, type Plugin } from '@deepseek-ai/cordis'
import type { Entry } from '@deepseek-ai/cordis-plugin-loader'
import { tearDownEntryFiber } from '@deepseek-ai/dsh-client-hmr/client'
import type { ClientTransportHooks, ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
import { bootClient } from '@deepseek-ai/dsh-client-web/src/boot-client.ts'
import { mountClient } from '@deepseek-ai/dsh-client-web/src/mount.ts'
import type { RemoteMock } from '@deepseek-ai/dsh-remote-mock'
import { act } from '@testing-library/react'
import { createInProcessModules, loadPluginModules } from './modules.ts'
import { assertPlan, graphFromRoster, type AssemblyPlan } from './roster.ts'
import { REMOTES_PACKAGE, remoteNamespacesOf, remoteProxiesPlugin } from './remote-proxies.ts'
/** Carrier options. */
export interface TestClientOptions {
/**
* Mount `uiRenderer` into an element (a fresh `document.body` child when `true`); requires jsdom and a roster
* that provides `uiRenderer`. Default false.
*/
readonly mount?: boolean | HTMLElement
/** Wait for `ctx.connection.state === 'connected'` before returning. Default true. */
readonly awaitConnected?: boolean
/** Readiness budget in milliseconds before `start` rejects with the mock log summary. Default 5000. */
readonly connectTimeoutMs?: number
}
/** Page global the connection plugin reads its carrier from. */
interface TransportGlobal {
__DSH_TRANSPORT__?: ClientTransportHooks
}
const transportGlobal = globalThis as TransportGlobal
/**
* Process globals every live client in this worker shares: the transport the
* `connection` plugin reads at apply, and the jsdom shims. The first holder
* installs them and remembers what was there; the last release removes the
* shims and restores the transport. A holder installs its transport for its
* own boot and for each rebuild it runs, both under the worker's boot turn, so
* overlapping clients and out-of-order disposal neither clobber a booting or
* rebuilding client nor leak into later tests.
*/
class SharedGlobals {
private holders = 0
private previousTransport: ClientTransportHooks | undefined
private removeShims: (() => void) | undefined
/**
* Point the transport global at `transport` for the boot or rebuild about to run; the holder must already hold.
* @param transport - carrier the next `connection` apply reads.
*/
install(transport: ClientTransportHooks): void {
transportGlobal.__DSH_TRANSPORT__ = transport
}
/**
* Hold the globals with `transport` installed.
* @param transport - carrier the next boot reads.
* @returns the release for this holder.
*/
acquire(transport: ClientTransportHooks): () => void {
if (this.holders === 0) {
this.previousTransport = transportGlobal.__DSH_TRANSPORT__
this.removeShims = installJsdomShims()
}
this.holders += 1
this.install(transport)
return () => {
this.holders -= 1
if (this.holders > 0) return
this.removeShims?.()
this.removeShims = undefined
if (this.previousTransport === undefined) delete transportGlobal.__DSH_TRANSPORT__
else transportGlobal.__DSH_TRANSPORT__ = this.previousTransport
this.previousTransport = undefined
}
}
}
const sharedGlobals = new SharedGlobals()
/**
* Boots and entry rebuilds run one at a time per worker: the transport global
* must stay the acting client's until its `connection` row applies.
*/
let bootTurn: Promise<unknown> = Promise.resolve()
/** Run `work` as the next boot turn; its failure is the caller's, never the next turn's. */
function takeTurn(work: () => Promise<void>): Promise<void> {
const turn = bootTurn.then(work)
bootTurn = turn.catch(() => undefined)
return turn
}
/** Default readiness budget; the mock answers `$events` immediately, so a miss means a boot-time fixture is absent. */
const DEFAULT_CONNECT_TIMEOUT_MS = 5_000
/**
* Browser globals jsdom lacks that roster plugins touch at apply or mount:
* client-hmr opens an `EventSource`, layout components observe element size.
* Inert stand-ins, installed only where the global is absent.
*/
const JSDOM_SHIMS: Readonly<Record<string, unknown>> = {
EventSource: class {
addEventListener(): void {}
close(): void {}
},
ResizeObserver: class {
observe(): void {}
disconnect(): void {}
},
}
/** Install a shim for each absent global; the disposer deletes exactly those. */
function installJsdomShims(): () => void {
const globals = globalThis as Record<string, unknown>
const installed = Object.keys(JSDOM_SHIMS).filter(name => globals[name] === undefined)
for (const name of installed) globals[name] = JSDOM_SHIMS[name]
return () => { for (const name of installed) Reflect.deleteProperty(globals, name) }
}
/** The Error a thrown value stands for: itself, or a new Error carrying its string form. */
function toError(error: unknown): Error {
return error instanceof Error ? error : new Error(String(error))
}
function messageOf(error: unknown): string {
return toError(error).message
}
function connectionOf(ctx: Context): ConnectionHandle {
const connection = ctx.get('connection') as ConnectionHandle | undefined
if (connection === undefined) {
throw new Error('client-test-runtime: the roster provides no `connection` service')
}
return connection
}
/** Mount point plus whether `start` created it (and so removes it on dispose). */
interface MountPoint {
readonly element: HTMLElement | undefined
readonly owned: boolean
}
function resolveMountPoint(mount: boolean | HTMLElement | undefined): MountPoint {
if (mount === undefined || mount === false) return { element: undefined, owned: false }
if (typeof document === 'undefined') {
throw new Error('client-test-runtime: mount requires a DOM; add `// @vitest-environment jsdom` to the spec')
}
if (mount === true) {
const element = document.createElement('div')
document.body.appendChild(element)
return { element, owned: true }
}
return { element: mount, owned: false }
}
/** Run `fn` inside React `act` when a DOM exists; plain await otherwise. */
async function settle(fn: () => Promise<void>): Promise<void> {
if (typeof document === 'undefined') {
await fn()
return
}
await act(async () => { await fn() })
}
async function awaitConnected(ctx: Context, mock: RemoteMock, timeoutMs: number): Promise<void> {
const { state } = connectionOf(ctx)
if (state.getSnapshot() === 'connected') return
await new Promise<void>((resolve, reject) => {
const timer = setTimeout(() => {
unsubscribe()
const unmatched = mock.log.unmatched().map(row => `${row.mode} ${row.endpoint}`)
const streams = mock.log.streams().map(row => `${row.endpoint} (${row.state})`)
reject(new Error(
`client-test-runtime: connection state is ${String(state.getSnapshot())} after ${timeoutMs}ms; `
+ `unmatched: [${unmatched.join(', ')}]; streams: [${streams.join(', ')}]`,
))
}, timeoutMs)
const unsubscribe = state.subscribe(() => {
if (state.getSnapshot() !== 'connected') return
clearTimeout(timer)
unsubscribe()
resolve()
})
})
}
/** A booted client under test. */
export class TestClient {
/**
* Load the roster's modules, then, holding this worker's boot turn, install
* the mock as the Connection carrier and the jsdom shims and boot through
* `bootClient` over the synthesized boot graph; afterwards optionally mount
* and wait for the connection. The `@deepseek-ai/dsh-api-remotes` row is
* dropped from the roster: its generated Remote clients exist only in built
* `lib/`, and the `remote.<ns>` services the roster injects (plus the
* namespaces the mock has rules for at this point) are provided as
* contract-free proxies over the same Connection instead; a `provide` entry
* for that row is refused. On any failure the context is disposed, an owned
* mount removed, and this client's hold on the globals released before the
* original error is rethrown.
* @param plan - roster and annotations.
* @param mock - Remote mock answering every Gateway call.
* @param options - mount and readiness options.
* @returns the booted client.
*/
static async start(
plan: AssemblyPlan,
mock: RemoteMock,
options: TestClientOptions = {},
): Promise<TestClient> {
assertPlan(plan)
if (plan.provide?.[REMOTES_PACKAGE] !== undefined) {
throw new Error(`client-test-runtime: ${REMOTES_PACKAGE} cannot be provided; its remote.<ns> services are the tier's proxies`)
}
const roster = plan.roster.rows.some(row => row.name === REMOTES_PACKAGE)
? plan.roster.without([REMOTES_PACKAGE])
: plan.roster
const ctx = new Context()
const transport: ClientTransportHooks = { rpc: mock.rpc }
let mountPoint: MountPoint = { element: undefined, owned: false }
let release: (() => void) | undefined
const restore = (): void => {
if (mountPoint.owned) mountPoint.element?.remove()
release?.()
}
try {
const modules = await loadPluginModules({ ...plan, roster })
mountPoint = resolveMountPoint(options.mount)
await takeTurn(async () => {
release = sharedGlobals.acquire(transport)
const system = createInProcessModules(graphFromRoster(roster.rows), modules)
ctx.plugin(remoteProxiesPlugin(remoteNamespacesOf(modules.values(), mock), mock) as unknown as Plugin)
await bootClient({ ctx, modules: system, manifest: system.manifest })
})
if (mountPoint.element !== undefined) {
if (ctx.get('uiRenderer') === undefined) {
throw new Error('client-test-runtime: mount requested, but the roster provides no `uiRenderer`')
}
await mountClient(ctx, mountPoint.element)
}
if (options.awaitConnected !== false) {
await awaitConnected(ctx, mock, options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS)
}
} catch (error) {
try {
await settle(() => ctx.fiber.dispose())
} catch {
// The boot failure is the error to report; a half-built tree failing to dispose adds nothing to it.
} finally {
restore()
}
throw error
}
return new TestClient(ctx, mock, mountPoint.element, restore)
}
private disposing: Promise<void> | undefined
private constructor(
readonly ctx: Context,
readonly mock: RemoteMock,
readonly container: HTMLElement | undefined,
private readonly restore: () => void,
) {}
/** The carrier this client's `connection` row reads when it applies. */
private get transport(): ClientTransportHooks {
return { rpc: this.mock.rpc }
}
/** The roster's Connection service (no `Context` augmentation declares it); throws when the roster provides none. */
get connection(): ConnectionHandle {
return connectionOf(this.ctx)
}
/** Flush pending React work and microtasks inside `act` (plain microtask flush without a DOM). */
async flush(): Promise<void> {
await settle(() => Promise.resolve())
}
/**
* Rebuild one Loader entry: client-hmr's registry-first fiber teardown, then `entry.refresh()`. The rebuild
* takes the worker's boot turn with this client's carrier installed, so a rebuilt `connection` row reads its
* own mock even while another client is live. Requires a live client: after `dispose()` the Loader holds no
* entries and the lookup throws before anything is installed.
* @param name - package name of the row.
*/
async reload(name: string): Promise<void> {
const entry = this.entryOf(name)
await takeTurn(async () => {
sharedGlobals.install(this.transport)
await tearDownEntryFiber(entry)
await entry.refresh()
await this.ctx.loader.await()
})
}
/**
* Remove one Loader entry and wait for its plugin cleanup.
* @param name - package name of the row.
*/
async unload(name: string): Promise<void> {
const entry = this.entryOf(name)
const disposal = entry.fiber?.dispose()
this.ctx.loader.remove(entry.id)
await disposal
}
/**
* Dispose the plugin tree, then drop an owned mount and release this
* client's hold on the shared globals even when the tree fails to dispose,
* then `mock.assertNoUnmatched()` last so its failure is the test's reason
* without skipping the cleanup; when both the tree and the check fail, one
* error carries both messages. The first call owns the teardown and reports
* its failure; every later call waits for that teardown and resolves.
*/
async dispose(): Promise<void> {
if (this.disposing !== undefined) {
await this.disposing.catch(() => undefined)
return
}
this.disposing = this.teardown()
await this.disposing
}
private async teardown(): Promise<void> {
let failure: Error | undefined
try {
await settle(() => this.ctx.fiber.dispose())
} catch (error) {
failure = toError(error)
} finally {
this.restore()
}
if (failure === undefined) {
this.mock.assertNoUnmatched()
return
}
try {
this.mock.assertNoUnmatched()
} catch (unmatched) {
throw new Error(`${messageOf(unmatched)}\nclient-test-runtime: the plugin tree also failed to dispose: ${failure.message}`, { cause: failure })
}
throw failure
}
private entryOf(name: string): Entry {
const entries = [...this.ctx.loader.entries()]
const entry = entries.find(candidate => candidate.options.name === name)
if (entry === undefined) {
throw new Error(
`client-test-runtime: no Loader entry named ${name}; entries: ${entries.map(row => row.options.name).join(', ')}`,
)
}
return entry
}
}