# Testing Utilities
URL: /runtime/api/testing



`@taucad/runtime-testing` provides a real in-process [`RuntimeClient`](/runtime/api/client) harness, Vitest-backed mocks, glTF inspection, and geometry assertions. Install it as a development dependency; Vitest and `@taucad/runtime` are required peers.

```bash
npm install -D @taucad/runtime-testing vitest
```

## Types [#types]

**`GeometryExpectation`** — Expected geometry properties for test assertions.

- **`vertexCount`** (`number`, required) — Total number of vertices across all meshes
- **`faceCount`** (`number`, required) — Total number of faces (triangles) across all meshes
- **`meshCount`** (`number`, required) — Number of meshes in the geometry
- **`boundingBox`** (`{ size: [number, number, number]; center: [number, number, number]; tolerance?: number; }`, required) — Bounding box dimensions and position

## Runtime Harnesses [#runtime-harnesses]

| Function                     | Description                                                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `createTestRuntimeClient`    | Create a real client over `inProcessTransport` with an isolated in-memory filesystem                                           |
| `createTestGeometry`         | Render one fixture with the runtime's typed `open` request and optional named-view callback; close the client before returning |
| `getTestParameters`          | Resolve one fixture's parameter schema through a temporary client and shut it down afterward                                   |
| `describeBundlerConformance` | Run the shared bundler conformance suite against a custom bundler definition                                                   |

Callers own clients returned by `createTestRuntimeClient` and must call `shutdown()`. The two convenience helpers own and close the clients they create.

## Runtime Mocks and Assertions [#runtime-mocks-and-assertions]

| Function                          | Description                                                       |
| --------------------------------- | ----------------------------------------------------------------- |
| `createMockLogger`                | Create a Vitest-backed runtime logger                             |
| `createMockFileSystem`            | Create a configurable kernel filesystem                           |
| `createMockKernelRuntime`         | Create a direct kernel-definition runtime                         |
| `createMockRuntime`               | Create a middleware runtime with filesystem, state, and hashes    |
| `createMockRuntimeClient`         | Create an explicit `RuntimeClient` mock                           |
| `createMockDependencies`          | Create standard dependency records                                |
| `createMockCreateGeometryHandler` | Create a middleware geometry handler                              |
| `createMockGetParametersHandler`  | Create a middleware parameter handler                             |
| `createErrorResult`               | Create a failed geometry result                                   |
| `assertSuccess` / `assertFailure` | Assert and narrow a kernel result                                 |
| `assertRenderingSuccess`          | Assert and narrow a public document rendering                     |
| `createMockInput`                 | Create a middleware geometry request                              |
| `createGeometryFile`              | Create a normalized file locator for direct definition unit tests |

## Geometry Validation [#geometry-validation]

`validateGlbData`, `glbToDocument`, `getInspectReport`, `getGeometryStatsFromInspect`, and `getBoundingBoxFromInspect` inspect binary glTF. `extractGltfFromResult`, `extractGltfFromExportResult`, `createGeometryTestHelpers`, `createGeometryVariant`, and `getSignedVolumeFromGlb` work over runtime results, alongside shared color, coordinate, and naming assertions.

## Usage [#usage]

```typescript
import { afterEach, describe, expect, it } from 'vitest';
import { esbuild } from '@taucad/esbuild';
import { replicad } from '@taucad/replicad';
import { assertRenderingSuccess, createGeometryTestHelpers, createTestRuntimeClient } from '@taucad/runtime-testing';
import { defineRuntime } from '@taucad/runtime/worker';

const runtime = defineRuntime({
  plugins: [replicad({ kernels: { default: { wasm: 'single' } } }), esbuild()],
});

describe('kernel test', () => {
  const clients = new Set<ReturnType<typeof createTestRuntimeClient>>();

  afterEach(async () => {
    await Promise.all([...clients].map((client) => client.shutdown()));
    clients.clear();
  });

  it('renders geometry through the production client path', async () => {
    const client = createTestRuntimeClient({
      runtime,
      files: {
        'main.ts': `
          import { makeBaseBox } from 'replicad';
          export default () => makeBaseBox(10, 20, 30);
        `,
      },
    });
    clients.add(client);

    const document = client.open({ source: { path: 'main.ts' } });
    const view = document.view('model');
    const outcome = await view.rendering();
    expect(outcome.superseded).toBe(false);
    if (outcome.superseded) return;

    assertRenderingSuccess(outcome.rendering);
    await createGeometryTestHelpers().expectValidGltf(outcome.rendering);
    view.close();
    document.close();
  });
});
```

## Related [#related]

* [Test Kernels](/runtime/guides/testing-kernels)
* [Create a Custom Kernel](/runtime/guides/custom-kernel)
* [Create Custom Middleware](/runtime/guides/custom-middleware)