Cypress と GitHub Actions の連携設定

GitHub Actions で CypressによるE2Eテストを実行して、cypress.io のダッシュボードに連携するための設定メモです。

Cypressとは？

Webアプリケーションの E2Eテスト / 結合テストを便利に行うためのアプリケーションです。

以下の特徴があります:

• オープンソース・無料で使用できる。
• インストールが簡単。
• 直感的に分かりやすいテストコードでテストできる。
• テストの1ステップごとにスナップショットが取られるため、テスト結果を後から追いかけるのがとっても便利。
• テストコードで画面表示の待ち合わせ処理やスリープ処理の記述が不要。
• テストコード内でスタブを用いて通信処理の差し替えを行うこともできる。
• テスト実行の様子が自動録画される

参考:

• https://docs.cypress.io/guides/overview/why-cypress#Features

Cypress は実行スピードも速く、これまでのE2Eテストツールとは一線を画す便利さ・心地良さよさがあるのですが、苦手なテストもあります。とはいえ苦手部分に関しては Cypress の公式ページに明言されており、回避方法についての説明があるため、最初に目を通しておけばいろいろハマる前に手は打てそうです。

Cypress 基本的には開発者PC上で利用することを主眼に置かれたアプリケーションですが、CIで動作させることも可能です。

今回はまずローカルPC上で動作させて、次に CI で動作させてみたいと思います。

1.Cypress のインストール

まずは、ローカルPC環境で動作するように Cypress をインストールします。

npm install cypress --save-dev

参考:

• https://docs.cypress.io/guides/getting-started/installing-cypress

2.テストコードを書く

cypress/integration というフォルダを作り、その下に作成したファイルにテストコードを記述します。

以下のページをテストするコードを書いてみました。

• テスト対象のページ： https://ototadana.github.io/ci-cd-demo/

テストコードの例:

/// <reference types="Cypress" />
describe('E2Eテスト', () => {
  it('名前を入力してOKボタンで挨拶が返ってくる', () => {
    cy.visit('/')                       // トップページを表示する
    cy.get('input').type('Shoichi')     // inputタグに "Shoichi" とタイプする
    cy.get('button').click()            // buttonタグを取得して、クリックする
    cy.contains('hello, Shoichi.')      // 画面内に "hello, Shoichi." が表示されていることを確認する
  })
})

このように visit で (URLではなく) パスだけを指定する場合は、設定ファイル cypress.json に “baseUrl” を設定しておく必要があります。 例えば、テスト対象のサーバーが http://localhost:3000 で起動する場合は以下のように記述します。

{
  "baseUrl": "http://localhost:3000"
}

参考:

• https://docs.cypress.io/guides/getting-started/writing-your-first-test
• https://docs.cypress.io/guides/references/best-practices#Setting-a-global-baseUrl

3.ローカルで実行

あとは以下のコマンドでローカル実行できます。

1. ローカルPC上でサーバーを起動する (例: npm start)
2. cypressを起動する (例: npx cypress run)

npx cypress run ではなく npx cypress open とすると、デスクトップアプリケーションが起動し、cypress の実行がインタラクティブに行えます（本来はこちらの方が主な使い方です）。

参考:

• https://docs.cypress.io/guides/getting-started/testing-your-app
• https://docs.cypress.io/guides/getting-started/installing-cypress

4.GitHub Actionsの設定

GitHub Actionsでは、以下の設定をしています。

1. Cypressの実行
2. 実行結果を cypress.io のダッシュボードに連携する

「テストが成功したかどうか」だけを確認するならば cypress.io に連携する必要はないのですが、「エラー発生時の状況を後から確認したい」といった場合には連携設定しておくと便利です。テストの様子を録画した動画も cypress.io で確認できます。

4.1 GitHub Actions で Cypress 実行設定する

cypress.io との連携を行わない場合は、以下の設定だけでOKです。

  - name: E2Eテスト実行
    uses: cypress-io/github-action@v2
    with:
      start: npm start

with.start では、cypressでのテスト実行前に起動するテスト対象サービスの起動コマンドを指定しています。

参考:

• https://docs.cypress.io/guides/continuous-integration/github-actions

4.2 cypress.io との連携設定

連携を行う場合、まず以下の手順でダッシュボードを準備します。

1. https://www.cypress.io/ で「Sign up」をクリックしてサインアップする。
2. そのまま Organization を作成する
3. 「Create new Project」でプロジェクトを作成する。

プロジェクト作成すると、プロジェクトID と レコードキー が取得できるので、それぞれ以下の場所に設定します。

• プロジェクトID: cypress.jsonファイル
• レコードキー: GitHubの対象リポジトリの Settings - Secrets の「CYPRESS_RECORD_KEY」

あわせて以下のようにワークフロー定義にwith.recored:true および CYPRESS_RECORD_KEY 環境変数の記述を追加します。

  - name: E2E実行
    uses: cypress-io/github-action@v2
    with:
      start: npm start
      record: true
    env:
      CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}

参考:

• https://docs.cypress.io/guides/dashboard/introduction
• https://docs.cypress.io/guides/dashboard/projects

5.成果物

今回実際に作ったコードは以下になります：

• https://github.com/ototadana/ci-cd-demo/pull/3/commits/cb6efa9b3c18e3fa87c0046eecad80e1e757087a