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"

โ€‹
Options

OptionShortDescription
--pattern <name>-p <name>Filter tests by name pattern
You can specify multiple file paths:
pnpm sonamu test src/application/user/user.test.ts src/application/post/post.test.ts

โ€‹
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

To check the DevRunner status on the dev server, use the /__test__/status endpoint: 
curl http://localhost:3000/__test__/status

{
  "ready": true,
  "running": false,
  "lastRunAt": "2026-02-23T10:30:00.000Z"
}
FieldDescription
readyWhether the Vitest instance is ready
runningWhether tests are currently running
lastRunAtTimestamp of the last test run

โ€‹
Troubleshooting

โ€‹
Cannot connect to dev server

dev ์„œ๋ฒ„์— ์—ฐ๊ฒฐํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. sonamu dev๊ฐ€ ์‹คํ–‰ ์ค‘์ธ์ง€ ํ™•์ธํ•˜์„ธ์š”
Solution: Start the dev server first with pnpm dev.

โ€‹
DevRunner not enabled

devRunner๊ฐ€ ํ™œ์„ฑํ™”๋˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค. sonamu.config.ts์—์„œ test.devRunner.enabled: true ์„ค์ •์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค
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