【ITニュース解説】What to do when you can't test Spinner with findByRole("status") (Jest + Chakra UI)

ソフトウェア開発において、コードが意図通りに動作するかを確認する「テスト」は非常に重要である。特にウェブアプリケーションのような複雑なシステムでは、JavaScriptのテストフレームワークであるJestと、ユーザーインターフェース（UI）部品を提供するChakra UIのようなライブラリを組み合わせてテストを行うことが一般的だ。Chakra UIの「ローディングスピナー」など、ユーザーに処理の進行状況を伝えるUI要素は、findByRole("status")というアクセシビリティのロールに基づいて要素を探す方法を用いてテストされることが多い。この方法は、要素が正しく表示され、ユーザーに情報が伝わるかを検証するために用いられる。

しかし、開発現場では予期せぬエラーに遭遇することがある。今回のケースでは、Jestでテストを実行した際に「ローディングスピナーが見つからない」というエラーが発生し、その根本原因は、開発環境とテスト環境の間で「環境変数」の扱いに違いがあったことだった。

具体的な状況として、開発者はReact、Vite、Supabaseという技術スタックを用いて学習記録アプリケーションを開発していた。ReactはUIを構築するためのJavaScriptライブラリであり、Viteは高速な開発サーバーやビルド機能を提供するフロントエンド開発ツールである。そしてSupabaseは、データベースや認証機能などを提供するバックエンドサービスだ。このような構成でアプリケーションを開発する際、テストの際にはSupabaseのような外部サービスへの実際の接続を避けるために「モック」という手法がよく用いられる。モックとは、テスト対象のコードが依存する外部のサービスやコンポーネントの代わりに、テスト用に作られた「偽物」を一時的に使うことである。これにより、テストは外部サービスの状態に左右されず、高速かつ安定して実行できるようになる。

このモックを作成する際、Supabaseクライアントの設定に、Viteが提供する環境変数の取得方法であるimport.meta.env.VITE_SUPABASE_URLやimport.meta.env.VITE_SUPABASE_ANON_KEYのような記述が使われていた。環境変数とは、データベースのURLやAPIキーといった、アプリケーションの動作に必要な設定値や機密情報をコード本体から分離して管理するための仕組みだ。Viteプロジェクトでは、これらの環境変数を.envファイルに定義し、import.meta.envを通じてコード内で利用するのが標準的な方法である。

しかし、このimport.meta.envという記述がJestを使ったテスト環境では問題を引き起こした。その理由は、import.meta.envがViteのビルド環境でのみ有効な特殊な機能であるためだ。Viteは、開発サーバーの起動時や最終的なアプリケーションのビルド時に、このimport.meta.envの値を解決して実際の環境変数に置き換える。一方、JestはNode.jsというJavaScriptの実行環境上で動作し、さらにTypeScriptで書かれたテストコードをJestで実行するためにはts-jestという変換ツールが使われる。Node.js環境はViteのビルド環境とは異なるため、Jestはimport.meta.envを理解できない。その結果、TypeScriptコードをJavaScriptに変換する「コンパイル」の段階で「コンパイルエラー」が発生し、テストが実行できなくなってしまったのだ。コンパイルエラーとは、プログラムの文法が正しくない場合や、型定義に誤りがある場合などに、ソースコードを機械が理解できる形式に変換する際に発生するエラーのことである。

この問題の解決策は、テスト専用のモックを作成する際に、Vite特有のimport.meta.envではなく、Node.js環境で一般的に利用されるprocess.envという方法で環境変数を取得するように切り替えることだった。process.envは、Node.jsアプリケーションの実行環境に設定された環境変数を取得するための標準的な方法であり、Jestが動作するNode.js環境と高い互換性を持つ。

具体的なコードの修正として、モックファイル内の環境変数の取得部分を以下のように変更した。 const supabaseUrl = process.env.VITE_SUPABASE_URL || "http://localhost:54321"; const supabaseAnonKey = process.env.VITE_SUPABASE_ANON_KEY || "mock-anon-key"; ここでは、process.env.VITE_SUPABASE_URLで環境変数を取得しようと試み、もしその変数が定義されていなければ、"http://localhost:54321"のようなローカルのモック用URLや"mock-anon-key"といったダミーの値をフォールバック（代替）として使用するようにしている。これにより、テスト環境で特定の環境変数が設定されていなくても、テストが適切に動作する柔軟性が生まれる。

さらに、Jestがテスト実行時にこれらの環境変数を正しく読み込めるように、.env.testという専用の環境変数ファイルを作成し、そこにテスト環境で必要な値を定義する。Jestは実行時に、この.env.testファイルに記述された環境変数を自動的に読み込むように設定することが可能だ。このようにprocess.envを使用し、テスト用の環境変数ファイルを適切に管理することで、開発環境とテスト環境それぞれで必要とされる環境変数を分離し、両方の環境でアプリケーションが期待通りに動作するようにできる。

今回の問題は、Viteのような最新のフロントエンドツールが提供する便利な機能と、Jestのようなテストフレームワークが動作するNode.js環境との間の、環境変数の扱いの違いが原因で発生した。開発環境とテスト環境がそれぞれ異なる特性を持つことを理解し、それぞれの環境に適した方法で環境変数を扱うことが、スムーズな開発とテストを実現するための鍵となる。特に、import.meta.envはVite環境、process.envはNode.js環境という使い分けを意識することが重要である。この知識は、システムエンジニアを目指す上で、様々な開発環境やツールを扱う際に役立つだろう。