test

pnpm sonamu test 명령어는 실행 중인 dev 서버의 Vitest 인스턴스를 통해 테스트를 실행합니다. dev 서버가 이미 로드한 모듈을 재사용하므로 매번 초기화하는 pnpm test보다 빠르게 피드백을 받을 수 있습니다.

전제조건

이 명령어를 사용하려면 두 가지가 필요합니다:

sonamu.config.ts에서 devRunner 활성화
pnpm dev로 dev 서버가 실행 중

sonamu.config.ts 설정

api/src/sonamu.config.ts

export default defineConfig({
  // ... 다른 설정
  test: {
    devRunner: {
      enabled: true,
      routePrefix: "/__test__",            // 선택, 기본값
      vitestConfigPath: "vitest.config.ts", // 선택, api-root 상대경로
    },
  },
});

설정 옵션

옵션	타입	기본값	설명
`enabled`	`boolean`	`false`	DevRunner 활성화 여부
`routePrefix`	`string`	`"/__test__"`	테스트 엔드포인트 경로 접두사
`vitestConfigPath`	`string`	-	vitest.config.ts 경로 (api-root 상대경로)

기본 사용법

# 전체 테스트 실행
pnpm sonamu test

# 특정 파일 실행
pnpm sonamu test src/application/user/user.test.ts

# 이름 패턴으로 필터링
pnpm sonamu test --pattern "findMany"

# 파일 + 패턴 조합
pnpm sonamu test src/application/user/user.test.ts --pattern "findById"

# trace 정보와 함께 출력
pnpm sonamu test --traces

# DevRunner 상태 확인
pnpm sonamu test --status

옵션

옵션	단축	설명
`--pattern <이름>`	`-p <이름>`	테스트 이름 패턴으로 필터링
`--traces`	`-t`	테스트에서 수집된 trace 정보를 출력
`--status`	`-s`	DevRunner 상태를 확인하고 종료

파일 경로는 여러 개를 지정할 수 있습니다:

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

Trace 출력

--traces (-t) 옵션을 사용하면 테스트 실행 중 Naite.t()로 수집된 trace 정보를 결과와 함께 출력합니다. 각 trace는 키, 소스 위치, 값을 포함합니다.

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"}]

테스트 코드에서 Naite.t()를 사용하여 trace를 기록할 수 있습니다:

import { Naite } from "sonamu";

// 테스트 또는 모델 코드 내에서
Naite.t("query", sqlString);
Naite.t("result", rows);

동작 원리

pnpm sonamu test는 dev 서버 내부에 상주하는 Vitest 인스턴스를 HTTP 요청으로 호출합니다.

CLI가 dev 서버의 /__test__/run 엔드포인트에 POST 요청을 보냅니다.
dev 서버의 DevVitestManager가 상주 Vitest 인스턴스로 테스트를 실행합니다.
결과를 JSON으로 반환하면 CLI가 요약을 출력합니다.

`pnpm test`와의 비교

	`pnpm test`	`pnpm sonamu test`
서버 필요	불필요	`pnpm dev` 실행 중 필요
실행 속도	매번 초기화	Vitest 인스턴스 재사용 (빠름)
HMR 연동	없음	코드 변경 즉시 반영
용도	CI, 전체 테스트	개발 중 빠른 피드백

언제 어떤 것을 사용하나요?

개발 중: pnpm sonamu test로 빠르게 피드백을 받으세요. 코드를 수정하고 바로 테스트를 실행할 수 있습니다.
CI/CD: pnpm test를 사용하세요. 독립적인 환경에서 전체 테스트를 실행합니다.

상태 확인

CLI에서 --status 플래그를 사용하거나 HTTP 엔드포인트에 직접 요청하여 DevRunner 상태를 확인할 수 있습니다:

# CLI로 확인
pnpm sonamu test --status

# 또는 HTTP 엔드포인트에 직접 요청
curl http://localhost:3000/__test__/status

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

필드	설명
`ready`	Vitest 인스턴스가 준비되었는지 여부
`running`	현재 테스트가 실행 중인지 여부
`lastRunAt`	마지막 테스트 실행 시각
`sseAvailable`	SSE(Server-Sent Events) 실시간 스트리밍이 사용 가능한지 여부

문제 해결

dev 서버에 연결할 수 없는 경우

dev 서버에 연결할 수 없습니다. sonamu dev가 실행 중인지 확인하세요

해결: pnpm dev로 dev 서버를 먼저 시작하세요.

devRunner가 활성화되지 않은 경우

devRunner가 활성화되지 않았습니다. sonamu.config.ts에서 test.devRunner.enabled: true 설정이 필요합니다

해결: sonamu.config.ts의 test.devRunner.enabled를 true로 설정하고 dev 서버를 재시작하세요.

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

전제조건

sonamu.config.ts 설정

설정 옵션

기본 사용법

옵션

Trace 출력

동작 원리

`pnpm test`와의 비교

상태 확인

문제 해결

dev 서버에 연결할 수 없는 경우

devRunner가 활성화되지 않은 경우

다음 단계

테스트 구조

dev

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​전제조건

​sonamu.config.ts 설정

​설정 옵션

​기본 사용법

​옵션

​Trace 출력

​동작 원리

​pnpm test와의 비교

​상태 확인

​문제 해결

​dev 서버에 연결할 수 없는 경우

​devRunner가 활성화되지 않은 경우

​다음 단계

테스트 구조

dev

전제조건

sonamu.config.ts 설정

설정 옵션

기본 사용법

옵션

Trace 출력

동작 원리

`pnpm test`와의 비교

상태 확인

문제 해결

dev 서버에 연결할 수 없는 경우

devRunner가 활성화되지 않은 경우

다음 단계