# Testing Utilities
URL: /docs/api/testing



Testing Utilities [#testing-utilities]

Use the testing API when writing unit tests for custom kernels, middleware, or kernel integration. All utilities require Vitest as a peer dependency.

Types [#types]

<TypeTable
  type={{
  "name": "GeometryExpectation",
  "description": "Expected geometry properties for test assertions.",
  "entries": [
    {
      "name": "vertexCount",
      "description": "Total number of vertices across all meshes",
      "tags": [],
      "type": "number",
      "simplifiedType": "number",
      "required": true,
      "deprecated": false
    },
    {
      "name": "faceCount",
      "description": "Total number of faces (triangles) across all meshes",
      "tags": [],
      "type": "number",
      "simplifiedType": "number",
      "required": true,
      "deprecated": false
    },
    {
      "name": "meshCount",
      "description": "Number of meshes in the geometry",
      "tags": [],
      "type": "number",
      "simplifiedType": "number",
      "required": true,
      "deprecated": false
    },
    {
      "name": "boundingBox",
      "description": "Bounding box dimensions and position",
      "tags": [],
      "type": "{ size: [number, number, number]; center: [number, number, number]; tolerance?: number; }",
      "simplifiedType": "object",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

Worker and Filesystem Utilities [#worker-and-filesystem-utilities]

| Function                     | Description                                                                                                       |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `createTestWorker`           | Create and initialize a [`KernelRuntimeWorker`](../concepts/worker-model) with kernel definition and seeded files |
| `initializeWorkerForTesting` | Initialize an existing worker with MessageChannel-based filesystem bridge                                         |
| `seedTestFileSystem`         | Seed the in-memory filesystem with files; resets to clean state first                                             |
| `clearTestFileSystem`        | Reset the in-memory filesystem to empty                                                                           |

Mock Utilities [#mock-utilities]

| Function                          | Description                                                           |
| --------------------------------- | --------------------------------------------------------------------- |
| `createMockLogger`                | Create a mock logger with vitest spy methods                          |
| `createMockFileSystem`            | Create a mock filesystem with configurable return values              |
| `createMockRuntime`               | Create a mock `KernelMiddlewareRuntime` with stubbed services         |
| `createMockRuntimeClient`         | Create a mock [`RuntimeClient`](./client) for transport-level testing |
| `createMockDependencies`          | Create mock `Dependency[]` arrays for dependency hash testing         |
| `createMockCreateGeometryHandler` | Create a mock handler for `wrapCreateGeometry` middleware tests       |
| `createMockGetParametersHandler`  | Create a mock handler for `wrapGetParameters` middleware tests        |
| `createMockResponse`              | Create a mock `Response` for HTTP-dependent kernel tests              |
| `createSuccessResult`             | Create a successful `CreateGeometryResult` for middleware tests       |
| `createErrorResult`               | Create a failed `CreateGeometryResult` for middleware tests           |
| `createMockInput`                 | Create mock `CreateGeometryInput` for middleware tests                |
| `MockKernelWorker`                | Mock worker class for unit testing middleware integration             |

Geometry Validation [#geometry-validation]

| Function                      | Description                                                  |
| ----------------------------- | ------------------------------------------------------------ |
| `validateGlbData`             | Assert GLB data has valid header and non-zero length         |
| `getInspectReport`            | Get gltf-transform inspect report from GLB data              |
| `getGeometryStatsFromInspect` | Extract vertexCount, faceCount, meshCount from report        |
| `getBoundingBoxFromInspect`   | Extract bounding box size and center from report             |
| `extractGltfFromResult`       | Extract GLB/GLTF blob from CreateGeometryResult              |
| `createGeometryVariant`       | Create a geometry variant for parametric test assertions     |
| `createGeometryTestHelpers`   | Create helpers combining validation and expectation checking |

Usage [#usage]

```typescript
import { describe, it, expect } from 'vitest';
import { createTestWorker, clearTestFileSystem, extractGltfFromResult, validateGlbData } from '@taucad/runtime/testing';
import replicadDefinition from '@taucad/runtime/kernels/replicad';

describe('kernel test', () => {
  it('renders geometry', async () => {
    const worker = await createTestWorker(replicadDefinition, {
      '/projects/test/main.ts': 'export default () => null',
    });
    const result = await worker.createGeometry({
      file: { filename: 'main.ts', path: '/projects/test' },
      parameters: {},
    });
    expect(result.success).toBe(true);
    const glb = extractGltfFromResult(result);
    if (glb) validateGlbData(glb);
    await clearTestFileSystem();
  });
});
```

Related [#related]

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