Cypress on ララジャパン

CypressでE2Eテストを自動化（５）laracasts/cypressでLaravelプロジェクトをテスト

Wed, 09 Oct 2024 12:42:04 +0900

ここまで４回の投稿でCypressテストの設定・テストコードなどをご紹介してきました。５回目の今回は、laracasts/cypressというLaravelでCypressを使用するために作成されたパッケージをご紹介します。Laravel10.xのプロジェクトにインストールして使ってみました。

Cypressのセットアップや基本的なテストなど、以前の記事は以下からご覧いただけます。

Cypressセットアップ・実行方法 Cypress画面表示のテスト Cypressログイン・ログアウトのテスト Cypressパスワードリセットのテスト

laracasts/cypressインストール

今までご紹介したCypressのテストでは、テスト対象プロジェクトとCypressが全く別のディレクトリでも問題なかったのですが、今回ご紹介するlaracasts/cypressはLaravelのartisanコマンドやfactoryなどを使用するため、テスト対象のLaravelプロジェクト内にインストールする必要があります。

ではまずはCypressをインストールします。Laravelのプロジェクトルートで、以下のコマンドを実行します。

% npm install cypress --save-dev

執筆時点で、cypress13.14.2がインストールされました。次にlaracasts/cypressのインストールです。以下のコマンドを実行します。

% composer require laracasts/cypress --dev

このコマンドで、laracasts/cypress3.0.2と関連パッケージがインストールされました。

最後に、以下のコマンドで初期ファイルを作成します。コマンドを実行するとcypressのディレクトリをどこに作成するか？を質問されるので、任意のディレクトリを指定してください。ここではコマンドラインで提案された通りのtests/配下を指定しました。

% php artisan cypress:boilerplate

Where should we put the cypress directory? [tests/cypress]:
> 


Updated tests/cypress/support/index.js
Updated tests/cypress/plugins/index.js
Created tests/cypress/plugins/swap-env.js
Created tests/cypress/integration/example.cy.js
Created tests/cypress/support/laravel-commands.js
Created tests/cypress/support/laravel-routes.js
Created tests/cypress/support/assertions.js
Created tests/cypress/support/index.d.ts
Created cypress.config.js
Created .env.cypress

ファイルが作成されました、さっそくCypressを立ち上げてみます。以下のコマンドを実行してください。

% npx cypress open

ここで、require is not defined in ES module scopeというエラーが発生しました。

require is not defined の修正

Laravel10ではデフォルトでpackage.jsonに“type”: “module”が設定されているのですが、これとlaracasts/cypressで使用されているCommonJS形式の記述がマッチしないことが原因でエラーとなっているようです。

このエラーの修正方法には何パターンかありますが、ここではLaravelのデフォルトを変更せず、またできるだけ簡単にエラーを解消できるよう以下の修正を行います。

１：ファイルの拡張子を.cjsに変更

まず、Cypress実行の際にrequireされる以下の２ファイルの拡張子を.jsから.cjsへ変更します。

/cypress.config.cjs                  // .jsから.cjsへ
/tests/cypress/plugins/swap-env.cjs  // .jsから.cjsへ

２：configファイルを修正

次に、cypress.config.cjsファイルのe2e内、setupNodeEvents()に以下のtaskを追加します。

cypress.config.cjs

const { defineConfig } = require('cypress')

module.exports = defineConfig({
.....

    e2e: {
        setupNodeEvents(on, config) {
          // ここにtaskを追加（plugins/index.jsの内容を移動）
          on('task', require('./tests/cypress/plugins/swap-env.cjs'));  //ここを追加
          return config　　　　　　　　　　　　　　　　　　　　　　　　　　　　  //ここを追加
        },
.....
    },
})

３：index.jsを削除

２の変更により/tests/cypress/plugins/index.jsは不要になるので削除します。

ここまででエラー修正は完了です。

４：baseUrlの指定

configファイルを開いているので、テストの実行に必要なbaseUrlも設定しておきましょう。同じくconfigファイルのe2e内にLaravelプロジェクトのURLをセットします。

cypress.config.cjs

const { defineConfig } = require('cypress')

module.exports = defineConfig({
.....

    e2e: {
        setupNodeEvents(on, config) {
          // return require('./tests/cypress/plugins/index.js')(on, config)
          // ここに元のplugins/index.jsの内容を移動
          on('task', require('./tests/cypress/plugins/swap-env.cjs'));
          return config
        },
        baseUrl: 'http://127.0.0.1:8000', //プロジェクトURLの指定
.....
    },
})

ここまで進めたら、再度以下のコマンドでCypressを立ち上げます。

% npx cypress open

問題なく起動したらダッシュボードを開いて、laracasts/cypressインストール時に自動生成されたexample.cy.jsを選択し、実行してみます。

こちらもエラーなく成功したら準備は完了です。

laracasts/cypressのコマンド

laracasts/cypressでは、Laravelプロジェクトのテストに便利なコマンドが用意されています。その中からいくつかテストでよく使うものをご紹介します。

まずはcreate()から。factoyと連動して、テスト用データを作成できます。以下の例ではUserデータを作成しています。

    cy.create('App\\Models\\User', { 
        name: 'ユーザー名',
        email: 'login-test@example.com',
    });

次に、login()・logout()です。コマンド名の通りログイン・ログアウトの処理を実行するコマンドで、PHPUnitでauth()->login($user)、auth()->logout()と記述した時と同じ動作をしてくれます。以下のように、引数にユーザーの情報を渡して使用します。

    cy.login({ name: 'ユーザー名' });
    cy.logout({ email: 'test@example.com'' });

そして次はcurrentUser()です。これはLaravelのauth()->user()と同じく、現在認証されているユーザーを取得してくれます。取得したユーザー情報は、Cypressコマンドのits()と組み合わせることで任意のプロパティが取り出せます。以下の例では取得したユーザーのemailデータを取り出し、期待通りか確認しています。

    cy.currentUser().its('email').should('eq', 'test@example.com');

最後に、refreshDatabase()です。Laravelのmigrate:refreshをコールします。このコマンドは任意の場所で使用できますが、CypressのbeforeEach()コマンドと組み合わせて使用すると、各テストケースの前にDBをリフレッシュしてくれるので便利です。

    beforeEach(() => {
        cy.refreshDatabase();
    });

テストコード

今回は新規会員登録・ログイン・ログアウトのテストを、ここまでご紹介したlaracasts/cypressのコマンドを使用して作成しました。

LaracastsCypressTest.cy.js

describe('laracasts/cypress Test', () => {

    beforeEach(() => {
        cy.refreshDatabase();
    });

    it('新規会員登録テスト', () => {
        cy.visit('/register');

        // フォームに情報を入力・送信
        cy.get('input[name=name]').type('新規登録ユーザー');
        cy.get('input[name=email]').type('test@example.com');
        cy.get('input[name=password]').type('password');
        cy.get('input[name=password_confirmation]').type('password');
        cy.get('button[type="submit"]').click()

        // ダッシュボードにリダイレクトされたことを確認
        cy.url().should('eq', Cypress.config().baseUrl + '/dashboard');
        // 認証中のユーザーを確認
        cy.currentUser().its('name').should('eq', '新規登録ユーザー');
    });

    it('ログインテスト', () => {
        // ユーザーを作成
        cy.create('App\\Models\\User', {
            name: 'ログインテスト',
            email: 'login-test@example.com',
        });

        cy.visit('/login');
        cy.get('input[name=email]').type('login-test@example.com');
        cy.get('input[name=password]').type('password');
        cy.get('button[type="submit"]').click()

        // ダッシュボードに遷移したことを確認
        cy.url().should('eq', Cypress.config().baseUrl + '/dashboard');
        // 認証中のユーザーを確認
        cy.currentUser().its('email').should('eq', 'login-test@example.com');
    });

    it('ログアウトテスト', () => {
        // ユーザーを作成
        cy.create('App\\Models\\User', {
            name: 'ログアウトテスト',
            email: 'logout-test@example.com',
        });

        //ログインを実行
        cy.login({ name: 'ログアウトテスト' });
        cy.visit('/dashboard')

        //ドロップダウンメニューを開くためのボタンクリック・ログアウトボタンをクリック
        cy.get('.relative').click()
        cy.contains('a', 'ログアウト').click()

        cy.visit('/dashboard').assertRedirect('/login');
        // 認証中のユーザーがいないことを確認
        cy.currentUser().should('not.exist');
    });
});

では、テストを実行してみましょう。Cypressのブラウザでテストファイルをクリックします。まだCypressを立ち上げていない場合はnpx cypress openを実行してCypressを立ち上げてくださいね。

全て成功しました！今回Cypressコマンドの説明は省きましたが、以下の記事で実行方法や代表的なコマンドをご紹介していますのでぜひご覧ください。

Cypressセットアップ・実行方法 Cypress画面表示のテスト Cypressログイン・ログアウトのテスト Cypressパスワードリセットのテスト

CypressでE2Eテストを自動化（４）パスワードリセットのテスト

Tue, 03 Sep 2024 23:36:11 +0900

今回はパスワードリセットのテストです。リセットリンクをクリックしてメールアドレスを入力、MailHogに届いたメールの確認、パスワードリセット実行、という一連のユーザーの操作をCypress13.xで実装します。

Cypressのセットアップや画面表示テストなど、以前の記事は以下からご覧いただけます。

Cypressセットアップ・実行方法 Cypress画面表示のテスト Cypressログイン・ログアウトのテスト

Cypressでパスワード再設定のテスト

引き続きLaravel Breezeのログイン画面を使ってテストします。テストの流れは、少し項目が多いですが以下のような形で進めようと思います。

ログイン画面で「パスワードを忘れた？」というリンクをクリック
パスワードリセットのリクエスト画面でメールアドレスを入力・送信
受信したメールのリンクからパスワードリセット画面へ遷移
パスワードリセットを実行
旧パスワードでログインが失敗することを確認
新しいパスワードでログインが成功することを確認

受信メールの確認にはMailHogを使用しますので、もしインストールがまだの場合は環境に合わせてインストールくださいね。

Laravelの.envは以下のように設定しています。

.env

...
MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="local@example.com"
MAIL_FROM_NAME=メールテスト
...

事前準備１： cypress-mailhog

CypressからMailHogのデータを取得するための便利なコマンドが提供されているパッケージ、cypress-mailhogを使用します。

以下のコマンドでインストールできます。執筆時点で最新の2.4.0がインストールされました。

$ npm install --save-dev cypress-mailhog

また、以下の設定が必要です。まずはcypress/support/commands.jsファイルにインポート。

cypress/support/commands.js

import 'cypress-mailhog';
...

そして、cypress.config.jsファイルのenvにMailHogのURLを追記します。私の環境ではhttp://localhost:8025にてMailHogのUIが確認できます。

cypress.config.js

import { defineConfig } from "cypress";

export default defineConfig({
  env: {
    mailHogUrl: "http://localhost:8025", // MailHogのURLをここに追記
  },
  e2e: {
    baseUrl: 'http://127.0.0.1:8000',
  },
});

これでCypressのテスト内でcypress-mailhogのコマンドが使用できるようになりました。

具体的には以下のように、cy.に続けてCypressコマンドのように使用できます。mhGetAllMails()はメールボックスのメールを最大50件取得するコマンドで、mhFirst()は、直前のコマンドで取得したメールから最初の１件を抽出するコマンドです。

cy.mhGetAllMails()            //メールを最大50件取得
cy.mhGetAllMails().mhFirst()  //メールの最初の１件を取得

事前準備２： mailparser

次に、mailparserをインストールします。今回は届いたメールの本文を確認する必要があるのですが、先ほどのcypress-mailhogで取得したメールの本文を見てみると、以下のようにテキストとして読めない状態です。

そのためmailparserを使用して、人間が読めるように解析する必要があります。

以下のコマンドでインストール。

$ npm install mailparser --save-dev

こちらも2ファイルに設定が必要です。まずcypress/support/commands.jsにカスタムコマンドを追加します。先ほどインストールしたcypress-mailhogのimport文も含めると、以下のようになります。

cypress/support/commands.js

import 'cypress-mailhog'; // cypress-mailhog 用の記述
...
Cypress.Commands.add('mhParseMail', { prevSubject: true }, (mail) => {
  return cy.task('parse-mail', { mail: mail.Raw.Data })
})
...

カスタムコマンド名は任意ですが、mhParseMailとしました。

そして、cypress.config.jsにmailparserのimportとtaskを追加します。taskとは、テストコード内からブラウザ外で必要な作業を呼び出すための機能です。taskのドキュメントはこちら

先ほどcypress-mailhogで同ファイルに書き込んだものと合わせると、最終的には以下のようになります。

cypress.config.js

import { defineConfig } from "cypress";
import { simpleParser as parser } from 'mailparser'; // ここでmailparserをインポート

export default defineConfig({
  env: {
    mailHogUrl: "http://localhost:8025"
  },
  e2e: {
    baseUrl: 'http://127.0.0.1:8000',
    setupNodeEvents(on, config) {                 // タスク用の追記ここから
      on('task', {
        'parse-mail': ({ mail }) => parser(mail), // タスクを定義
      })
    },                                            // タスク用の追記ここまで
  },
});

on(’task’, {…})がタスクを定義している箇所です。task名は任意ですが、ここではparse-mailとしました。カスタムコマンドmhParseMail()を実行するとparse-mailというtaskが呼ばれ、mailparserによりメール解析が実行される、という流れです。

ここまで設定できたらテストコードからの呼び出しは簡単で、cypress-mailhogで提供されているmhGetAllMails().mhFirst()に繋いで以下のように使用します。

cy.mhGetAllMails().mhFirst().mhParseMail().then((mail) => {
 mail.subject               // 件名を取得
 mail.from.value[0].address // Fromを取得
 mail.text                  // 本文を取得
}

取得したメールの１通目のデータをmhParseMail()で解析してからthen()に渡します。受け取ったmailオブジェクトはmailparserの形式になっているため、上の例のようにmail.subjectで件名を、mail.from.value[0].addressでメールのfromを、mail.textで本文を取得できます。

他にもプロパティが色々ありますのでmailparserのドキュメントをご確認ください。

wrap

ここまでで事前準備は完了ですが、最後に今回新しく使用するコマンドwrap()をご紹介します。

cypress-mailhogやmailparserから受け取ったメールデータはJavaScriptのオブジェクトです。このデータをCypressのアサーションコマンドで扱うために、以下のようにwrap()コマンドでラップします。

cy.mhGetAllMails().mhFirst().mhParseMail().then((mail) => {
 cy.wrap(mail.subject).should('eq', 'パスワードのリセット方法について');
}

これで、Cypressコマンドを繋いでメールの件名が期待した内容がどうかを検証できるようになります。

Cypressでパスワードリセットのテスト

以下がパスワードリセットのテストコード全文になります。

cypress/e2e/PasswordResetTest.cy.js

it('パスワードリセットのテスト', () => {

  cy.visit('/login');
  cy.contains('a', 'パスワードを忘れた').click();

  // パスワードリセットページに遷移したことを確認
  cy.url().should('include', '/forgot-password');

  // メールアドレス入力
  cy.get('input[name="email"]').type(Cypress.env('email'));

  // パスワードリセットメール送信ボタンをクリック
  cy.contains('button', 'パスワードリセットメールを送信').click();

  // 取得した一覧のうち、１件目（最新）のメール本文を取得
  cy.mhGetAllMails().mhFirst().mhParseMail().then((mail) => {

    cy.wrap(mail.subject).should('eq', 'パスワードのリセット方法について');
    cy.wrap(mail.from.value[0].address).should('eq', 'from@example.com');

    // メールの本文からパスワードリセットのためのリンクを抽出
    const hrefRegex = /https?:\/\/[^\s/"']+\/reset-password\/[^\s/"']+/;
    let match = hrefRegex.exec(mail.text)

    // パスワードリセットの画面へ遷移
    cy.visit(match[0])

    cy.get('input[name="email"]').type(Cypress.env('email')); // メールアドレス入力
    cy.get('input[name="password"]').type('new-password');    // 新しいパスワード
    cy.get('input[name="password_confirmation"]').type('new-password'); // パスワードの再入力

    // パスワードリセットメール送信ボタンをクリック
    cy.contains('button', 'パスワードのリセット').click();

    // ログイン画面へ遷移したことを確認
    cy.url().should('eq', Cypress.config().baseUrl + '/login');

    // 旧パスワードでログインすると失敗する
    cy.get('input[name="email"]').type(Cypress.env('email'));
    cy.get('input[name="password"]').type(Cypress.env('password'));
    cy.get('button[type="submit"]').click();

    cy.get('input[name="email"]')
      .next('ul')
      .should('contain', 'ログイン情報が存在しません。');

    // 新しいパスワードで再度ログイン試行（メールアドレスの入力値は残っているので不要）
    cy.get('input[name="password"]').type('new-password'); // 新しいパスワード
    cy.get('button[type="submit"]').click();

    // ダッシュボードに遷移したことを確認
    cy.url().should('eq', Cypress.config().baseUrl + '/dashboard');
  })
})

ではテストを実行してみます。npx cypress openでCypressを立ち上げて、対象ファイルをクリックします。

成功しました！ですが、このテストではDBのパスワードを変更してしまうため、どこかでパスワードをデフォルトに戻すなどの処理を行う必要があります。

CypressでDBをリセットするには、テスト対象のプロジェクトにDBリセット用のAPIを用意する、DBリセット用のシェルスクリプトを作成してテストから呼び出す・・・などの方法が考えられますが、今回はLaravelのプロジェクトがテスト対象ということもあり、ユニットテストのようにrefreshDatabase()が実行できれば便利ですよね。

ということで、次回はLaravelプロジェクトをCypressでテストするときに便利なパッケージをご紹介します。

参照

Cypressセットアップ・実行方法 Cypress画面表示のテスト Cypressログイン・ログアウトのテスト

CypressでE2Eテストを自動化（３）ログイン・ログアウト

Sun, 04 Aug 2024 06:19:43 +0900

前回のCypressでの画面表示テストに続き、今回はログイン・ログアウトのテストです。カスタムコマンドの作り方やHTTPリクエストの実行など、Cypressのテストに欠かせないアプローチが出てきますので参考になれば嬉しいです。

Cypressのセットアップや画面表示テストなど、以前の記事は以下からご覧いただけます。

Cypressセットアップ・実行方法 Cypress画面表示のテスト

フォーム入力・ボタンクリック

ログインのテストは前回に続きLaravel Breezeのログイン画面で行います。フォーム画面のテストには、テキスト入力・ボタンクリックの操作が必要ですので、それぞれCypressのtype()とclick()コマンドを使用します。

どちらのコマンドもcy.type()…のようにcyに直接繋げるのではなく、操作対象の要素を取得した後に繋いで使用します。例えばメールアドレス入力欄にメールアドレスを入力、またsubmitボタンをクリックといった操作は、以下のように記述します。

  cy.get('input[name="email"]').type('test@example.com')
  cy.get('button[type="submit"]').click()

cypress.env.jsonに環境変数をセット

ログイン情報など、テストの実行環境によって異なる値はcypress.env.jsonを作成してそちらにまとめておくと便利です。

今回使用するユーザーのメールアドレス・パスワードは、以下のように定義しました。

cypress.env.json

{
  "email": "test@example.com",
  "password": "password"
}

テストコードの中でこの値を呼び出すには、Cypress.env()を使います。

  cy.get('input[name="email"]').type(Cypress.env('email'));
  cy.get('input[name="password"]').type(Cypress.env('password'));

ログイン成功・失敗のテストコード

type()・click()を使用した、ユーザーがログインに成功するケースとエラーが発生するケースのテストコードは以下のようになります。アサーションは前回と同じくshould()を使って検証します。

it('正しいメールアドレス・パスワードでログイン成功', () => {

  cy.visit('/login')

  cy.get('input[name="email"]').type(Cypress.env('email'))
  cy.get('input[name="password"]').type(Cypress.env('password'))
  cy.get('button[type="submit"]').click()

  // ダッシュボードに遷移
  cy.url().should('eq', Cypress.config().baseUrl + '/dashboard')
})

it('パスワード間違いでログイン失敗', () => {

  cy.visit('/login')

  cy.get('input[name="email"]').type(Cypress.env('email'))
  cy.get('input[name="password"]').type('wrong-password') //間違ったパスワード
  cy.get('button[type="submit"]').click()

  //ログイン画面のまま
  cy.url().should('include', '/login')

  // 画面のエラー表示を確認
  cy.get('input[name="email"]')
    .next('ul')
    .should('contain', 'ログイン情報が存在しません。')
})

ログイン失敗のテストでは、「ログイン情報が存在しません。」のエラーメッセージが存在することを確認しています。このエラーメッセージはLaravel Breezeでは以下のHTMLで出力されます。

<input class="border-gray-300 focus:border-indigo-500 focus:ring-indigo-500 rounded-md shadow-sm block mt-1 w-full" id="email" type="email" name="email" value="test@example.com" required="required" autofocus="autofocus" autocomplete="username">
<ul class="text-sm text-red-600 space-y-1 mt-2">
    <li>ログイン情報が存在しません。</li>
</ul>

メッセージ出力箇所のul・liには要素特定に使えそうなidやclassが割り当てられていないため、input[name=“email”]要素の次のul要素内をチェックします。

request・thenコマンド

さて次はログアウトですが、テストを作成する前にrequest()とthen()コマンドをご紹介します。

request()は、HTTPリクエストを送信するために使用するコマンドです。以下のように記述すると、引数のURLに対してGETリクエストを送信します。

cy.request('/login')

POST送信の場合はオブジェクト形式でオプションを渡す必要があります。以下のように記述すると、POSTメソッドでURL/loginに対してリクエストを送信、かつリクエストbodyにはパスワード情報を含める。という意味になります。

    cy.request({
      method: 'POST',
      url: '/login',
      body: {
        password:'password',
      }
    })

では次にthen()コマンドです。then()は単独で使うのではなく他のコマンドにチェーンして、前のコマンドからの結果を受け取る形で記述します。具体的な使用方法として、先ほどのPOST送信にthen()を繋げました。

    cy.request({
      method: 'POST',
      url: '/login',
      body: {
        password:'password',
      }
    }).then((response) => {
      expect(response.status).to.eq(200)
    })

このコードでは、HTTPリクエストが完了するのを待ってから、そのレスポンスをresponseという引数で受け取ります。その後、コールバック関数内でレスポンスのステータスコードを検証しています。

then()は他にもHTML要素や任意の値やオブジェクトなども扱えます。詳しくはドキュメントをご参照ください。

ログアウトのテスト

ではログアウトのテストを作成してゆきましょう。画像のように、ドロップダウンを開いてログアウトリンクをクリックするとログアウトすることをテストします。

こういったログアウトのようなテストでは、ユーザーがすでにログインしている状態を準備する必要があります。これを、直接フォームに入力してボタンをクリックする方法で行なっても良いのですが、それでは画面操作の分余計な時間がかかってしまいます。

そこで、先ほどご紹介したrequest()を使用してHTTPリクエストでログインすることにします。これにより、UIを介さずに効率的にログイン処理を完了できます。

ログイン処理のカスタムコマンドを作成

テスト内で繰り返し使用する処理はカスタムコマンドとして定義します。これにより、どのテストからでも簡単に呼び出して使用できるようになります。

cypress/support/commands.jsファイルにカスタムコマンドを追加し、その際Cypressが定めた以下の構文を使用します。

Cypress.Commands.add('カスタムコマンド名', (引数) => { })

以下が作成したカスタムコマンドです。ユーザー画面のログインなのでコマンド名はloginAsUserとしました。

cypress/support/commands.js

Cypress.Commands.add('loginAsUser', (email, password) => {
  // Step 1: ログインページにアクセスしてCSRFトークンを取得
  cy.visit('/login')
  cy.get('input[name="_token"]').invoke('val').then((csrfToken) => {
    // Step 2: 取得したCSRFトークンを使用してログインリクエストを送信
    cy.request({
      method: 'POST',
      url: '/login',
      form: true, // フォームデータとして送信
      body: {
        email: email,
        password: password,
        _token: csrfToken  // CSRFトークンをリクエストに含める
      }
    }).then((response) => {
      // Step 3: ログインが成功したかステータスコードで確認
      expect(response.status).to.eq(200);
    });
  });
})

ログインするだけなのに少し長いコマンドになっていますが、内容は大きく以下の３ステップに分かれています。

ログインに必要なCSRFトークンを取得する処理
cy.requestを使用してログインリクエストを実行
ログイン成功のステータス確認

まず、ステップ１ではログイン画面へアクセスし、トークンのデータを含むHTML要素を取得。その要素に対しinvoke(‘val’)を使用し、トークンの値だけを抜き出しています。invoke(‘val’)とはjQueryのval()メソッドを呼び出すということを意味します。なぜjQueryが使えるのか?というと、これはCypressがjQueryを内包しているためこのような値の取得方法が可能になっています。

さて、こうして取得したトークンは次のHTTPリクエストで使用します。そのためthen()で繋ぎ、トークンをcsrfTokenとして受け取ります。

そしてステップ２は、request()でのHTTPリクエスト実行です。リクエストメソッド、URL、リクエストデータなどを引数に渡しています。_tokenとしてcsrfTokenも含まれていますね。

最後のステップ３はレスポンスの検証です。then()でレスポンスを受け取り、expect()を使ってHTTPステータスを確認しています。expect()はCypressが内部で使用しているChai.jsというアサーションライブラリのメソッドであるため、cy.に繋げず単独で使用できます。

コマンドが完成しました！これをテストの中では、以下のように呼び出して使います。

  cy.loginAsUser()

ログアウトのテストコード

カスタムコマンドを使用したログアウトのテストコードは以下のようになります。

it('ログアウトリンククリックでログアウト', () => {

  //カスタムコマンドでログイン
  cy.loginAsUser(Cypress.env('email'), Cypress.env('password'))

  //テスト対象画面へ遷移
  cy.visit('/dashboard')

  //ドロップダウンメニューを開くためのボタンクリック・ログアウトボタンをクリック
  cy.get('.relative').click()
  cy.contains('a', 'ログアウト').click()

  //ホーム画面へ遷移したことを確認
  cy.url().should('eq', Cypress.config().baseUrl + '/')
});

カスタムコマンドによるログイン処理、ログアウト実行、アサーション、という構成です。ログアウトテストに直接関係のないログイン処理を別ファイルに切り出しているので、テストコードがすっきりしていいですね。

では、ここまでのログイン成功・ログイン失敗・ログアウトのテストを全て実行してみます。

無事成功しました！次回は、Cypressでメール確認のテストを作成します。

参照

CypressでE2Eテストを自動化（１）セットアップ CypressでE2Eテストを自動化（２）画面表示のテスト

CypressでE2Eテストを自動化（２）画面表示のテスト

Wed, 03 Jul 2024 12:59:35 +0900

テスト自動化ツールCypressのセットアップに続いて、今回は画面表示のテストです。Cypressでの画面遷移や要素の取得、アサーションなど基本的な書き方をご紹介します。

Cypressの構文

Cypressの基本的な構文は、以下のように３つのグループに分かれています。describeとcontextはテストケースのグループを、itは１つ１つのテストケースを表しています。

contextはdescribeのエイリアスなので、機能は同じです。テストケースの大まかな定義や特定の条件でのグループ分けなど、テストのスタイルによって使い分けることができます。

describe('大項目', () => {
  context('中項目', () {
    it('テスト１', () => {
      //テストの内容
    })

    it('テスト２', () => {
      //テストの内容
    })
  })
})

テストを作成する際にこれらの３つの項目全てが必要ということはなく、最小単位であるitだけでテストを構成しても問題ありません。

Cypressの画面遷移・要素の取得

今回のテスト対象はLaravel Breezeのログイン画面です。

・画面が表示できるか・ダッシュボードにアクセスするとログイン画面にリダイレクトされるか

をテストします。

これらのテストに必要なCypressのコマンドについて、１つずつ進めてゆきましょう。

まずは画面遷移から。visit()コマンドを使用します。引数にアクセスしたいURL（ここではローカルのログイン画面のURL）を渡して以下のように記述します。

      cy.visit('http://127.0.0.1:8000/login')

最初にcy.とありますが、Cypressではこのようにcy.の後にメソッドを繋げて記述します。

テスト対象画面に遷移できたら、次はメールアドレス入力欄やログインボタンの要素を取得します。画面の要素を取得するには、get()やcontains()を使用して以下のように書きます。

      cy.get('input#email')
      cy.get('button[type="submit"]').contains('ログイン')

get()の引数には取得したい要素のセレクタを渡します。上の例ではidが"email"であるinput要素、typeが"submit"であるbutton要素を指定しています。

そしてcontains()は、対象のテキストを「含む」要素を取得します。上記の例では、まずget()でtypeが"submit"であるbutton要素を取得し、contains()をチェーンで繋いで"ログイン"というテキストが含まれる要素に絞り込んでいます。「含む」なのでもし"ログインする"などの他のテキストが含まれていても取得対象となります。

CSSセレクタの指定については「○番目の要素」や「○というデータ属性」などの細かい指定も可能です。ドキュメントには色々な例が載っていますのでご参照ください。

また、URLの確認もテストではよくあるかと思いますが、こちらもコマンドが用意されています。

      cy.url()

これだけで、現在のURLを文字列として取得してくれます。

Cypressのアサーション

ここまででテスト対象の要素は取得できたので、検証に進みます。get()やcontains()の後にshould()をチェーンで繋ぎます。

      cy.get('input#email').should('exist')
      cy.get('button[type="submit"]').contains('ログイン').should('exist')

should(’exist’)のように、引数にはアサーション方法を渡します。上の例では要素が「存在すること」を確認しています。

引数として渡すアサーション方法は色々あり、他にも「include（含む）」「eq（イコール）」などの確認ができます。

      cy.url().should('include', 'login')
      cy.url().should('eq', 'http://127.0.0.1:8000/login');

baseUrlを設定

visit()の引数であるURLですが、対象のURLを毎回記述するのは不便です。以下のようにcypress.config.jsにベースURLを定義しておきましょう。

以下のように、baseUrl: ‘対象のURL’をe2eの中に記述します。

cypress.config.js

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    baseUrl: 'http://127.0.0.1:8000', //ここを追加
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
  },
});

これで先ほどの画面遷移は以下のようにすっきり書くことができます。

      //cy.visit('http://127.0.0.1:8000/login')
      cy.visit('/login')

テストの実行

いよいよテスト実行です。ここまでで出てきたコマンドを使用して、テストコードの全体は以下のようになりました。

    it('ログイン画面表示', () => {
      cy.visit('/login')

      cy.get('input#email').should('exist')
      cy.get('input#password').should('exist')
      cy.get('button[type="submit"]').contains('ログイン').should('exist')
    })

    it('未ログイン時はログイン画面へリダイレクト', () => {
      cy.visit('/dashboard')

      cy.url().should('include', 'login')
    })

Cypressブラウザを立ち上げて、ファイル名をクリックするとテストが走ります。起動・テスト実行の詳細は前回の記事をご覧ください。

テストが成功しました！テストケース名をクリックするとアサートの内容など、テストの詳細を見ることができます。

次回は、要素の入力を伴うログイン関連のテストを作成します。

参照

CypressでE2Eテストを自動化（１）セットアップ CypressでE2Eテストを自動化（３）ログイン・ログアウト

CypressでE2Eテストを自動化（１）セットアップ

Tue, 28 May 2024 23:57:55 +0900

Webアプリの動作確認時、ブラウザをポチポチ手動でテストをするのも良いですが、可能な限り自動化すればテストに割く時間や手間を大きく削減できます。

テスト自動化ツールは色々なタイプがありますが、導入がシンプル・JavaScrirptベースなCypressを試してみました。

Cypressとは

Cypressとは、Webアプリケーション向けに開発されたフロントエンドの自動テストツールです。

テスト自動化というとSeleniumが有名ですが、Seleniumはブラウザ操作全般（スクレイピングなど）に使えるのに対し、Cypressはテスト用に特化して作られています。そのためスナップショット・自動待機など便利な機能が最初から用意されており、GUIを操作してテスト実行が可能なのでエンジニアでなくともとっつきやすいのではないでしょうか。

ドキュメントには使い方が詳しく解説されているので、導入前にざっと見てみるのも面白いと思います。現時点で日本語非対応ですが翻訳機能を使えば問題ありません。

また、テスト結果を保存したりチームで共有するためのクラウド機能は有料ですが、Cypressの大部分であるテスト機能そのものは無料で使えるのも嬉しいポイント。

Cypressインストールとセットアップ

CypressのインストールにはNode.js（現時点ではNode.js 18.x、もしくは20.x以上）が必要ですので、バージョンを確認。

% node -v
v18.17.1

次にインストール先のディレクトリへ移動して、以下のコマンドを実行します。今回私はテスト対象のプロジェクトルートにインストールしましたが、異なるディレクトリへインストールしてもCypressのテスト実行には問題ありません。

% cd /your/project/path
% npm install cypress --save-dev

実行後、現時点で最新のCypress13.9.0がインストールされました。では以下のコマンドでCypressを起動します。

% npx cypress open

起動直後の画面です。ここからはターミナルではなくブラウザを操作して設定を進めます。E2Eテスト、コンポーネントテストの選択肢があるので、ここではE2Eテストを選択。後からでもこの選択は変更可能です。

次に、構成ファイルの一覧が表示されます。ここもContinueをクリック。

次に、テストに使用するブラウザを選択。ここではChromeを選択します。

いよいよ最初のテスト作成へ進みます。Create new specをクリック。

ここではテストファイルの名前を編集できます。今回はデフォルトのままとして、Create spec をクリック。

作成されたテストファイルが表示されました。ファイルにはサンプルコードが記述されています。このままテストを実行することもできますが、一旦×をクリックしてダッシュボードを見てみます。

以下がダッシュボードです。テストはまだ１つしかないので一覧には先ほど作ったファイルだけがリストされていますね。

ここまでで、インストールディレクトリには以下のディレクトリ・ファイルが作成されました。

Cypress/e2e/spec.cy.js

Cypress/fixtures/example.json

Cypress/support/commands.js

Cypress/support/e2e.js

cypress.config.js

Cypress自動テスト実行

サンプルコードではありますが、さっそくテストを実行してみましょう。テストの一覧から先ほど作成したspec.cy.jsをクリックします。

すると画面が変わり、テストコードが実行されます。テストの内容はCypressのサンプルサイト（https://example.cypress.io）へアクセスするだけなので問題なく成功し、緑のOKマークが表示されています。

テスト失敗のパターンも確認してみましょう。visit()とは引数のURLへアクセスするコマンドですので、ここを立ち上げていないローカルサーバーのアドレスに変更しました。どうなるでしょうか。

Cypress/e2e/spec.cy.js

describe('template spec', () => {
  it('passes', () => {
    cy.visit('http://127.0.0.1:8000') //ここを編集
  })
})

テストコードを編集すると自動でテストが走り、以下のようにエラーメッセージが表示されました。コードのどこで失敗したのかも示してくれるのでわかりやすいですね。

少し長くなってしまったので、次回から具体的なブラウザテストを実装してゆきます。

参照

CypressでE2Eテストを自動化（２）画面表示のテスト CypressでE2Eテストを自動化（３）ログイン・ログアウト