Testing

Relevant source files

• packages/aikit/test/agent.instance.test.ts
• packages/aikit/test/loop.test.ts
• packages/aikit/test/public.api.test.ts

The aikit package employs a comprehensive test suite designed to validate the integrity of AI agent lifecycles, provider abstractions, and message normalization. Testing is performed using the vite-plus/test runner, which provides a high-performance environment for executing unit and integration tests across the monorepo.

Testing Architecture

The testing strategy focuses on isolating internal logic from external network dependencies. By mocking the global fetch and providing local model catalogs, the suite ensures that tests are deterministic and can run in offline environments.

Test Runner and Environment

Tests are executed via the vite-plus/test utility packages/aikit/test/loop.test.ts1 The environment is configured to point to a local model catalog using the CODEWORK_AIKIT_MODELS_PATH environment variable, which is resolved via a utility helper packages/aikit/test/agent.instance.test.ts10-11

Network Isolation Pattern

To prevent accidental API calls to LLM providers during testing, the suite frequently mocks globalThis.fetch packages/aikit/test/public.api.test.ts4-15 This pattern is combined with custom stream simulators like AssistantMessageEventStream to verify how the system reacts to various LLM response patterns, including text deltas and tool calls packages/aikit/test/loop.test.ts78-100

System-to-Code Mapping

The following diagram maps high-level testing concepts to the specific code entities used to implement them.

Testing Entity Map

Sources: packages/aikit/test/public.api.test.ts4-15 packages/aikit/test/loop.test.ts78-100 packages/aikit/test/loop.test.ts144-179 packages/aikit/test/agent.instance.test.ts10-11

Test Infrastructure and Utilities

The test suite relies on a set of shared utilities located in packages/aikit/test/utils/ to maintain consistency across test files. These include:

• Tool Fixtures: Standardized tool definitions (e.g., calculator) used to test tool call generation and execution.
• Validators: Custom matchers for verifying the structure of ToolCall and AssistantMessage objects.
• Path Resolvers: Utilities like ROOT_MODELS_PATH that ensure the test runner can locate the offline models.json for model registry testing.

For details, see Test Infrastructure and Utilities.

Test Coverage by Module

The codebase is partitioned into distinct test files that target specific subsystems of the aikit package:

Test File	Focus Area	Key Entities Tested
loop.test.ts	Stateless execution engine	Loop.run, Loop.runContinue
agent.instance.test.ts	Stateful agent management	Agent.Instance, Agent.create
stream.test.ts	Provider registration & streaming	Stream.registerProtocolProvider
llm.test.ts	Model resolution & registry	llm() facade, Model.registry
public.api.test.ts	Package exports & entrypoints	aikit namespace exports

For details, see Test Coverage by Module.

Agent Lifecycle Testing

A significant portion of the test suite is dedicated to the Loop.run orchestration. This includes verifying the sequence of events emitted during an agent turn, such as agent.start, turn.start, and tool-specific events like tool.execution.start packages/aikit/test/agent.instance.test.ts163-185

Agent Event Flow Validation

Sources: packages/aikit/test/loop.test.ts181-235 packages/aikit/test/agent.instance.test.ts163-185