Skip to main content
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:
  1. Enable devRunner in sonamu.config.ts
  2. 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

OptionTypeDefaultDescription
enabledbooleanfalseWhether to enable DevRunner
routePrefixstring"/__test__"Path prefix for test endpoints
vitestConfigPathstring-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

OptionShortDescription
--pattern <name>-p <name>Filter tests by name pattern
--traces-tShow trace information collected during tests
--status-sCheck 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.
  1. The CLI sends a POST request to the dev serverโ€™s /__test__/run endpoint.
  2. The dev serverโ€™s DevVitestManager runs the tests using the resident Vitest instance.
  3. Results are returned as JSON, and the CLI prints a summary.

โ€‹
Comparison with pnpm test

pnpm testpnpm sonamu test
Server requiredNopnpm dev must be running
Execution speedRe-initializes each timeReuses Vitest instance (fast)
HMR integrationNoneCode changes reflected immediately
Use caseCI, full test suiteQuick 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
}
FieldDescription
readyWhether the Vitest instance is ready
runningWhether tests are currently running
lastRunAtTimestamp of the last test run
sseAvailableWhether 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.

โ€‹
Next Steps

Test Structure

Learn about the Vitest-based test system

dev

Learn more about the development server