最終的には以下の作業を行います。作業環境には、macOSのpodmanでコンテナとして動作しているOracle APEXの環境を使っています。コード内の定数BASE_URLを変更することで、テスト対象とするアプリケーションは変えられます。PlaywrightのテストはPlaywrightをインストールした上で、VSCodeの拡張機能Playwright Test for VSCodeから実行しています。
タイプがテキスト・フィールドの場合は、以下のようなHTMLが生成されていました。
以下より、作業について説明します。
最初にE2Eテストの対象とするAPEXアプリケーションを作成します。
サンプル・アプリケーションのサンプル・データセットのEMP/DEPTをインストールして、APEXアプリケーションを作成します。言語は英語にします。テスト・コードではページのタイトルを参照しているため、言語を日本語にすると、確認のために指定している文字列も日本語にする必要があります。
SQLワークショップのサンプル・データセットを開きます。
データ・セットEMP/DEPTのインストール（すでにインストール済みであれば更新）をクリックします。
インストールする言語の指定を求められます。言語として英語を選択します。
すでに英語でインストール済みであれば、新規言語は選択しません（- 新しい言語の選択 -から変更しません）。
次へ進みます。
新規であればデータセットのインストールをクリックします。
更新であれば既存のデータセットのリフレッシュをクリックします。
サンプル・データセットのロードが完了すると、そのデータを元にしたアプリケーションを作ることができます。
アプリケーションの作成をクリックします。
アプリケーション作成ウィザードが開きます。ダッシュボードやファセット検索のページが追加済みです。テスト用のアプリケーションに沢山のページは不要なので、機能についてはすべてチェックを外します。
以上でアプリケーションの作成をクリックします。
アプリケーションが作成されます。
アプリケーションを実行し、今回のE2Eテストで行う操作を確認します。
アプリケーションにアクセスし、表示されるログイン・ページにて、以下の操作を行います。
- ユーザー名を入力する。
- パスワードを入力する。
- サインインをクリックする。
サインインが完了すると、ホーム・ページが開きます。
ホーム・ページ上で以下の操作を行います。
- Dashboardのカードをクリックし、Dashboardのページが開くことを確認します。
- Employeesのカードをクリックし、Employeesのファセット検索のページが開くことを確認します。
- Departmentsのカードをクリックし、Departmentsの対話モード・レポートのページが開くことを確認します。
Playwrightではセレクタを使って、操作する要素を特定します。
ログイン画面ではテキスト・フィールドにユーザー名とパスワードを入力し、ボタンのサインインをクリックしています。そのため、これらのテキスト・フィールドとボタンを特定するセレクタが必要です。
どのようなセレクタが適当か確認するために開発ツールの検証を呼び出し、それぞれの要素の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>ページ・ナビゲーションのリージョンのタイプはリストです。
このリージョンが参照している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
% mkdir Playwright
%
cd Playwright
npm init playwright@latest
{"username":"admin","password":"4fae#ae2ef3!!","sessionId":"17291688537780"}
プロジェクトの初期化に当たって、いくつか質問されます。今回はすべてデフォルトの設定で初期化しています。デフォルトではテスト・スクリプトの記述は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の設定を加えています。
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| import { defineConfig, devices } from '@playwright/test'; | |
| /** | |
| * Read environment variables from file. | |
| * https://github.com/motdotla/dotenv | |
| */ | |
| // import dotenv from 'dotenv'; | |
| // import path from 'path'; | |
| // dotenv.config({ path: path.resolve(__dirname, '.env') }); | |
| /** | |
| * See https://playwright.dev/docs/test-configuration. | |
| */ | |
| export default defineConfig({ | |
| testDir: './tests', | |
| /* Run tests in files in parallel */ | |
| fullyParallel: true, | |
| /* Fail the build on CI if you accidentally left test.only in the source code. */ | |
| forbidOnly: !!process.env.CI, | |
| /* Retry on CI only */ | |
| retries: process.env.CI ? 2 : 0, | |
| /* Opt out of parallel tests on CI. */ | |
| workers: process.env.CI ? 1 : undefined, | |
| /* Reporter to use. See https://playwright.dev/docs/test-reporters */ | |
| reporter: 'html', | |
| /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */ | |
| use: { | |
| /* Base URL to use in actions like `await page.goto('/')`. */ | |
| // baseURL: 'http://127.0.0.1:3000', | |
| /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */ | |
| trace: 'on-first-retry', | |
| }, | |
| /* Configure projects for major browsers */ | |
| projects: [ | |
| { | |
| name: 'chromium', | |
| use: { | |
| ...devices['Desktop Chrome'], | |
| viewport: { width: 1280, height: 1280 }, | |
| storageState: './.auth/state.json', | |
| }, | |
| }, | |
| { | |
| name: 'firefox', | |
| use: { ...devices['Desktop Firefox'] }, | |
| }, | |
| { | |
| name: 'webkit', | |
| use: { ...devices['Desktop Safari'] }, | |
| }, | |
| /* Test against mobile viewports. */ | |
| // { | |
| // name: 'Mobile Chrome', | |
| // use: { ...devices['Pixel 5'] }, | |
| // }, | |
| // { | |
| // name: 'Mobile Safari', | |
| // use: { ...devices['iPhone 12'] }, | |
| // }, | |
| /* Test against branded browsers. */ | |
| // { | |
| // name: 'Microsoft Edge', | |
| // use: { ...devices['Desktop Edge'], channel: 'msedge' }, | |
| // }, | |
| // { | |
| // name: 'Google Chrome', | |
| // use: { ...devices['Desktop Chrome'], channel: 'chrome' }, | |
| // }, | |
| ], | |
| /* Run your local dev server before starting the tests */ | |
| // webServer: { | |
| // command: 'npm run start', | |
| // url: 'http://127.0.0.1:3000', | |
| // reuseExistingServer: !process.env.CI, | |
| // }, | |
| }); |
テスト・スクリプトを配置するフォルダtestsに、以下のファイルfixtures.tsを作成します。このファイルに、APEXアプリケーションへサインインする手順を記述しています。
BASE_URLは、先ほど作成したAPEXアプリケーションを指すURLに変更します。
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| import { test as base } from "@playwright/test"; | |
| import path from 'path'; | |
| import * as fs from 'fs'; | |
| /* | |
| * プロジェクトのフォルダ直下に.authフォルダを作成し、その中にauth.jsonを作成する。 | |
| * auth.jsonの中身は以下のようにする。 | |
| * ログイン・ユーザー名とパスワードは、実際のものに置き換えること。 | |
| * {"username":"admin","password":"4fae#ae2ef3!!","sessionId":"17291688537780"} | |
| * | |
| * 初回実行時のために、state.jsonファイルを作成しておく。 | |
| * echo "{}" > .auth/state.json | |
| * | |
| * BASE_URLは、テスト実行時に使用するURLを指定する。 | |
| */ | |
| export const authFile = path.join(__dirname, '../.auth/auth.json'); | |
| export const BASE_URL = 'http://localhost:8181/ords/r/apexdev/demonstration-emp-dept'; | |
| const stateFile = path.join(__dirname, '../.auth/state.json'); | |
| export const test = base.extend({ | |
| // Create a custom fixture | |
| loginUser: async ({ page }, use) => { | |
| // auth.jsonからユーザー名とパスワードを取り出す。 | |
| const auth = JSON.parse(fs.readFileSync(authFile, 'utf8')); | |
| /* | |
| * 最初にホーム・ページにアクセスするが、URLにsession=が含まれていないため、ログイン・ページに遷移する。 | |
| */ | |
| await page.goto(`${BASE_URL}/home`); | |
| /* | |
| * ページ・作成ウィザードが生成したログイン・ページであれば、 | |
| * ページ・アイテム名がIDと同じINPUT要素が作成されている。 | |
| */ | |
| await page.fill("input#P9999_USERNAME", auth.username); | |
| await page.fill("input#P9999_PASSWORD", auth.password); | |
| // await page.click("input#P9999_REMEMBER"); | |
| // サインイン・ボタンをクリックする。ボタンに静的IDとしてLOGINを設定する必要がある。 | |
| await page.click("button#LOGIN"); | |
| /* | |
| * サインインに成功した後、ホーム・ページに遷移する。 | |
| * ページ・遷移後のURLからsessioin=の引数に設定されている | |
| * セッションIDを取り出し、auth.jsonに保存する。 | |
| * このセッションIDを後続のテストで使用する。 | |
| * | |
| * 完全にホーム・ページに遷移したことを確認するためにwaitForSelectorを呼び出しているが、 | |
| * もっと汎用的な方法があるはず。 | |
| */ | |
| await page.waitForSelector('#menu-dashboard'); | |
| // URLからセッションIDを取り出す。 | |
| const homeURL = new URL(page.url()); | |
| const sessionId = homeURL.searchParams.get('session'); | |
| // auth.jsonにsessionIdとして保存する。 | |
| const newAuth = { ...auth, sessionId: sessionId }; | |
| fs.writeFileSync(authFile, JSON.stringify(newAuth)); | |
| // console.log('afer signin - auth', newAuth); | |
| /* | |
| * contextをstate.jsonに保存する。 | |
| */ | |
| await page.context().storageState({ path: stateFile }); | |
| // const cookies = await page.context().cookies(); | |
| // console.log('cookies', cookies); | |
| // Pass control back to the test | |
| await use(); | |
| }, | |
| }); |
プロジェクトのフォルダの直下にフォルダ.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以下に作成します。
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| import { expect } from '@playwright/test'; | |
| import { test, authFile, BASE_URL } from './fixtures.ts'; | |
| import path from 'path'; | |
| import * as fs from 'fs'; | |
| test('open Dashboard', async ({ page, loginUser }) => { | |
| /* | |
| * fixtures.jsに記載されているloginUserが呼び出される。 | |
| * サインインに成功した後は、ホーム・ページが開かれている。 | |
| */ | |
| // 表示されているページにダッシュボードのカードがあることを確認する。 | |
| await page.waitForSelector('#menu-dashboard', { timeout: 5000 }); | |
| // ダッシュボードのカードをクリックする。#menu-dashboardはAPEX側に要設定。 | |
| await page.click("a#menu-dashboard"); | |
| // ダッシュボードのページが開かれていることを確認する。 | |
| await expect(page).toHaveTitle('Dashboard'); | |
| }); | |
| /* | |
| test('verify', async ({ page }) => { | |
| // call page without fixture. | |
| await page.goto('http://localhost:8181/ords/apexdev/test/test'); | |
| }); | |
| */ | |
| test('open Employees', async ({ page }) => { | |
| /* | |
| * loginUserは呼び出さず、サインインが継続している状態から始める。 | |
| * auth.jsonに保存されているsessionIdを使用して、ホームページを開く。 | |
| * auth.jsonは、fixtures.jsのloginUserで、サインイン時にsessionIdが更新されている。 | |
| */ | |
| const auth = JSON.parse(fs.readFileSync(authFile, 'utf8')); | |
| // ホーム・ページを開く。 | |
| const home_url = `${BASE_URL}/home?session=${auth.sessionId}`; | |
| console.log(home_url); | |
| await page.goto(home_url); | |
| // ホーム・ページに従業員一覧のカードがあることを確認し、クリックする。#menu-employeesはAPEX側に要設定。 | |
| await page.waitForSelector('#menu-employees', { timeout: 3000 }); | |
| await page.click("a#menu-employees"); | |
| // 従業員のページが開かれていることを確認する。 | |
| await expect(page).toHaveTitle('Employees'); | |
| }); | |
| test('open Departments', async ({ page }) => { | |
| /* | |
| * 従業員一覧に同じ。 | |
| */ | |
| const auth = JSON.parse(fs.readFileSync(authFile, 'utf8')); | |
| // ホーム・ページを開く。 | |
| const home_url = `${BASE_URL}/home?session=${auth.sessionId}`; | |
| console.log(home_url); | |
| await page.goto(home_url); | |
| // ホーム・ページに部門一覧のカードがあることを確認し、クリックする。#menu-departmentsはAPEX側に要設定。 | |
| await page.waitForSelector('#menu-departments', { timeout: 3000 }); | |
| await page.click("a#menu-departments"); | |
| // 部門のページが開かれていることを確認する。 | |
| await expect(page).toHaveTitle('Departments'); | |
| }); |
作成したファイルをすべて保存し、Playwrightの拡張機能を開きます。
testsとして認識されているapex.spec.tsにある実行ボタンをクリックすることで、apex.spec.tsに記述されている一連のテストが実行されます。apex.spec.tsにはopen Dashboard、open Employees、open Departmentsの３つのテストが含まれています。
それぞれ個別に実行できますが、open Dashboardでユーザー認証を行なっている都合上、最初にopen Dashboardのテストを実行する必要があります。
今回の記事は以上になります。
Oracle APEXのアプリケーション作成の参考になれば幸いです。
完
