Microsoftから公開されているオープンソースのE2Eテスト自動化フレームワークの
Playwrightを使って、APEXアプリケーションのE2Eテストを実施してみます。
最終的には以下の作業を行います。作業環境には、macOSのpodmanでコンテナとして動作しているOracle APEXの環境を使っています。コード内の定数
BASE_URLを変更することで、テスト対象とするアプリケーションは変えられます。PlaywrightのテストはPlaywrightをインストールした上で、VSCodeの拡張機能Playwright Test for VSCodeから実行しています。
以下より、作業について説明します。
最初にE2Eテストの対象とするAPEXアプリケーションを作成します。
サンプル・アプリケーションのサンプル・データセットのEMP/DEPTをインストールして、APEXアプリケーションを作成します。言語は英語にします。テスト・コードではページのタイトルを参照しているため、言語を日本語にすると、確認のために指定している文字列も日本語にする必要があります。
SQLワークショップのサンプル・データセットを開きます。
データ・セットEMP/DEPTのインストール（すでにインストール済みであれば更新）をクリックします。
インストールする言語の指定を求められます。言語として英語を選択します。
すでに英語でインストール済みであれば、新規言語は選択しません（- 新しい言語の選択 -から変更しません）。
次へ進みます。
新規であればデータセットのインストールをクリックします。
更新であれば既存のデータセットのリフレッシュをクリックします。
サンプル・データセットのロードが完了すると、そのデータを元にしたアプリケーションを作ることができます。
アプリケーションの作成をクリックします。
アプリケーション作成ウィザードが開きます。ダッシュボードやファセット検索のページが追加済みです。テスト用のアプリケーションに沢山のページは不要なので、機能についてはすべてチェックを外します。
以上でアプリケーションの作成をクリックします。
アプリケーションが作成されます。
アプリケーションを実行し、今回のE2Eテストで行う操作を確認します。
アプリケーションにアクセスし、表示されるログイン・ページにて、以下の操作を行います。
- ユーザー名を入力する。
- パスワードを入力する。
- サインインをクリックする。
サインインが完了すると、ホーム・ページが開きます。
ホーム・ページ上で以下の操作を行います。
- Dashboardのカードをクリックし、Dashboardのページが開くことを確認します。
- Employeesのカードをクリックし、Employeesのファセット検索のページが開くことを確認します。
- Departmentsのカードをクリックし、Departmentsの対話モード・レポートのページが開くことを確認します。
Playwrightではセレクタを使って、操作する要素を特定します。
ログイン画面ではテキスト・フィールドにユーザー名とパスワードを入力し、ボタンのサインインをクリックしています。そのため、これらのテキスト・フィールドとボタンを特定するセレクタが必要です。
どのようなセレクタが適当か確認するために開発ツールの検証を呼び出し、それぞれの要素のHTMLを確認します。
タイプがテキスト・フィールドの場合は、以下のようなHTMLが生成されていました。
<input type="text" id="P9999_USERNAME" name="P9999_USERNAME" placeholder="ユーザー名" class="text_field apex-item-text apex-item-has-icon" autocomplete="username" value="admin" size="40" maxlength="100" data-enter-submit="false" data-is-page-item-type="true">
ページ・アイテムの名前がid属性として設定されているため、セレクタとしては#ページアイテム名、つまり#P9999_USERNAMEで特定できます。パスワードも同様に#P9999_PASSWORDで特定できます。
ボタンサインインについては、BUTTON要素を特定できる適当な属性がありません。
<button class="t-Button t-Button--hot lto18565948643221472_0" type="button" id="B18565948643221472" data-otel-label="LOGIN"><span class="t-Button-label">サインイン</span></button>
そのため、ボタンに静的IDとしてLOGIN設定します。
ボタンに設定した静的IDは属性idに設定されます。そのため、このボタンをセレクタ#LOGINで特定できます。
<button class="t-Button t-Button--hot lto18565948643221472_0" type="button" id="LOGIN" data-otel-label="LOGIN"><span class="t-Button-label">サインイン</span></button>
ホーム・ページのカードについても確認します。
カードに紐ずくA要素を特定するセレクタとして使える、これといった属性がありません。
<a href="/ords/r/apexdev/demonstration-emp-dept106/dashboard?session=8435741618687" class="t-Card-wrap" data-otel-label="">
<div class="t-Card-icon u-color "><span class="t-Icon fa fa-dashboard"><span class="t-Card-initials" role="presentation"></span></span></div>
<div class="t-Card-titleWrap">
<h3 class="t-Card-title">Dashboard</h3>
<h4 class="t-Card-subtitle"></h4>
</div>
<div class="t-Card-body">
<div class="t-Card-desc"></div>
<div class="t-Card-info"></div>
</div>
<span class="t-Card-colorFill u-color " aria-hidden="true"></span>
</a>
ページの設定を確認します。
ページ・ナビゲーションのリージョンのタイプはリストです。
左ペインで
ページ共有コンポーネントを開き、リストに適用されているテンプレートを見つけ（テンプレート
Cardsが適用されています）、
コンポーネントの編集をクリックします。
このリージョンが参照しているHTMLのテンプレートが表示されます。
リスト・テンプレートCardsのテンプレート定義を確認します。
A要素はテンプレート定義のカレント・リスト・テンプレートおよび非カレント・リスト・テンプレートで、以下のように記述されています。
<a href="#LINK#" class="t-Card-wrap" #A05# data-otel-label="#A10#">
置換文字列#A05#に、セレクタとして利用可能な属性を設定することにします。
置換文字列#A05#に設定する文字列は、Dashboardのカードにid="menu-dashboard"、Employeesにid="menu-employees"、Departmentsにはid="menu-departments"とします。
ページ・ナビゲーションのソースを確認します。
ソースとなるリストはページ・ナビゲーションです。
リストのソースは共有コンポーネントとして作成されています。
共有コンポーネントのリストを開きます。
リストの一覧にページ・ナビゲーションがあります。名前のリンクをクリックして、ページ・ナビゲーションを開きます。
リスト・エントリとしてDashboard、Employees、Departmentsが含まれています。
最初にDashboardを開いて、属性を追加します。
テンプレート定義に含まれる置換文字列#A01#から#A10#は、ユーザー定義属性です。セクションのユーザー定義属性に移動し、置換文字列#A05#に対応している5. Link Attributesとしてid="menu-dashboard"を設定します。
変更の適用をクリックします。
同様にリスト・エントリEmployeesを開き、ユーザー定義属性の5. Link Attributesとしてid="menu-employees"を設定します。
リスト・エントリDepartmentsの5. Link Attributesにid="menu-departments"を設定します。
以上で、Playwrightを使ってE2Eテストを行うために必要な、APEXアプリケーションの改変は完了です。
続いてPlaywrightをインストールします。PlaywrightのGetting StartedのInstallationの記述に従って、作業を行います。
いくつか方法がありますが、今回はnpmでインストールしました。
今回のE2Eテストを作成するディレクトリを作成します。本作業ではPlaywrightとしました。
mkdir Playwright
作成したディレクトリに移動し、Playwrightをインストールします。
cd Playwright
npm init playwright@latest
プロジェクトの初期化に当たって、いくつか質問されます。今回はすべてデフォルトの設定で初期化しています。デフォルトではテスト・スクリプトの記述はTypeScriptで行い、テスト・スクリプトはサブフォルダのtestsに保存されます。
% cd Playwright
Playwright % npm init playwright@latest
> npx
> create-playwright
Getting started with writing end-to-end tests with Playwright:
Initializing project in '.'
✔ Do you want to use TypeScript or JavaScript? · TypeScript
✔ Where to put your end-to-end tests? · tests
✔ Add a GitHub Actions workflow? (y/N) · false
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) · true
Initializing NPM project (npm init -y)…
Wrote to /Users/ynakakoshi/Documents/Playwright/package.json:
{
"name": "playwright",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": ""
}
Installing Playwright Test (npm install --save-dev @playwright/test)…
added 3 packages, and audited 4 packages in 1s
found 0 vulnerabilities
Installing Types (npm install --save-dev @types/node)…
added 3 packages, and audited 7 packages in 640ms
found 0 vulnerabilities
Writing playwright.config.ts.
Writing tests/example.spec.ts.
Writing tests-examples/demo-todo-app.spec.ts.
Writing package.json.
Downloading browsers (npx playwright install)…
✔ Success! Created a Playwright Test project at /Users/ynakakoshi/Documents/Playwright
Inside that directory, you can run several commands:
npx playwright test
Runs the end-to-end tests.
npx playwright test --ui
Starts the interactive UI mode.
npx playwright test --project=chromium
Runs the tests only on Desktop Chrome.
npx playwright test example
Runs the tests in a specific file.
npx playwright test --debug
Runs the tests in debug mode.
npx playwright codegen
Auto generate tests with Codegen.
We suggest that you begin by typing:
npx playwright test
And check out the following files:
- ./tests/example.spec.ts - Example end-to-end test
- ./tests-examples/demo-todo-app.spec.ts - Demo Todo App end-to-end tests
- ./playwright.config.ts - Playwright Test configuration
Visit https://playwright.dev/docs/intro for more information. ✨
Happy hacking! 🎭
Playwright %
VSCodeに拡張機能のPlaywright Test for VSCodeをインストールします。
VSCodeから先ほど作成したE2Eテストのプロジェクト・フォルダ（今回の作業ではPlaywrightとして作成）を開きます。プロジェクトが初期化されていて、雛形となるファイルが作成されています。
エクスプローラーからファイルplaywright.config.tsを選択し、以下の内容に置き換えます。chromiumのプロジェクトにviewportとstorageStateの設定を加えています。
テスト・スクリプトを配置するフォルダtestsに、以下のファイルfixtures.tsを作成します。このファイルに、APEXアプリケーションへサインインする手順を記述しています。
BASE_URLは、先ほど作成したAPEXアプリケーションを指すURLに変更します。
プロジェクトのフォルダの直下にフォルダ.authを作成します。認証情報を保存するファイルauth.jsonと、ブラウザの状態を保存するファイルstate.jsonを配置します。
フォルダ.auth直下にファイルauth.jsonを作成します。内容として、以下を記述します。usernameとpasswordは環境に合わせて変更します。sessionIdはログイン後にテスト・スクリプトによって更新されるため、値はそのままで問題ありません。
{"username":"admin","password":"4fae#ae2ef3!!","sessionId":"17291688537780"}
フォルダ.auth直下にブラウザのステータスを保存するファイルstate.jsonを作成します。内容はとして{}を記述し、空のJSONオブジェクトが保存されている状態にします。
最後に今回実施するE2Eテストを記述したファイルapex.spec.tsを、フォルダtests以下に作成します。
以上でPlaywrightを使ってE2Eテストを実行する準備ができました。
作成したファイルをすべて保存し、Playwrightの拡張機能を開きます。
testsとして認識されているapex.spec.tsにある実行ボタンをクリックすることで、apex.spec.tsに記述されている一連のテストが実行されます。apex.spec.tsにはopen Dashboard、open Employees、open Departmentsの３つのテストが含まれています。
それぞれ個別に実行できますが、open Dashboardでユーザー認証を行なっている都合上、最初にopen Dashboardのテストを実行する必要があります。
今回の記事は以上になります。
Oracle APEXのアプリケーション作成の参考になれば幸いです。
