instiz/core package 테스트 코드 도입

main

date

Sep 24, 2025

slug

introducing-core-package-test-code

author

status

Public

도입 목적

현재 프로젝트 구성이 모노레포(monorepo) 구조로 운영되고 있다.

그래서 총 4개의 프로젝트를 관리해야 하는데, 이 중 공용으로 사용되는 라이브러리와 유틸 함수 들은 코어(core) 패키지로 별도로 분리해서 재사용하고 있다.

문제는 이러한 공용 모듈이 여러 프로젝트에서 동시에 사용되기 때문에 하나의 변경이 다른 서비스에 예기치 못한 영향을 미칠 수 있다는 점이다.

이를 해결 하기위해 최소한의 방어책이 필요하다고 판단하였고, 단위 테스트 환경을 구축할 도입할 필요가 있다고 판단되었다.

문제 인식

함수 동작에 대한 명확한 이해 부족

여러 사람이 함께 작업하다 보면, 내가 만든 함수의 내부 동작 방식이나 반환값을 다른 팀원이 100% 이해하기 어려울 것이다. 물론 JSDoc을 활용하여 해당 함수에 대한 설명, 반환 값을 명시해 두긴 했으나 누군가가 함수 로직을 수정하게 될 경우 반환 형태가 달라질 수 있을 것 이다.

항상 동일한 Output을 보장하기 어려움

누구나 수정할 수 있기 때문에, 동일한 입력에 대해 항상 동일한 결과를 반환한다는 확신이 부족하다.

예상치 못한 로직 변경이 발생하면, 4개 서비스 전체에서 에러가 동시 다발적으로 발생할 위험이 있습니다.

유지보수 리스크

코어 패키지는 모든 프로젝트에서 공용으로 사용되기 때문에, 한 번 문제가 발생하면 모든 앱에 장애가 발생한다.

따라서 단순히 코드 리뷰나 문서화만으로는 안정성을 담보하기 어렵다고 판단하여 체계적인 테스트와 빌드 프로세스를 추가하는 것이 좀 더 견고한 서비스를 만드는 것이라고 판단

테스트 코드 작성

각 함수별로 input/output을 명확하게 검증하는 테스트 케이스를 작성

예를 들어, 날짜 유틸 함수라면 다양한 케이스(과거 날짜, 미래 날짜, 경계값 등)를 넣어 테스트

테스트 통과 → 빌드 진행

CI 파이프라인에서 테스트 스크립트를 먼저 실행

모든 테스트를 통과했을 때만 빌드를 진행하고, 빌드된 패키지를 다른 프로젝트들이 사용할 수 있도록 파이프라인 추가

jest 패키지 생성

각 프로젝트 마다 별도의 jest를 설치하는 방식 보다 공용 jest 패키지를 생성하여 해당 패키지를 사용하는 방식으로 관리하려고 한다.

근데 여기서 한 가지 문제가 발생했다. 내가 원하는건 @instiz/jest 만 설치하면 별도의 jest를 설치하지 않아도 jest 환경이 구축되는 것이다.

근데 jest 환경을 읽지 못하는 문제가 발생했다. 환경 설정 파일의 경우 exports를 통해 외부 프로젝트에서 사용할 수 있지만 jest 모듈의 경우 exports가 되지 않아 사용할 수 없었다.


// @instiz/jest > index.ts
import type { Config } from 'jest';

const baseConfig: Config = { // 생략 }

export const createJestConfig = (overrides: Partial<Config> = {}): Config => ({
    ...baseConfig,
    ...overrides,
});


// package.json
{
    "name": "@instiz/jest",
    "version": "0.0.0",
    "private": true,
    "main": "./index.ts",
    "exports": {
        ".": "./index.ts"
    },
    // 생략
}

그래서 외부 프로젝트에서 사용할 jest runner 환경을 만들어주었다. @instiz/jest를 설치한 프로젝트에서 테스트 파일을 작성한 후 @instiz/jest의 runner를 통해 jest를 실행시키는 방식이다.

runner 생성


// @insitz/jest > bin > runner.cjs
const { run } = require('jest');
run();

환경설정에 runner 추가


// @instiz/jest > index.ts
import type { Config } from 'jest';

const baseConfig: Config = { // 생략 }

export const createJestConfig = (overrides: Partial<Config> = {}): Config => ({
    ...baseConfig,
    ...overrides,
});

export const jestConfig: Config = baseConfig;

export const jestSetup = () => {};

if (require.main === module) {
    const { run } = require('jest');
    run();
}

runner 환경 export


{
    "name": "@instiz/jest",
    "version": "0.0.0",
    "private": true,
    "bin": {
      "test-runner": "./bin/runner.cjs"
    },
}

외부 프로젝트에서 사용할 땐 @instiz/jest를 설치하고 기본적인 환경 설정 파일(jest.config.ts)을 생성해주고 runner를 실행시켜주면 하나의 jest 환경에서 여러 프로젝트에서 활용될 수 있다.


{
    "name": "@instiz/core",
    "version": "0.0.0",
    "types": "./dist/index.d.ts",
    "scripts": {
        "test": "test-runner",
        "test:ci": "test-runner --ci --passWithNoTests",
        "test:coverage": "test-runner --coverage"
    },
    "devDependencies": {
        "@instiz/tsconfig": "workspace:*",
        "@instiz/jest": "workspace:*",
        "@types/jest": "^29.5.0",
    },
}