Node.jsでprocess.envをスタブ化する完全ガイド

はじめに (対象読者・この記事でわかること)

本記事は、Node.jsを利用した開発経験がある方、特に環境変数(process.env)を活用したアプリケーション開発を行っている方を対象としています。また、テスト駆動開発(TDD)やCI/CDパイプラインでのテスト実装に興味がある方にもおすすめです。

この記事を読むことで、Node.jsにおける環境変数のテスト方法を体系的に理解し、process.envを効果的にスタブ化する3つの主要な手法を実践的に習得できます。dotenvパッケージの利用から、Jest環境での設定、自前モックの実装まで、具体的なコード例を通じて、テスト環境での開発をよりスムーズに進めるための知識を提供します。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

• Node.jsの基本的な知識
• JavaScript/TypeScriptの基本的な構文
• テストフレームワーク(jestなど)の基本的な使い方

process.envとスタブ化の必要性

Node.jsにおけるprocess.envは、Node.jsプロセスの環境変数にアクセスするためのオブジェクトです。アプリケーション設定、データベース接続情報、APIキーなど、環境に依存する情報を保持するために広く利用されています。

例えば、以下のように環境変数から値を取得することができます。

const dbHost = process.env.DB_HOST || 'localhost';
const apiKey = process.env.API_KEY;

開発環境ではローカルでテストを行うため、本番環境と異なる値を設定する必要があります。また、CI/CDパイプライン上でのテストでは、環境変数を明示的に設定する必要があります。

しかし、テストコード内で直接process.envを操作することは推奨されません。なぜなら、テスト間で環境変数が共有されてしまい、テストが相互に影響を与える可能性があるからです。また、テスト環境で本番環境の情報をそのまま使うことは、セキュリティ上のリスクにもつながります。

これらの問題を解決するため、process.envをスタブ化（モック化）する手法が有効です。スタブ化により、テストごとに独立した環境変数の状態を設定でき、信頼性の高いテストを実現できます。

process.envをスタブ化する具体的な方法

ここでは、Node.jsでprocess.envをスタブ化する3つの主要な方法を紹介します。

dotenvパッケージを使う方法

最もシンプルな方法は、dotenvパッケージを使ってテスト用の環境変数ファイルをロードすることです。

ステップ1：dotenvのインストール

まず、dotenvを開発依存としてインストールします。

npm install dotenv --save-dev

ステップ2：テスト用環境変数ファイルの作成

プロジェクトルートに.env.testというファイルを作成し、テスト用の環境変数を設定します。

# .env.test
DB_HOST=test-db.example.com
DB_USER=testuser
DB_PASS=testpass
API_KEY=test-api-key

ステップ3：テスト前に環境変数ファイルをロード

テスト実行前に、dotenvを使って環境変数ファイルを読み込みます。

// test/setup.js
require('dotenv').config({ path: '.env.test' });

そして、テストフレームワークの設定ファイルで、このセットアップファイルを読み込むように設定します。

Jestの場合:

// jest.config.js
module.exports = {
  setupFiles: ['./test/setup.js']
};

Mochaの場合:

// test/mocha-setup.js
require('dotenv').config({ path: '.env.test' });

// テストの前に実行する処理
before(() => {
  // 共通のセットアップ処理
});

メリットとデメリット

メリット: - 設定ファイルを分けることで、環境ごとの管理が容易 - 実装がシンプルで理解しやすい

デメリット: - テストごとに異なる値が必要な場合には対応が難しい - ファイルのパスをハードコーディングする必要がある

jest-environment-nodeを使う方法

Jestを使っている場合、jest-environment-nodeを使うことで、テストごとに環境変数をリセットできます。

ステップ1：jest-environment-nodeのインストール

npm install --save-dev jest-environment-node

ステップ2：カスタム環境の設定

Jestの設定ファイルで、カスタム環境を指定します。

// jest.config.js
module.exports = {
  testEnvironment: 'node',
  testEnvironmentOptions: {
    env: {
      DB_HOST: 'test-db.example.com',
      DB_USER: 'testuser',
      DB_PASS: 'testpass',
      API_KEY: 'test-api-key'
    }
  }
};

ステップ3：テストコード内での利用

テストコード内では、通常通りprocess.envにアクセスできます。

test('should use test database credentials', () => {
  expect(process.env.DB_HOST).toBe('test-db.example.com');
  expect(process.env.DB_USER).toBe('testuser');
});

メリットとデメリット

メリット: - テスト環境をJestの設定ファイルで一元管理できる - テスト間で環境変数が干渉しない

デメリット: - Jestに依存する - 複雑な環境変数の設定には不向き

自前でモックを作成する方法

より柔軟な制御が必要な場合は、自前でprocess.envをモック化する方法があります。

ステップ1：テスト用のモジュール作成

テスト用の環境変数を管理するモジュールを作成します。

// test/envMock.js
const originalEnv = { ...process.env };

const mockEnv = (env) => {
  process.env = { ...originalEnv, ...env };
};

const restoreEnv = () => {
  process.env = originalEnv;
};

module.exports = {
  mockEnv,
  restoreEnv
};

ステップ2：テストコードでの利用

テストファイルで、このモジュールを利用します。

const { mockEnv, restoreEnv } = require('./test/envMock');

beforeEach(() => {
  // 各テストの前に環境変数を設定
  mockEnv({
    DB_HOST: 'test-db.example.com',
    DB_USER: 'testuser',
    DB_PASS: 'testpass',
    API_KEY: 'test-api-key'
  });
});

afterEach(() => {
  // 各テストの後に元の環境変数に戻す
  restoreEnv();
});

test('should use test database credentials', () => {
  expect(process.env.DB_HOST).toBe('test-db.example.com');
  expect(process.env.DB_USER).toBe('testuser');
});

メリットとデメリット

メリット: - 高度なカスタマイズが可能 - テストごとに異なる環境変数の設定が容易

デメリット: - 実装が少し複雑 - 元の環境変数を正しく復元する必要がある

ハマった点やエラー解決

問題1: テスト間で環境変数が共有されてしまう

症状: あるテストで環境変数を変更した後、別のテストでその変更が影響してしまう。

原因: process.envはグローバルなオブジェクトであり、テスト間で共有されている。

解決策: 各テストの前に環境変数を初期化するか、上記で紹介した自前のモックを使って、テストごとに独立した状態を維持する。

問題2: CI/CD環境での環境変数の設定がうまくいかない

症状: ローカルではテストが成功するが、CI/CD環境では失敗する。

原因: CI/CD環境では環境変数が設定されていないか、値が異なっている。

解決策: CI/CDパイプラインの設定ファイルで、必要な環境変数を明示的に設定する。また、dotenvを使ってローカルとCI/CDで共通の環境変数ファイルを使う方法も有効。

実践的な例：Expressアプリケーションでのprocess.envのスタブ化

実際のExpressアプリケーションで、process.envをスタブ化する例を見てみましょう。

アプリケーションコード

// config/database.js
const mongoose = require('mongoose');

const connectDB = () => {
  const dbUri = process.env.DB_URI || 'mongodb://localhost:27017/myapp';

  mongoose.connect(dbUri, {
    useNewUrlParser: true,
    useUnifiedTopology: true,
  })
  .then(() => console.log('MongoDB connected'))
  .catch(err => console.error('Connection error:', err));
};

module.exports = connectDB;

テストコード（自前モックを使用）

// tests/database.test.js
const { mockEnv, restoreEnv } = require('./test/envMock');
const connectDB = require('../config/database');

beforeEach(() => {
  mockEnv({
    DB_URI: 'mongodb://test-db.example.com:27017/testdb'
  });
});

afterEach(() => {
  restoreEnv();
});

test('should connect to test database', () => {
  // モックしたmongoose.connectを呼び出す
  expect(connectDB()).resolves.not.toThrow();
});

この例では、テストごとにデータベース接続先をテスト用のURIに切り替えています。これにより、本番環境のデータベースに接続することなく、テストを安全に実行できます。

まとめ

本記事では、Node.jsでprocess.envをスタブ化する3つの主要な方法を紹介しました。

• dotenvパッケージを使う方法: シンプルで環境ごとの管理が容易
• jest-environment-nodeを使う方法: Jest環境での一元管理が可能
• 自前でモックを作成する方法: 高度なカスタマイズが可能

これらの方法を使い分けることで、テスト環境での開発をよりスムーズに進めることができます。特に、自前でモックを作成する方法は、複雑なテストシナリオにも対応できるため、ぜひマスターしてください。

この記事を通して、テスト環境における環境変数の管理方法を理解し、より信頼性の高いNode.jsアプリケーション開発ができるようになったことでしょう。今後は、より高度なテスト手法や、Dockerコンテナ内での環境変数管理についても記事にする予定です。

参考資料

• Node.js公式ドキュメント - process
• dotenvパッケージ - npm
• Jest公式ドキュメント - testEnvironment
• Testing Environment Variables in Node.js