1 つのツールですべてをテストすることはできるのでしょうか?開発者の夢物語のように聞こえるかもしれませんが、JavaScript のフロントエンド テスト フレームワークである Cypress を使えば、ほぼ実現できます。Selenium などの他のツールとは異なり、Cypress ならサードパーティの依存関係やパッケージを追加しなくても、すぐにテストを書き始められます。
このチュートリアルでは、Cypress を使って API をテストする方法を学びます。Cypress をセットアップし、サンプル API のテストを作成して、CircleCI を使った CI/CD パイプラインにテストを組み込みます。最後まで進めると、開発ワークフローに簡単に組み込める、API テスト自動化の堅牢なフレームワークが完成します。完成したプロジェクトは、GitHub の testing-apis-with-cypress リポジトリで公開しています。
前提条件
このチュートリアルを進めるには、以下の準備が必要です。
- JavaScript、Git、GitHub の基礎知識
- システムにインストールされた Node.js (バージョン 22 以降。Cypress 16 は Node.js 22、24、26 以降をサポートしています)
- インストールされている Node のバージョンは
node -vで確認できます
- インストールされている Node のバージョンは
- CircleCI アカウント
- GitHub アカウント
Cypress を使った API テスト
Cypress はスタンドアロンのテスト ツールです。Web アプリケーションをテストする際には、実行中の Web アプリケーションに代わって HTTP リクエストを送信します。Cypress がブラウザーからリクエストを送っているように見えるかもしれませんが、実際には JavaScript エンジンとして Node.js を使い、API サーバーに HTTP リクエストを送信しています。サーバーから受け取った応答を返すのにも Node.js を使用します。
また、Cypress はフレームワーク内から HTTP リクエストを送信するための cy.request() メソッドを公開しています。このチュートリアルでは、フロントエンド アプリケーションではなく API を Cypress でテストするために、このメソッドを使います。
ディレクトリを初期化して Cypress をセットアップする
まず、ターミナルで以下のコマンドを実行して空のディレクトリを作成し、空の Node プロジェクトを初期化します。
mkdir testing-apis-with-cypress && cd testing-apis-with-cypress
このコマンドでディレクトリを作成し、そのディレクトリに移動します。次に、デフォルト設定で Node.js プロジェクトを作成します。デフォルト設定は、チュートリアルの後半で更新します。テストは、初期化した Node プロジェクトの中に書いていきます。以下を実行します。
npm init -y
npm init -y を実行すると、デフォルト設定の Node プロジェクトが作成され、プロジェクトの package.json ファイルの内容をカスタマイズするためのプロンプトは表示されません。npm init だけを実行した場合は、Node プロジェクトのプロパティを設定するプロンプトが表示されるため、package.json ファイルの内容は異なるものになります。
ディレクトリを初期化したら、Cypress フレームワークをインストールします。Cypress は他の npm パッケージと同じ方法でインストールできるので、以下のどちらかのコマンドで開発用の依存関係としてインストールします。
npm install cypress@16.2.0 --save-dev
または:
yarn add cypress@16.2.0 --dev
Cypress のインストールが完了したら、次は Cypress フレームワークを初期化します。このプロセスで、テストを書くために必要なデフォルトの Cypress ディレクトリが作成され、必要に応じてパッケージも追加されます。
ターミナルで以下のコマンドを実行して、Cypress を起動します。
npx cypress open
新しいウィンドウが開き、最初のテストを書き始められるように設定プロセスを案内してくれます。バージョン 10 より前の Cypress は外観が異なります。詳しくは変更履歴をご覧ください。
Cypress の新しいメジャー バージョンを初めて開くと、What’s New in Cypress ページにリリースの主な変更点が表示されます。Continue をクリックします。
Welcome to Cypress! 画面では、E2E Testing と Component Testing のどちらかを選択できます。
E2E Testing をクリックすると、Cypress が内部で設定を行います。cypress.config.js や cypress/support フォルダーなど、プロジェクトに必要な設定ファイルが追加され、Configuration files ページに一覧表示されます。Continue をクリックしてデフォルトのままにします。続いてブラウザーの選択を求められるので、Chrome を選択し、Start E2E Testing in Chrome をクリックします。Electron も一覧に表示されますが、非推奨と表示されています。
初回なので、Cypress から Scaffold example specs と Create new spec のどちらかを選ぶように求められます。このチュートリアルでは Create new spec をクリックし、デフォルトのパス cypress/e2e/spec.cy.js のまま Create spec をクリックします。
Okay, run the spec をクリックします。テンプレートの spec はサンプル サイトにアクセスするもので、以下のようなウィンドウでテストが合格する様子を確認できます。
これで、Chrome ブラウザーでのエンドツーエンド テスト用に Cypress をインストールして設定できました。次のセクションでは、API の URL を設定してテストを始めます。
Cypress を使い始める
このチュートリアルでは、ユーザーの一覧を返す既存のサンプル API を使ってアプリケーションをテストします。そのためにはまず、テストで使用する API の URL (Cypress ではこれを baseUrl と呼びます) を Cypress に認識させる必要があります。
baseUrl を設定する
Cypress フレームワークでは、Cypress の初期化プロセスで生成される設定ファイル cypress.config.js がプロジェクトのルートに置かれます。cypress.config.js ファイルには指定したすべての設定変数が格納され、baseUrl もここで設定します。こうしておけば、テストを実行するたびに URL 全体を書く必要がなくなります。以下の cypress.config.js ファイルのコード スニペットのように、baseUrl にはテストに使うサンプル API を設定変数として指定します。
const { defineConfig } = require("cypress");
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
// implement node event listeners here
},
baseUrl: "https://reqres.in/api/",
},
});
reqres.in のサンプル データは API キーなしで使えますが、キーなしのデモでは 1 日あたりのリクエスト数の上限が低く設定されています。この上限のためにテストが失敗し始めた場合は、reqres.in で無料のキーを作成し、cy.request() にオプション オブジェクトを渡して x-api-key ヘッダーで送信してください。例: cy.request({ url: "/users?page=2", headers: { "x-api-key": "<your-key>" } })
実行コマンドを設定する
テスト用の URL の準備ができたので、ターミナルからテストを簡単に実行できるようにしましょう。そのために、package.json ファイルの scripts セクションにスクリプトを追加します。具体的には、以下の test コマンドを package.json ファイルの scripts セクションに追加します。
"scripts": {
"test": "npx cypress open"
},
このコマンドは、テストの実行時に Cypress をヘッドレス モードではなく、ブラウザーを開いて実行するように指示します。
package.json ファイルのスクリプトを使うと、本来ならターミナルで実行する必要があるコマンドやスクリプトを自動化できます。代わりに npm で実行でき、実行するプログラムが理解できる形にまとめられます。
最初の Cypress API テストを作成する
前述のとおり、Cypress は内部で Node を使って HTTP リクエストを送信し、その応答を Cypress に戻して、アサーションを行ったり、想定どおりの呼び出しが行われたかを検証したりします。最初のテストでは、サンプル アプリケーションに GET リクエストを送信し、想定どおりにユーザーが返されることを確認します。
その前に、cypress/e2e フォルダー内に api-tests フォルダーを作成する必要があります。cypress フォルダーは、Cypress の初期化時に自動的に生成されたものです。
api-tests フォルダー内に users.cy.js ファイルを作成します。このファイルにテストを書いていきます。ここが Cypress の優れた点で、Cypress は単体で完結しているため、API のテストに外部の依存関係は一切必要ありません。
users.cy.js ファイルを開き、ユーザーを取得する API GET リクエストのテストを設定します。以下のコードを追加します。
describe("Users api testing", () => {
it("fetches users - GET", () => {
cy.request("/users?page=2").as("usersRequest");
cy.get("@usersRequest").then((users) => {
expect(users.status).to.eq(200);
assert.isArray(users.body.data, "Users Response is an array");
});
});
});
この例では、Cypress が cy.request() メソッドに baseUrl を付加します。このメソッドはサンプル API のエンドポイントに GET リクエストを送信してユーザーの一覧を取得し、テストから API が呼び出されていることを検証します。
注: cy.request() に HTTP リクエストの操作を何も渡さなかった場合、デフォルトで GET リクエストになります。そのため、API の GET リクエストを送信することをテストで指定する必要はありません。
Cypress API テストを実行する
最初のテストを実行し、すべてが正しく動作することを確認するために、ターミナルで npm test コマンドを実行します。npm test コマンドは、先ほど package.json で定義したものです。Cypress アプリが開きます。E2E Testing をクリックし、続いて Start E2E Testing in Chrome をクリックして spec の一覧を開きます。
テストを実行するコマンドを実行すると、追加したテスト spec (ファイル) が spec の一覧に表示されます。users.cy.js を選択し、Cypress が実行する様子を確認しましょう。
Cypress アプリには、テストの実行が成功し、サンプル配列からすべてのユーザーを取得できたことが表示されます。Cypress はデフォルトでブラウザー内で実行されるため、テストから返されたすべての要素をさらに詳しく確認できます。
画面の左側で、返された配列を示す最後のアサーションをクリックします。出力がコンソールに表示されます。同じウィンドウで右クリックして [検証] を選択すると、ブラウザーの開発者ツールが開きます。Console タブをクリックすると、テストでアサーションしている項目の配列が表示されます。API とテストが正しく動作していることを確認できたので、ひとまず成功です。
さらにテストを作成して追加する
Cypress の使い方に慣れてきたら、さらにテストを追加できます。たとえば、使用しているサンプル API で、個別のユーザーを取得するテストや、新しいユーザーを作成するテストを書くことができます。
POST リクエストなど、GET 以外のリクエストでは、cy.request() で HTTP リクエストの種類を宣言する必要があります。新しいユーザーを作成する POST リクエストの body など、その他の引数もここで宣言します。以下のテストを users.cy.js の describe ブロック内に追加します。
it("creates a user - POST", () => {
cy.request("POST", "/users", { name: "morpheus", job: "leader" }).as("createUserRequest");
cy.get("@createUserRequest").then((user) => {
expect(user.status).to.eq(201);
expect(user.body).to.include({ name: "morpheus", job: "leader" });
});
});
サンプル API は 201 ステータスで応答し、id と createdAt タイムスタンプが付いた新しいユーザーを返します。ただしユーザーは保存されないため、新しいユーザーはその後の GET リクエストには表示されません。
次のセクションでは、CircleCI パイプラインを設定して、テストの自動化を始めます。
CI パイプラインを作成する
CircleCI パイプラインでテストを実行するには、ローカル プロジェクトに CircleCI の設定を追加します。まず、ルート ディレクトリに .circleci という名前のフォルダーを作成します。このフォルダー内に config.yml ファイルを作成し、以下の設定を config.yml に追加します。
version: '2.1'
orbs:
cypress: cypress-io/cypress@6.1.0
workflows:
use-my-orb:
jobs:
- cypress/run:
install-browsers: true
cypress-command: npx cypress run --e2e --browser chrome
この設定では CircleCI Orb を使用しています。Orb を使うと、CI の実行に必要なものすべてを簡単にパッケージ化できます。ここでは Cypress Orb を使うことで、設定を簡素化し、時間を節約しています。install-browsers: true でジョブのコンテナーに Chrome をインストールし、--browser chrome で、Cypress アプリで選択したのと同じブラウザーでテストを実行します。Orb が利用している設定の全体はドキュメントで確認できます。どれほど多くのセットアップが抽象化されているかがよくわかるでしょう。
Git をセットアップして CircleCI にプッシュする
テストの自動化を始める前に、CircleCI をセットアップしてプロジェクトに接続する必要があります。まず、以下のコマンドを実行してプロジェクトの Git リポジトリを初期化します。
git init
次に、ルート ディレクトリに .gitignore ファイルを作成します。このファイルに node_modules を追加して、npm で生成されたモジュールがリモート リポジトリに追加されないようにします。続いて、ここまでの作業をすべてコミットし、プロジェクトを GitHub にプッシュします。
まだアカウントをお持ちでない場合は、CircleCI アカウントを作成します。次に CircleCI にログインし、組織を選択します。
Cypress Orb はパートナー Orb であり、CircleCI はパートナー Orb を未認定 Orb として扱います。そのため、パイプラインで使用する前に、組織で未認定 Orb の使用を許可する必要があります。この設定を有効にできるのは組織の管理者です。サイドバーで Org を選択して組織の設定を開きます。サイドバーの末尾が More になっている場合、Org はその中にあります。Security を選択し、Orb Security Settings で Allow uncertified public orbs をオンにします。この設定をオンにしないと、ジョブが実行される前にパイプラインが失敗し、「Orb cypress-io/cypress@6.1.0 not loaded.」というエラーが表示されます。
次に、プロジェクトをセットアップします。手順は組織の種類によって異なります。組織の種類は、Web アプリでの組織の URL で確認できます。CircleCI GitHub App で接続された組織は /circleci/、GitHub OAuth アプリで接続された組織は /github/ または /gh/ です。
- CircleCI GitHub App で接続された組織: Home ページで Create project をクリックし、画面の指示に従って、プロジェクトに名前を付け、パイプラインを設定し、リポジトリを選択します。GitHub との接続を求められた場合は、CircleCI GitHub App をインストールし、リポジトリへのアクセスを許可します。トリガーはデフォルト (コミットのたびにパイプラインを実行) のままにし、設定ソースには既存の
.circleci/config.ymlファイルを使います。選択内容を確認して、プロジェクトの作成を完了します。その後、小さなコミットをプッシュして、最初のパイプラインを実行します。 - GitHub OAuth アプリで接続された組織 (ユーザーが GitHub アカウントでサインインしたときに CircleCI が作成する組織): サイドバーで Projects を選択し、リポジトリを見つけて Set up をクリックします。リポジトリにすでにある
.circleci/config.ymlを使う Fastest を選択し、ブランチにmainと入力して Set Up Project をクリックします。
その後、CircleCI がパイプラインを実行し、テストが自動的に実行されます。パイプラインが完了したら、cypress/run ジョブを開いて Run Cypress ステップを展開し、テスト結果を確認します。
成功です!すべてのテストに合格しました。
まとめ
このチュートリアルでは、Cypress をセットアップし、API テストを実行するように設定しました。テスト用に baseUrl を設定する方法と、テスト フレームワークのディレクトリを構成する方法を学びました。また、cy.request() を使ってさまざまな HTTP 操作を行う方法と、Cypress のテスト ランナーの使い方も学びました。最後に、継続的インテグレーションと CircleCI を活用して、テストを自動化しました。
このチュートリアルで学んだことが、みなさんとチームの役に立てば幸いです。アプリケーション開発を楽しんでください!