Testing

Minara uses Vitest. The suite tests fast logic, integrated local behavior, and end-to-end flows without requiring production credentials.

Test layers

apps/agent/tests/
├── unit/          # focused logic and safety behavior
├── integration/   # local services, SQLite, CLI, and gateway boundaries
├── e2e/           # complete user and agent flows
├── fakes/         # deterministic models, servers, and test runtimes
├── helpers/       # shared fixtures and assertions
└── setup.ts       # isolated temp data directory and SQLite database

Choose the narrowest layer that proves the behavior. Unit tests are the default. Use integration tests when components need their real local boundaries. Use E2E tests when a full flow or a public surface needs coverage.

Run tests

From the repository root:

pnpm test:unit
pnpm test:e2e
pnpm --filter @minara/agent test:integration

For an individual package or a watch loop:

pnpm --filter @minara/agent test:unit
pnpm --filter @minara/agent test:watch
pnpm --filter @minara/agent exec vitest run tests/unit/core/tool-registry.test.ts

Run the focused test first. Run the affected broader layer before opening a pull request.

Test with real local boundaries

tests/setup.ts gives every test a separate temporary data directory and SQLite database. It clears the main credentials from the environment before each test. This lets tests exercise persistence and the registry without reading a developer's account or state.

Use the shared fakes instead of network mocks scattered through individual tests:

• createMockLanguageModel provides scripted model responses and records requests.
• mock-minara-server provides a local Minara-compatible HTTP surface.
• buildTestRuntime creates an AgentRuntime with only the dependencies a test needs.

New safety hooks, capability factories, skills, and routing rules should each receive focused coverage. Agent-loop changes should have an integration or E2E test that uses the real registry with deterministic model output.

Network canaries are opt-in

CI intentionally runs without production credentials. Most tests use fakes, fixtures, and local servers.

Some upstream compatibility checks exist, but they only run when you explicitly enable them. For example, external skill checks require MINARA_INTEGRATION_NETWORK=1; FMP and DefiLlama canaries also require their own E2E_*_LIVE=1 flag and API key. These checks verify upstream response shapes. They are not part of the normal test loop.

Do not add real credentials to tests, snapshots, or CI logs. Do not leave test.only in a change.

CI expectations

CI installs dependencies with the lockfile, builds shared packages, runs type checks and targeted suites, and installs Chromium for browser-dependent tests. A local failure in a browser test may mean Playwright Chromium is missing:

pnpm --filter @minara/agent exec playwright install chromium

For documentation changes, also run the docs localization and build checks described in the docs contributor guide.