End To End Test

SDK PortalのDashboardで開発したアプリケーションや、SDK ApiFrontでデプロイされるSPAの、End To End Testのための「E2E Tester」と呼ばれる機能がバンドルされています。

ブラウザアプリケーションを操作する試験シナリオの作成から、ヘッドレスブラウザでの試験実行、画面キャプチャでの結果確認まで、SDK Portalから実施可能です。

この、E2E Testerの利用方法について紹介します。

1. 画面構成

E2E Tester 画面の画面構成です。

Readmeエリア

E2E Tester の機能概要や e2e/ ディレクトリ内のファイル構成ルール、Puppeteer の公式サイトリンクを確認することができます。また、 Offline Tool のダウンロードファイルが用意されています。

シナリオ選択エリア

e2e/ 配下のディレクトリ・ファイルをGUIで操作できるファイルシステムです。

シナリオ一覧表示エリア

E2E テストの実行状況サマリを確認することができます。

Test Console

E2E テストを実行・実行状況の詳細やエビデンスの画面キャプチャを確認することができます。

ファイルエディタ

画面操作スクリプト (.js ) や index.json など、e2e/ 配下のファイルを編集するエディタです。

2. 基本的な使い方

e2e/ 配下の ファイル操作は、Test Scenarios で行います。各対象に対して操作可能なメニューを紹介します。

2.1 操作メニューの表示方法

表示方法は2パターン存在し、操作したい対象の行にカーソルをあわせて表示されたメニューボタンを押下するか、行を右クリックすることで表示されます。

2.2 カレントディレクトリの操作一覧

ディレクトリ内で操作できるメニューの一覧です。

2.3 ディレクトリの操作一覧

ディレクトリへの操作メニューの一覧です。

2.4 ファイルの操作一覧

ファイルへの操作メニューの一覧です。

3. OFFLINE TOOL

オフラインで E2E Tester を利用するためのツールキットです。パッケージをダウンロードして E2E Tester を起動することができます。
以下のボタンからダウンロードすることが可能です。

4. E2E テストを作成する

E2E テストは Test Scenarios およびファイルエディタを利用して作成していきます。本項では、E2E テストのファイル構成と、必要なファイルの作成手順について紹介していきます。

4.1 E2E テストの構成

E2E テストのファイル構成と、ファイルの実行順序について説明します。

4.1.1 必要なファイル / ディレクトリ

E2E テストの実行に必要なディレクトリとファイルは以下の通りです。

• Test Scenarios イメージ 1
  • Home/ 直下の各シナリオ (例として001sample/002sample/003sample)

• Test Scenarios イメージ 2
  • シナリオ内の構成

4.1.2 画面操作スクリプトの実行順序について

E2E テストを実行すると、下記の様に指定したシナリオの中でディレクトリ名 / ファイル名の昇順に画面操作スクリプト (.jsファイル) が実行されます。

画面操作スクリプトの実行順は例として以下のようになります。

xml
Home/
    └── scenario_1/
        ├── 0001/
        │   ├── 001_script.js   <- 2番目
        │   ├── 002_script.js   <- 3番目
        │   └── _003_script.js  <- アンダーバー始まりのファイル名のため実行されない
        ├── 0002/
        │   ├── 001_script.js   <- 4番目
        │   └── 002_script.js   <- 5番目
        ├── 000_login.js        <- 1番目
        ├── index.json          <- 実行されない
        └── zzz.js              <- 6番目

4.2 シナリオを作成する

1. [Home] ディレクトリにいる状態で最上部の行にカーソルを合わせて、[メニューマーク] > [Create Folder] を押下します。

   

   メニューマークをクリック

   

   フォルダメニュー [Create Folder] をクリック

2. [directory name] にシナリオ名を入力し、[Submit] ボタンを押下します。ここでは仮に001sampleと入力します。

   

3. 001sampleという空のシナリオが作成できました。シナリオを作成する手順は以上です。

   

4.3 画面操作スクリプトを作成する

シナリオが作成できたら、シナリオの中に画面操作スクリプトを作成していきます。

4.3.1 ファイルを作成する

1. シナリオのディレクトリをダブルクリック または 操作メニュー [Open] を押下します。

   

   操作メニューを表示した場合

2. シナリオの中にいる状態から、最上部の行にカーソルを合わせます。[メニューマーク] > [Create New File] を押下します。

   

3. ポップアップ画面で、[file name] にファイル名を入力します。ファイルの拡張子は .js です。

   

4. 画面操作スクリプトの雛形ファイルが作成されて、エディタで編集できる状態になりました。

   

4.3.2 画面操作スクリプトを実装する

E2E Tester は、puppeteer のスクリプトをラッパーしています。本項では、画面操作スクリプトの引数一覧、実装例、およびエラー判定の実装例について紹介していきます。

• 画面操作スクリプトの引数一覧

  params	E2E テストのシナリオで呼び出すことができるパラメータ
  root	E2E Tester がラッピングしている puppeteer の page/ frame インスタンス
  actions	E2E Tester がラッピングしている puppeteer メソッドのユーティリティアクション
  browser	puppeteer の browser インスタンス
  page	puppeteer の current page インスタンス
  frame	puppeteer の current frame インスタンス。frameSelector オプションを利用する際に利用する。

• 実装例

  • E2E で利用できる主な puppeteer の実装例を紹介します。詳細に関しては puppeteer 公式ページを確認してください。

    jsx
    // page load
    await page.goto( '[URL]' );
    

    jsx
    // set timeout
    page.setDefaultNavigationTimeout( 60000 )
    page.setDefaultTimeout( 60000 )
    

    jsx
    // page action
    let obj = await root.$( '[SELECTOR STRING]' )
    await obj.hover()
    await obj.focus()
    await obj.click()
    await obj.type('[INPUT VALUE]')
    

    jsx
    // Wait For
    await page.waitForNavigation({timeout: 60000, waitUntil: "domcontentloaded"});
    await root.waitFor(()=>!document.querySelector( '[SELECTOR STRING]' ));
    await root.waitFor(300)
    

  • puppeteer をラッピングしている actions の使用例を紹介します。

    jsx
    // logger
    await actions.logger( '[LOG STRING]' );
    

    jsx
    // save screenshot
    await actions.screenshot( '[DESCRIPTION STRING]' );
    

    jsx
    // save resultCache
    await actions.saveResults( '[JSON KEY]' , '[JSON VALUE]' );
    

    jsx
    // get resultCache
    actions.getResults();
    

• シナリオ実行エラーの判定例

  E2E テストのエラーはthrow new Error()で返却します。エラーの判定方法には例として以下のような判定方法があります。

  • 画面の部品がフックできないエラー

    jsx
    // # id 指定で画面部品をフック
    let mainMenu = await root.$('#piyo');
    if( mainMenu == null)
        throw new Error("Not found button of id:piyo!")
    

  • 画面入力値 (E2Eテスト実行パラメータ) と比較して一致しないエラー

    jsx
    // 入力されたフォームの値を取得
    const name = await root.$eval('#piyo .inputText input');
    
    if (params.name !== name) throw new Error(`invalid name! '${params.name}' - '${name}'`);
    

4.4 パラメータを定義する

E2E テストの実行パラメータは index.json という固定のファイル名で定義します。ここでは、index.json ファイルの作成手順および設定可能なパラメータの紹介をします。

4.4.1 index.json に設定できる主なパラメータ情報について

index.json に設定するパラメータは主に4つです。パラメータの value に値を記述しておくと E2E テストの実行画面で value を初期表示させることができ、必要な値をすべて設定していれば実行ボタンを押下するだけで試験を開始することが可能です。

(例) index.json に定義した params

(例) params の各 key に value を定義した場合の E2E テスト実行画面

4.4.2 index.json を作成する

1. シナリオのディレクトリ直下でメニュー [Create New File] を押下します。

   

2. [file name] にindex.jsonと入力し、[Submit] ボタンを押下します。

   

3. index.json ファイルの雛形が作成されて、エディタに表示されます。

   

index.json ファイルの作成手順は以上です。

4.4.3 index.json に設定可能なパラメータの一覧

雛形が作成できたら、以下の表に従って、各パラメータを定義します。

パラメータを定義する手順は以上です。

5. E2E テストを実行する

E2E テストの実行方法について、Qmonus SDK には実行 API が予め用意されており、以下のいずれかの手段で実行することができます。本項では、E2E Tester の Test Console からの実行方法、および実行 API の仕様を紹介していきます。

• E2E Tester からの実行
• ローカル環境からの実行

5.1 E2E Tester から実行する

1. Test Console の [Start New Test] を押下します。

   

2. [Scenario Name] から実行するシナリオを選択し、[Submit] ボタンを押下します。

   

3. [Test Parameters] > [Test Scenario Parameters] に実行パラメータを入力します。初期表示では index.json のparamsに指定したデフォルト値が表示されています。

   

4. [Test Condition] > [Test Conditions] に E2E テストの実行オプションを設定します。初期表示では index.json のdefaultOptionsに指定したデフォルト値が表示されています。

   

5. [Test Description] > [description] に E2E テストの補足 (任意)を設定し、[Test Start] ボタンを押下します。初期表示では index.json のdescriptionに指定したデフォルト値が表示されています。

   

6. E2E テストが開始すると Start New Test 画面が閉じて、実行状況を確認することができます。

   

   テストが正常に完了すると、[Status] にcompleted、[End] に終了時間、[Progress] に100%と表示されます。

   

   E2E Tester によるシナリオ実行の手順は以上です。

【参考】 APIでシナリオを動作させるには

E2E Testの実行はAPIでも可能です。
API実行に必要な値は以下の通りです。

javascript
{
    "description": "",　　　　　　　　　　　　　　　　# index.json の description
    "options": {},　　　　　　　　　　　　　　　　　　　　　　　　# index.json の defaultOptions　
    "params": {},　　　　　　　　　　　　　　　　　　　　　　　　　　# index.json の param
    "scenario": "001sample"   # index.json ファイルが格納されているシナリオのディレクトリ名
} 

bash
curl -k -i -XPOST -H "Content-Type: application/json" \
                  -H "X-Xaas-Auth-Token: [x-xaas-auth-token値]" \
                  -d '{
    "description": "",
    "options": {},
    "params": {},
    "scenario": ""
  }' https://[`frontalのURL`]/apis/e2e

6. 実行状況を確認する

本項では、Test Console でのシナリオ実行状況の確認方法について紹介していきます。

6.1 実行状況の一覧を確認する

シナリオの実行状況は、[Test Console] > [E2E Test Status] で一覧を確認することができます。

確認できる各情報は以下の通りです。

6.2 実行詳細を確認する

E2E テストの詳細情報は [info] のiマークから確認することが可能です。

1. [Test Console] > E2E テストのiマーク を押下します。

   

2. 実行結果が表示されます。

   

   確認できるE2E テストの詳細情報は以下の通りです。

   scenario	シナリオ名
   description	E2E テスト実行時にdescriptionで設定した値
   start	E2E テストの開始時間
   end	E2E テストの終了時間
   tat	E2E テストが終了するまでの経過時間
   status	E2E テストの実行ステータス
   currentScenario	実行中の画面操作スクリプトファイル名
   current	実行中の画面操作スクリプトファイルの順番
   steps	シナリオ内の画面操作スクリプトのファイル数
   persent	steps / current の % 値
   error	エラー文
   options	E2E テスト実行パラメータのdefaultOptions 値
   params	E2E テスト実行パラメータのparams 値
   lastAccess	TODO 何の時間が表示されるのか記載をお願いしたい
   results	TODO 画面操作スクリプト内で何を実装すればここに表示されるのか記載をお願いしたい

   E2E テストの実行詳細を確認する手順は以上です。

6.3 E2E テストを中止する

Test Console では [status] がprocessingの E2E テストを中止することができます。

1. 中止したい E2E テストの×ボタンを押下します。

   

2. 確認画面で [Execute Cancellation] ボタンを押下します。

   

3. 実行が止まり、[Status] がCanceledになりました。

   

   E2E テストを中止する手順は以上です。

6.4 E2E テストを再実行する

Test Console では、 [Status] がcompleted/canceled/failedになった試験は同じパラメータまたは一部修正して再実行することが可能です。

1. 再実行したいE2E テスト の矢印ボタンを押下します。

   

2. 実行パラメータを確認し [Test Start] ボタンを押下します。パラメータを一部修正したい場合はここで修正してから実行します。

   

   E2E テストを再実行する手順は以上です。

6.5 エビデンスを確認する

6.5.1 実行ログを確認する

E2E Tester の実行ログは [Evidence] で確認することができます。

1. 歯車ボタンを押下します。

   

2. ポップアップ表示された test logs 画面で実行ログを確認することができます。また画面操作スクリプト内でawait actions.logger()を実装した場合もここに表示されます。

   

実行ログを確認する手順は以上です。

6.5.2 スクリーンショットを確認する

画面操作スクリプト内でawait actions.screenshot()を実装すると [Evidence] に順にスクリーンショットが並び、クリックすると確認することができます。

1. [Evidence] のナンバリングされたスクリーンショットボタンを押下します。

   

2. ポップアップ表示でスクリーンショットを確認することができます。また、左右のボタンで前後のスクリーンショットを確認することができます。

   

スクリーンショットを確認する手順は以上です。

6.5.3 エラーログを確認する

E2E Test の実行中にエラーが生じた場合、以下の箇所からエラーログを確認することができます。

• [info] ボタン > test Details 画面の [error]

  

• 歯車ボタン > test logs 画面の [test logs]

  

エラーログを確認する手順は以上です。

6.5.4 エビデンスを取得する

E2E テストのエビデンスをダウンロードする手順を記載していきます。

1. エビデンスを取得したい E2E テストの一番右のダウンロードボタンを押下します。押下すると zip 形式でエビデンスファイルのダウンロードを開始します。

   

2. エビデンスファイルにはスクリーンショットの.jpegファイル、および実行パラメータ、ログが含まれた実行情報が status.json に保存されています。TODO 下記のキャプチャのevidencesフォルダは空だったが何かファイルが入る予定なのか確認したい

   

   エビデンスを取得する手順は以上です。