test

The pnpm sonamu test command runs tests through the Vitest instance hosted in the dev server. Since the dev server reuses already-loaded modules, you get faster feedback compared to pnpm test, which initializes everything from scratch each time.

Prerequisites

Two things are required to use this command:

Enable devRunner in sonamu.config.ts
Have the dev server running via pnpm dev

sonamu.config.ts Configuration

api/src/sonamu.config.ts

export default defineConfig({
  // ... other settings
  test: {
    devRunner: {
      enabled: true,
      routePrefix: "/__test__",            // optional, default
      vitestConfigPath: "vitest.config.ts", // optional, relative to api-root
    },
  },
});

Configuration Options

Option	Type	Default	Description
`enabled`	`boolean`	`false`	Whether to enable DevRunner
`routePrefix`	`string`	`"/__test__"`	Path prefix for test endpoints
`vitestConfigPath`	`string`	-	Path to vitest.config.ts (relative to api-root)

Basic Usage

# Run all tests
pnpm sonamu test

# Run a specific file
pnpm sonamu test src/application/user/user.test.ts

# Filter by test name pattern
pnpm sonamu test --pattern "findMany"

# Combine file and pattern
pnpm sonamu test src/application/user/user.test.ts --pattern "findById"

# Show trace information
pnpm sonamu test --traces

# Check DevRunner status
pnpm sonamu test --status

Options

Option	Short	Description
`--pattern <name>`	`-p <name>`	Filter tests by name pattern
`--traces`	`-t`	Show trace information collected during tests
`--status`	`-s`	Check DevRunner status and exit

You can specify multiple file paths:

pnpm sonamu test src/application/user/user.test.ts src/application/post/post.test.ts

Trace Output

Use the --traces (-t) option to display trace information collected via Naite.t() during test execution. Each trace includes its key, source location, and value.

pnpm sonamu test --traces

Tests: 3 passed, 0 failed, 3 total
Duration: 245ms

Traces:
  UserModel.findMany
  user.test.ts

    [query] user.model.ts:42
    SELECT * FROM users WHERE ...

    [result] user.model.ts:45
    [{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]

You can record traces in your test or model code using Naite.t():

import { Naite } from "sonamu";

// Inside test or model code
Naite.t("query", sqlString);
Naite.t("result", rows);

How It Works

pnpm sonamu test invokes the resident Vitest instance inside the dev server via an HTTP request.

The CLI sends a POST request to the dev server’s /__test__/run endpoint.
The dev server’s DevVitestManager runs the tests using the resident Vitest instance.
Results are returned as JSON, and the CLI prints a summary.

Comparison with `pnpm test`

	`pnpm test`	`pnpm sonamu test`
Server required	No	`pnpm dev` must be running
Execution speed	Re-initializes each time	Reuses Vitest instance (fast)
HMR integration	None	Code changes reflected immediately
Use case	CI, full test suite	Quick feedback during development

When to use which?

During development: Use pnpm sonamu test for quick feedback. You can modify code and immediately run tests.
CI/CD: Use pnpm test. It runs the full test suite in an isolated environment.

Status Check

You can check DevRunner status using the --status flag in the CLI or by sending a request directly to the HTTP endpoint:

# Check via CLI
pnpm sonamu test --status

# Or request the HTTP endpoint directly
curl http://localhost:3000/__test__/status

{
  "ready": true,
  "running": false,
  "lastRunAt": "2026-02-23T10:30:00.000Z",
  "sseAvailable": true
}

Field	Description
`ready`	Whether the Vitest instance is ready
`running`	Whether tests are currently running
`lastRunAt`	Timestamp of the last test run
`sseAvailable`	Whether SSE (Server-Sent Events) real-time streaming is available

Troubleshooting

Cannot connect to dev server

dev 서버에 연결할 수 없습니다. sonamu dev가 실행 중인지 확인하세요
(Cannot connect to the dev server. Please check that sonamu dev is running.)

Solution: Start the dev server first with pnpm dev.

DevRunner not enabled

devRunner가 활성화되지 않았습니다. sonamu.config.ts에서 test.devRunner.enabled: true 설정이 필요합니다
(devRunner is not enabled. You need to set test.devRunner.enabled: true in sonamu.config.ts)

Solution: Set test.devRunner.enabled to true in sonamu.config.ts and restart the dev server.

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Prerequisites

sonamu.config.ts Configuration

Configuration Options

Basic Usage

Options

Trace Output

How It Works

Comparison with `pnpm test`

Status Check

Troubleshooting

Cannot connect to dev server

DevRunner not enabled

Next Steps

Test Structure

dev

​Prerequisites

​sonamu.config.ts Configuration

​Configuration Options

​Basic Usage

​Options

​Trace Output

​How It Works

​Comparison with pnpm test

​Status Check

​Troubleshooting

​Cannot connect to dev server

​DevRunner not enabled

​Next Steps

Test Structure

dev

Prerequisites

sonamu.config.ts Configuration

Configuration Options

Basic Usage

Options

Trace Output

How It Works

Comparison with `pnpm test`

Status Check

Troubleshooting

Cannot connect to dev server

DevRunner not enabled

Next Steps