[Nest.js] Fundamentals | Platform agnosticism, Testing

플랫폼 독립성

Nest는 플랫폼에 독립적인 프레임워크입니다. 이는 다양한 종류의 애플리케이션에서 재사용 가능한 로직을 개발할 수 있음을 의미합니다. 예를 들어, 대부분의 컴포넌트는 서로 다른 HTTP 서버 프레임워크 (예: Express, Fastify)는 물론, 다양한 형태의 애플리케이션 (예: HTTP 서버, 서로 다른 전송 계층을 사용하는 마이크로서비스, 웹소켓)에서도 변경 없이 재사용할 수 있습니다.

한 번 만들고 어디서든 사용하세요

문서의 Overview 섹션에서는 주로 HTTP 서버 프레임워크 (예: REST API 제공 앱, MVC 스타일의 서버사이드 렌더링 앱)를 사용하는 코딩 기법을 보여주지만, 이러한 모든 구성 요소는 마이크로서비스나 웹소켓처럼 다른 전송 계층 위에서도 사용할 수 있습니다.

 

또한, Nest는 전용 GraphQL 모듈을 제공하여 REST API 대신 GraphQL을 API 계층으로 자유롭게 사용할 수 있습니다.

 

더불어, 애플리케이션 컨텍스트 기능을 통해 CRON 작업이나 CLI 앱과 같은 다양한 Node.js 애플리케이션도 Nest 위에서 만들 수 있습니다.

 

Nest는 Node.js 애플리케이션을 위한 완전한 플랫폼이 되는 것을 목표로 하며, 높은 수준의 모듈화와 재사용성을 제공합니다. 한 번 만들고 어디서든 사용하세요!

테스트

자동화 테스트는 본격적인 소프트웨어 개발에서 필수적인 요소로 간주됩니다. 자동화를 통해 개발 중 개별 테스트나 테스트 스위트를 빠르고 쉽게 반복 실행할 수 있으며, 이를 통해 릴리스가 품질 및 성능 목표를 충족하는지 확인할 수 있습니다. 자동화는 테스트 커버리지를 높이고 개발자에게 빠른 피드백 루프를 제공해 줍니다. 이는 개발자의 생산성을 높이는 동시에, 소스 코드 커밋, 기능 통합, 버전 릴리스 등 개발 생명주기의 중요한 시점에 테스트가 실행되도록 보장합니다.

 

이러한 테스트는 단위 테스트, 통합 테스트, E2E (End-to-End) 테스트 등 다양한 유형을 포함합니다. 그 효과는 분명하지만, 초기 설정은 다소 번거로울 수 있습니다. Nest는 효과적인 테스트를 포함한 개별 모범 사례를 장려하며, 개발자와 팀이 테스트를 구축하고 자동화하는 데 도움이 되는 다음과 같은 기능들을 제공합니다:

• 컴포넌트에 대한 기본 단위 테스트 및 애플리케이션에 대한 e2e 테스트를 자동으로 스캐폴딩 합니다.
• 격리된 모듈 / 애플리케이션 로더를 구축할 수 있는 테스트 러너와 같은 기본 도구들을 제공합니다.
• Jest 및 Supertest와의 통합을 기본으로 제공하지만, 특정 테스트 도구에 종속되지 않고 유연하게 동작합니다.
• Nest의 의존성 주입 시스템을 테스트 환경에서도 사용할 수 있어, 컴포넌트 모킹이 용이합니다.

앞서 언급했듯이, Nest는 특정 테스트 프레임워크를 강제하지 않으므로 원하는 테스트 도구를 자유롭게 사용할 수 있습니다. 테스트 러너와 같은 요소만 교체하면, Nest가 제공하는 테스트 지원 기능은 그대로 활용할 수 있습니다.

설치

시작하기 위해, 필수 패키지를 설치합니다.

$ npm i --save-dev @nestjs/testing

단위 테스트

다음 예제에서는 CatsController와 CatsService 두 클래스를 테스트합니다. 앞서 언급했듯이, Jest는 기본 테스트 프레임워크로 제공되며, 테스트 러너 역할뿐만 아니라 단언 함수 (assert function), 모킹 및 스파이 등을 위한 테스트 더블 유틸리티도 제공합니다. 아래의 기본 테스트에서는 이 클래스들을 수동으로 인스턴스화하고, 컨트롤러와 서비스가 API 계약을 충실히 이행하는지를 검증합니다.

import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

describe('CatsController', () => {
  let catsController: CatsController;
  let catsService: CatsService;

  beforeEach(() => {
    catsService = new CatsService();
    catsController = new CatsController(catsService);
  });

  describe('findAll', () => {
    it('should return an array of cats', async () => {
      const result = ['test'];
      jest.spyOn(catsService, 'findAll').mockImplementation(() => result);

      expect(await catsController.findAll()).toBe(result);
    });
  });
});

힌트
테스트 파일은 테스트 대상 클래스 근처에 위치시키는 것이 좋습니다. 테스트 파일의 이름은 .spec 또는 .test 접미사를 포함해야 합니다.

 

위의 예제는 단순한 형태이기 때문에 Nest 고유의 기능을 실제로 테스트하고 있는 것은 아닙니다. 실제로 의존성 주입도 사용하지 않았습니다 (예: catsController에 CatsService 인스턴스를 직접 전달함). 이처럼 테스트 대상 클래스를 수동으로 인스턴스화하여 프레임워크와 무관하게 수행하는 테스트를 일반적으로 '격리 테스트 (isolated testing)'라고 부릅니다.

 

이제 Nest의 다양한 기능을 적극 활용하는 애플리케이션을 테스트할 수 있도록 도와주는 고급 기능들을 살펴보겠습니다.

테스트 유틸리티

@nestjs/testing 패키지는 보다 견고한 테스트를 가능하게 해 주는 유틸리티들을 제공합니다. 앞선 예제를 Nest에서 제공하는 Test 클래스를 사용하여 다시 작성해 보겠습니다.

import { Test } from '@nestjs/testing';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

describe('CatsController', () => {
  let catsController: CatsController;
  let catsService: CatsService;

  beforeEach(async () => {
    const moduleRef = await Test.createTestingModule({
        controllers: [CatsController],
        providers: [CatsService],
      }).compile();

    catsService = moduleRef.get(CatsService);
    catsController = moduleRef.get(CatsController);
  });

  describe('findAll', () => {
    it('should return an array of cats', async () => {
      const result = ['test'];
      jest.spyOn(catsService, 'findAll').mockImplementation(() => result);

      expect(await catsController.findAll()).toBe(result);
    });
  });
});

 

Test 클래스는 Nest의 전체 런타임을 모의 (mock) 하는 실행 컨텍스트를 제공하며, 클래스 인스턴스를 관리하거나 모킹/오버라이딩하기 쉽게 도와주는 훅들을 제공합니다. 이 클래스의 createTestingModule() 메서드는 @Module() 데코레이터에 전달하는 것과 동일한 모듈 메타데이터 객체를 인자로 받습니다. 이 메서드는 TestingModule 인스턴스를 반환하며, 이 인스턴스는 몇 가지 유용한 메서드를 제공합니다.

 

단위 테스트에서 중요한 메서드는 compile()입니다. 이 메서드는 의존성을 포함한 모듈을 부트스트랩하며 (일반적인 main.ts 에서 NestFactory.create()로 애플리케이션을 부트스트랩하는 방식과 유사함), 테스트할 수 있는 상태의 모듈을 반환합니다.

힌트
compile() 메서드는 비동기 함수이므로 await 키워드를 사용해 호출해야 합니다. 모듈이 컴파일된 후에는, get() 메서드를 사용하여 해당 모듈에 정의된 컨트롤러나 프로바이더와 같은 정적 인스턴스를 가져올 수 있습니다.

 

TestingModule은 ModuleRef 클래스를 상속받기 때문에, transient 또는 request-scoped와 같은 스코프가 지정된 프로바이더를 동적으로 resolve 할 수 있는 기능을 가집니다. 이러한 동적 인스턴스를 가져올 때는 get() 이 아닌 resolve() 메서드를 사용해야 합니다. get() 메서드는 정적 인스턴스만 가져올 수 있기 때문입니다.

const moduleRef = await Test.createTestingModule({
  controllers: [CatsController],
  providers: [CatsService],
}).compile();

catsService = await moduleRef.resolve(CatsService);

주의
resolve() 메서드는 해당 프로바이더의 고유한 DI 컨테이너 서브 트리로부터 새로운 인스턴스를 반환합니다. 각 서브 트리는 고유한 컨텍스트 식별자 (context identifier)를 가지므로, 이 메서드를 여러 번 호출하면 매번 서로 다른 인스턴스를 얻게 됩니다. 따라서 반환된 인스턴스를 비교하면 참조값이 서로 다름을 확인할 수 있습니다.

힌트
모듈 참조 기능에 대해 더 알고 싶다면 여기에서 확인해 보세요.

 

실제 프로바이더 (Production 용)를 사용하는 대신, 테스트 목적에 맞게 커스텀 프로바이더로 오버라이드할 수 있습니다. 예를 들어, 실제 데이터베이스에 연결하는 대신 데이터베이스 서비스를 모킹 하여 테스트할 수 있습니다. 이러한 오버라이드 기능은 다음 섹션에서 자세히 다룰 예정이지만, 단위 테스트에서도 사용할 수 있습니다.

자동 모킹

Nest는 누락된 의존성 전체에 공통적으로 적용할 수 있는 모의 (mock) 팩토리를 정의할 수 있도록 지원합니다. 이 기능은 테스트 대상 클래스에 많은 의존성이 있을 때, 일일이 모킹 하는 데 시간이 오래 걸리는 경우에 유용합니다. 이를 사용하려면 createTestingModule() 이후에 useChecker() 메서드를 체이닝 하여, 의존성 모킹을 위한 팩토리를 전달해야 합니다. 이 팩토리 함수는 선택적으로 토큰 (token)을 인자로 받을 수 있으며, 이 토큰은 Nest 프로바이더로 유효한 어떤 토큰이든 가능합니다. 팩토리 함수는 해당 토큰에 대한 모의 구현을 반환합니다. 아래는 jest-mock을 사용하여 일반적인 mocker를 생성하고, CatsService에 대해서는 jest.fn()을 활용한 특정 모킹을 적용한 예시입니다.

// ...
import { ModuleMocker, MockMetadata } from 'jest-mock';

const moduleMocker = new ModuleMocker(global);

describe('CatsController', () => {
  let controller: CatsController;

  beforeEach(async () => {
    const moduleRef = await Test.createTestingModule({
      controllers: [CatsController],
    })
      .useMocker((token) => {
        const results = ['test1', 'test2'];
        if (token === CatsService) {
          return { findAll: jest.fn().mockResolvedValue(results) };
        }
        if (typeof token === 'function') {
          const mockMetadata = moduleMocker.getMetadata(
            token,
          ) as MockMetadata<any, any>;
          const Mock = moduleMocker.generateFromMetadata(
            mockMetadata,
          ) as ObjectConstructor;
          return new Mock();
        }
      })
      .compile();

    controller = moduleRef.get(CatsController);
  });
});

 

이러한 모킹 된 인스턴스들도 일반 커스텀 프로바이더와 마찬가지로 테스트 컨테이너에서 꺼내올 수 있습니다. 예를 들어, moduleRef.get(CatsService)와 같이 호출하면 해당 모킹된 CatsService 인스턴스를 가져올 수 있습니다.

힌트
@golevelup/ts-jest의 createMock과 같은 일반적인 모의 (mock) 팩토리도 useMocker()에 직접 전달하여 사용할 수 있습니다.

힌트
REQUEST와 INQUIRER 프로바이더는 Nest 컨텍스트 내에 이미 사전 정의되어 있기 때문에 자동 모킹이 불가능합니다. 하지만, 커스텀 프로바이더 문법을 사용하거나 .overrideProvider 메서드를 활용하여 오버라이드할 수 있습니다.

End to End 테스트

단위 테스트가 개별 모듈이나 클래스에 초점을 맞춘 반면, E2E (End-to-End) 테스트는 클래스와 모듈 간의 상호작용을 더 큰 수준에서 검증하며, 이는 실제 사용자가 프로덕션 시스템과 상호작용하는 방식에 더 가깝습니다. 애플리케이션이 커질수록 각 API 엔드포인트의 E2E 동작을 수동으로 테스트하는 것은 어려워집니다. 자동화된 E2E 테스트는 시스템의 전체적인 동작이 올바르며 프로젝트 요구사항을 충족하는지를 확인하는 데 도움이 됩니다. E2E 테스트를 수행할 때는 앞서 살펴본 단위 테스트 구성과 유사한 방식을 사용합니다. 또한, Nest는 Supertest 라이브러리를 활용해 HTTP 요청을 시뮬레이션하는 작업도 쉽게 할 수 있도록 지원합니다.

import * as request from 'supertest';
import { Test } from '@nestjs/testing';
import { CatsModule } from '../../src/cats/cats.module';
import { CatsService } from '../../src/cats/cats.service';
import { INestApplication } from '@nestjs/common';

describe('Cats', () => {
  let app: INestApplication;
  let catsService = { findAll: () => ['test'] };

  beforeAll(async () => {
    const moduleRef = await Test.createTestingModule({
      imports: [CatsModule],
    })
      .overrideProvider(CatsService)
      .useValue(catsService)
      .compile();

    app = moduleRef.createNestApplication();
    await app.init();
  });

  it(`/GET cats`, () => {
    return request(app.getHttpServer())
      .get('/cats')
      .expect(200)
      .expect({
        data: catsService.findAll(),
      });
  });

  afterAll(async () => {
    await app.close();
  });
});

힌트
Fastify를 HTTP 어댑터로 사용하는 경우, 약간 다른 설정이 필요하며 자체적인 테스트 기능도 내장되어 있습니다.

let app: NestFastifyApplication;

beforeAll(async () => {
  app = moduleRef.createNestApplication<NestFastifyApplication>(
    new FastifyAdapter(),
  );

  await app.init();
  await app.getHttpAdapter().getInstance().ready();
});

it(`/GET cats`, () => {
  return app
    .inject({
      method: 'GET',
      url: '/cats',
    })
    .then((result) => {
      expect(result.statusCode).toEqual(200);
      expect(result.payload).toEqual(/* expectedPayload */);
    });
});

afterAll(async () => {
  await app.close();
});​

 

이번 예제에서는 앞에서 설명한 개념들을 확장하여 사용합니다. 이전에 사용했던 compile() 메서드에 더해, 이번에는 createNestApplication() 메서드를 사용하여 전체 Nest 런타임 환경을 인스턴스화합니다.

 

주의할 점은, compile() 메서드로 애플리케이션을 컴파일할 때는 아직 HTTP 어댑터나 서버가 생성되지 않았기 때문에 HttpAdapterHost#httpAdapter 값이 undefined 상태라는 것입니다. 따라서 테스트 중 httpAdapter가 필요하다면 createNestApplication()을 사용하여 애플리케이션 인스턴스를 생성해야 합니다. 또는 의존성 그래프를 초기화할 때 해당 의존성이 필요하지 않도록 프로젝트 구조를 리팩터링 하는 방법도 고려해야 합니다.

 

좋습니다. 예제를 하나씩 살펴봅시다:

 

우리는 실행 중인 애플리케이션에 대한 참조를 app 변수에 저장합니다. 이렇게 하면 HTTP 요청을 시뮬레이션할 수 있습니다.

 

Supertest의 request() 함수를 사용하여 HTTP 테스트를 시뮬레이션합니다. 이러한 HTTP 요청이 실행 중인 Nest 앱으로 라우팅 되도록 하려면, Nest의 기반이 되는 HTTP 리스너 (Express 플랫폼에서 제공될 수 있음)에 대한 참조를 request()에 전달합니다. 따라서 request(app.getHttpServer())라는 구문이 사용됩니다. request() 호출은 Nest 앱에 연결된 HTTP 서버를 감싼 객체를 반환하며, 이를 통해 실제 HTTP 요청을 시뮬레이션할 수 있습니다. 예를 들어, request(...).get('/cats')라는 Nest 앱으로 들어오는 실제 GET /cats 요청과 동일한 동작을 수행합니다.

 

이 예제에서는 CatsService의 대체 (테스트용) 구현도 제공합니다. 이는 하드코딩된 값을 반환하도록 설정되며, 테스트에서 그 값을 검증할 수 있습니다. 이런 대체 구현을 제공하려면 overrideProvider()를 사용합니다. Nest는 이와 유사하게 overrideModule(), overrideGuard(), overrideInterceptor(), overrideFilter(), overridePipe() 메서드를 통해 모듈, 가드, 인터셉터, 필터, 파이프도 오버라이드할 수 있도록 지원합니다.

 

이러한 override 메서드들 (단, overrideModule() 제외)은 사용자 정의 공급자 메서드에 대해 설명된 메서드를 반영하는 3가지 다른 메서드가 있는 객체를 반환합니다.

• useClass: 지정한 클래스를 인스턴스화하여 오브젝트 (프로바이더, 가드 등)를 대체합니다.
• useValue: 지정한 인스턴스를 그대로 사용하여 오브젝트를 대체합니다.
• useFactory: 인스턴스를 반환하는 함수를 제공하여 오브젝트를 대체합니다.

반면, overrideModule()은 useModule() 메서드를 반환하며, 이를 통해 기존 모듈을 다음과 같이 새로운 모듈로 대체할 수 있습니다.

const moduleRef = await Test.createTestingModule({
  imports: [AppModule],
})
  .overrideModule(CatsModule)
  .useModule(AlternateCatsModule)
  .compile();

 

각 override 메서드는 결국 TestingModule 인스턴스를 반환하므로, 다른 메서드들과 체이닝 (fluent style)으로 연결할 수 있습니다. 이런 체인을 사용할 때는 마지막에 compile()을 호출하여 Nest가 모듈을 인스턴스화하고 초기화하도록 해야 합니다.

 

또한, 테스트 실행 시 (예: CI 서버에서) 커스텀 로거를 사용하고 싶을 때도 있습니다. 이럴 때는 setLogger() 메서드를 사용하고, LoggerService 인터페이스를 만족하는 객체를 전달하여 테스트 중 로깅 방식을 지정할 수 있습니다. (기본적으로는 "error" 레벨의 로그만 콘솔에 출력됩니다.)

 

컴파일된 모듈은 다음 표에 설명된 여러 유용한 메서드를 가지고 있습니다:

createNestApplication()	주어진 모듈을 기반으로 Nest 애플리케이션 (INestApplication 인스턴스)을 생성하고 반환합니다. init() 메서드를 사용하여 애플리케이션을 수동으로 초기화해야 한다는 점에 유의하세요.
createNestMicroservice()	주어진 모듈을 기반으로 Nest 마이크로서비스 (INestMicroservice 인스턴스)를 생성하고 반환합니다.
get()	애플리케이션 컨텍스트에서 사용 가능한 컨트롤러 또는 프로바이더 (가드, 필터 등 포함)의 정적 인스턴스를 검색합니다. 모듈 참조 클래스에서 상속됩니다.
resolve()	애플리케이션 컨텍스트에서 사용 가능한 컨트롤러 또는 프로바이더 (가드, 필터 등 포함)의 동적으로 생성된 스코프 인스턴스 (request 또는 transient)를 검색합니다. 모듈 참조 클래스에서 상속됩니다.
select()	모듈의 의존성 그래프를 탐색합니다. 특정 모듈에서 인스턴스를 검색할 때 사용되며, get() 메서드의 strict 모드 (strict: true)와 함께 사용됩니다.

힌트
E2E 테스트 파일은 test 디렉터리 안에 두어야 합니다. 테스트 파일의 이름은 .e2e-spec 접미사를 가져야 합니다.

전역으로 등록된 향상자 (Enhancer) 재정의하기

전역으로 등록된 가드 (또는 파이프, 인터셉터, 필터)를 재정의하려면 몇 가지 추가 단계를 수행해야 합니다. 원래의 등록 방식은 다음과 같습니다:

providers: [
  {
    provide: APP_GUARD,
    useClass: JwtAuthGuard,
  },
],

 

이 코드는 APP_* 토큰을 통해 가드를 "멀티" 프로바이더로 등록하는 것입니다. 여기에서 JwtAuthGuard를 교체하려면, 해당 위치에 기존 프로바이더를 사용하는 방식으로 등록해야 합니다:

providers: [
  {
    provide: APP_GUARD,
    useExisting: JwtAuthGuard,
    // ^^^^^^^^ 'useClass' 대신 'useExisting'을 사용한 점에 주목하세요
  },
  JwtAuthGuard,
],

힌트
Nest가 토큰 뒤에서 인스턴스를 생성하지 않도록 하려면 useClass 대신 useExisting을 사용하여 이미 등록된 프로바이더를 참조하세요.

 

이제 JwtAuthGuard는 Nest에 일반 프로바이더로 인식되므로, TestingModule을 생성할 때 재정의할 수 있습니다:

const moduleRef = await Test.createTestingModule({
  imports: [AppModule],
})
  .overrideProvider(JwtAuthGuard)
  .useClass(MockAuthGuard)
  .compile();

 

이제 모든 테스트에서 모든 요청에 대해 MockAuthGuard가 사용됩니다.

요청 범위 인스턴스 테스트하기

요청 범위 프로바이더는 각 들어오는 요청마다 고유하게 생성됩니다. 해당 인스턴스는 요청 처리가 완료되면 가비지 컬렉션 됩니다. 이로 인해 문제가 발생하는데, 테스트된 요청을 위해 특별히 생성된 의존성 주입 하위 트리에 접근할 수 없기 때문입니다.

 

위에서 설명한 내용을 바탕으로, resolve() 메서드를 사용하여 동적으로 인스턴스화된 클래스를 검색할 수 있다는 것을 알고 있습니다. 또한 여기에서 설명한 것처럼 고유한 컨텍스트 식별자를 전달하여 DI 컨테이너 하위 트리의 생명 주기를 제어할 수 있습니다. 그렇다면 테스트 환경에서는 이를 어떻게 활용할 수 있을까요?

 

전략은 다음과 같습니다. 사전에 컨텍스트 식별자를 생성한 후, Nest가 모든 들어오는 요청에 대해 이 식별자를 사용하도록 강제하는 것입니다. 이렇게 하면 테스트된 요청에 대해 생성된 인스턴스를 검색할 수 있게 됩니다.

 

이를 위해 ContextIdFactory에 대해 jest.spyOn()을 사용합니다.

const contextId = ContextIdFactory.create();
jest
  .spyOn(ContextIdFactory, 'getByRequest')
  .mockImplementation(() => contextId);

 

이제 contextId를 사용하여 이후의 모든 요청에 대해 생성된 DI 컨테이너 하위 트리 하나에 접근할 수 있습니다.

catsService = await moduleRef.resolve(CatsService, contextId);

Reference

• Nest.js | Platform agnosticism
• Nest.js | Testing