Show HN: Suites – TypeScript 백엔드를 위한 현대적인 단위 테스트 프레임워크

제어 역전(Inversion of Control) 및 의존성 주입(Dependency Injection)을 사용하여 작동하는 TypeScript 백엔드용 단위 테스트 프레임워크

의존성 주입 프레임워크: NestJS (공식), InversifyJS (공식)

테스트 라이브러리: Jest, Vitest, Sinon

Suites를 사용해 보셨나요? 경험을 공유하고 Suites의 미래를 함께 만들어 주세요.

선언적(Declarative)- 단일 명세(specification)로부터 완전히 타입이 지정되고 격리된 테스트 환경을 정의하기 위한 선언적 API를 제공하며, 여기에는 자동 목(mock) 생성 및 생성자 메타데이터 기반의 의존성 배선(dependency wiring)이 포함됩니다.

안전한 리팩토링(Type-Safe Refactoring)- 목을 구체적인 TypeScript 구현에 연결하여 생성자, 주입된 의존성, 메서드 시그니처 변경 사항을 컴파일 시간에 검증함으로써, 실패하는 테스트가 적은 상태에서 자신감 있는 리팩토링이 가능하게 합니다.

팀 전반의 표준화된 테스트(Standardized Testing Across Teams)- NestJS, InversifyJS 및 기타 DI 설정에 걸쳐 통일된 테스트 표면을 노출하여, 근본적인 프레임워크와 관계없이 일관된 테스트 구조와 패턴을 구현할 수 있게 합니다.

AI 준비 완료(AI Ready)- LLM 기반 코딩 에이전트의 컨텍스트 요구 사항을 최소화하는 간결하고 엄격한 테스트 API를 제공하여, 더 높은 품질의 생성된 테스트, 자동 자체 수정(self-correction)을 안내하는 더 명확하고 실행 가능한 오류 메시지, 그리고 단일 패스로 테스트 작성을 완료할 가능성을 높입니다.

Solitary mode는 단일 유닛을 완전하게 격리된 상태에서 테스트합니다. 모든 의존성은 자동으로 목 처리됩니다. 다음의 경우에 사용하세요:
단일 유닛의 로직을 실제 의존성 없이 테스트하고 싶을 때.

import { TestBed, type Mocked } from '@suites/unit';
describe('User Service', () => {
let userService: UserService; // 테스트 대상 클래스
...

테스트 설정은 TestBed.solitary()를 사용하여 격리된 테스트 환경을 생성합니다:

TestBed가 클래스를 분석함- UserService의 생성자를 읽어 UserApi 및 Database 의존성을 찾습니다.
자동 목이 생성됨- UserApi 및 Database의 목 인스턴스를 생성합니다.

모든 메서드를 스텁(stubs)으로 만듭니다.
의존성 주입 (Dependencies are injected) - UserService에 목(mocks)을 자동으로 연결합니다.

생성자에서 자동 접근 (Type-safe access) - unitRef.get()을 사용하여 전체 TypeScript 지원과 함께 목을 검색할 수 있습니다.

수동으로 목을 생성할 필요가 없습니다. TestBed이 의존성 발견, 목 생성, 그리고 연결(wiring)을 자동으로 처리합니다.

TestBed.solitary()를 사용할 경우 모든 의존성이 자동으로 목 처리됩니다. 각 메서드는 미리 정의된 응답 없이 스텁이 됩니다. 필요한 경우 테스트에서 스텁 응답을 구성하세요.

// 이 스텁들은 기본적으로 반환 값이 없습니다
userApi.getRandom // 기본값으로 undefined 반환
database.saveUser // 기본값으로 undefined 반환
...

**Sociable 모드 (Sociable mode)**는 컴포넌트들이 함께 작동하는 방식을 테스트합니다. 외부 I/O가 목 처리된 상태로 유지되는 동안, 어떤 의존성을 실제(real) 상태로 유지할지 선택할 수 있습니다(.expose() 사용). 여러 유닛 간의 통합을 테스트하고 싶을 때 이를 사용하세요.

import { TestBed, type Mocked } from '@suites/unit';
describe('User Service', () => {
let userService: UserService; // 테스트 대상 클래스
...

Suites를 설치하기 전에 프로젝트가 다음 요구 사항을 충족하는지 확인하세요:

의존성 주입 프레임워크 (Dependency Injection Framework): NestJS, InversifyJS 또는 생성자 주입이 적용된 일반 TypeScript 클래스
테스트 라이브러리 (Testing Library): Jest, Vitest 또는 Sinon

먼저 Suites의 유닛 패키지를 설치하세요:

npm i -D @suites/unit
# 또는
yarn add -D @suites/unit
...

그런 다음, DI 프레임워크용 어댑터 하나와 테스트 라이브러리용 어댑터 하나를 설치하세요:

DI 프레임워크 어댑터:

NestJS - @suites/di.nestjs
InversifyJS - @suites/di.inversify

테스트 라이브러리 어댑터:

Jest - @suites/doubles.jest
Vitest - @suites/doubles.vitest

Sinon - @suites/doubles.sinon

NestJS + Jest 예시:

npm i -D @suites/doubles.jest @suites/di.nestjs
# 또는
yarn add -D @suites/doubles.jest @suites/di.nestjs
...

참고: NestJS나 Inversify를 사용하는 경우, reflect-metadata도 설치해야 합니다.

런타임 의존성(dev dependency가 아닌)으로 설치합니다: npm i reflect-metadata

전체 설치 지침은 설치 가이드(Installation Guide)를 참조하세요.

프로젝트 루트에 global.d.ts 파일을 생성하거나 테스트 디렉터리에 생성하여 적절한 TypeScript 지원을 활성화하세요:

/// <reference types='@suites/doubles.jest/unit' />
/// <reference types='@suites/di.nestjs/metadata' />

@suites/doubles.jest와 @suites/di.nestjs는 선택한 어댑터로 교체하세요.

자세한 구성 지침은 설치 가이드(Installation Guide)를 참조하세요.

Suites에 대한 기여를 환영합니다! 자세한 내용은 CONTRIBUTING.md 파일을 참고해 주세요.

프로젝트에서 Suites를 사용하고 계신가요? 팀과 회사들이 프로덕션 환경에서 Suites를 어떻게 사용하는지 공유할 수 있는 커뮤니티 토론장을 만들었습니다.

👉 토론에 참여하여 더 많은 이야기를 들려주세요 :)

여러분의 기여는 다른 사람들이 모범 사례(best practices)를 발견하고 Suites의 실제 적용 사례를 볼 수 있도록 돕습니다!

현재 Automock을 사용 중이라면, Suites로 전환하는 데 도움을 줄 포괄적인 마이그레이션 가이드(migration guide)를 만들었습니다. 이 가이드는 모든 변경 사항과 개선 사항을 다루어 업그레이드 과정을 원활하고 간단하게 만듭니다.

Suites는 Apache License, Version 2.0에 따라 라이선스됩니다.