gauge-playwright-helpers

Gauge + Playwright による E2E テストのための再利用可能なヘルパーライブラリです。

インストール

npm install @yukinissie/gauge-playwright-helpers

ピア依存パッケージ

以下のパッケージを別途インストールしてください。

npm install gauge-ts playwright @playwright/test
# PostgreSQL を使う場合
npm install pg

モジュール一覧

ApiContext

Playwright の APIRequestContext と最後のレスポンスを保持するシングルトン状態オブジェクトです。API テストのステップ間で共有して使います。

import { ApiContext } from "@yukinissie/gauge-playwright-helpers";

// Gauge の BeforeSuite / BeforeSpec フックで初期化
await ApiContext.initRequestContext();

// ステップ内で利用
const response = await ApiContext.requestContext.get("https://example.com/api");
ApiContext.response = response;

// AfterSuite / AfterSpec フックで破棄
await ApiContext.disposeRequestContext();

BrowserSession

Playwright の Browser / BrowserContext / Page を保持するシングルトン状態オブジェクトです。

import { BrowserSession } from "@yukinissie/gauge-playwright-helpers";

await BrowserSession.launchBrowser();       // ブラウザ起動
await BrowserSession.newContext();          // コンテキスト & ページ生成
const page = BrowserSession.page;          // Page を取得
await BrowserSession.closeContext();
await BrowserSession.closeBrowser();

CommonApiSteps

API テスト用のビルトイン Gauge ステップクラスです。

注意: gauge-ts は tests/ 配下の .ts ファイルをスキャンしてステップを登録します。CommonApiSteps を使うには、消費プロジェクトの tests/ 配下にリエクスポートするファイルを置いてください。

// tests/steps/apiSteps.ts
export { default as CommonApiSteps } from "@yukinissie/gauge-playwright-helpers";

| ステップ | 説明 | |---------|------| | GET リクエストを <url> に送信する | GET リクエストを送信 | | POST リクエストを <url> にボディ <jsonBody> で送信する | JSON ボディ付き POST | | PUT リクエストを <url> にボディ <jsonBody> で送信する | JSON ボディ付き PUT | | DELETE リクエストを <url> に送信する | DELETE リクエストを送信 | | ステータスコードが <statusCode> であること | ステータスコードを検証 | | レスポンスボディに <key> が含まれていること | レスポンスのキー存在を検証 | | レスポンスボディの <key> が <value> であること | レスポンスの値を検証 | | レスポンスボディの <key> が null であること | レスポンスの値が null であることを検証 | | レスポンスボディの <key> が数値であること | レスポンスの値が数値であることを検証 |

CommonBrowserSteps

ブラウザ操作用のビルトイン Gauge ステップクラスです。

// tests/steps/browserSteps.ts
export { default as CommonBrowserSteps } from "@yukinissie/gauge-playwright-helpers";

| ステップ | 説明 | |---------|------| | ページ <url> にアクセスする | 指定 URL へ遷移 | | ページに <content> が表示されていること | テキストの表示を検証 | | <field> フィールドに <value> を入力する | name 属性でフィールドを特定して入力 | | <button> ボタンをクリックする | ボタンをクリック | | ページ <url> に遷移したこと | URL への遷移を検証 | | <placeholder> プレースホルダーに <value> を入力する | プレースホルダーでフィールドを特定して入力 | | <text> をクリックする | テキストをクリック |

DbClient

PostgreSQL クライアントのラッパーです。

import { DbClient } from "@yukinissie/gauge-playwright-helpers";

const db = new DbClient({
  host: "localhost",
  port: 5432,
  user: "postgres",
  password: "password",
  database: "mydb",
});

await db.executeSql("INSERT INTO users (name) VALUES ('Alice')");

DbLifecycle

マイグレーション実行とテーブルリセットのユーティリティです。

import { DbLifecycle } from "@yukinissie/gauge-playwright-helpers";

const lifecycle = new DbLifecycle({
  client: db,
  migrationDir: "db/migrations", // サブディレクトリに up.sql を置く形式
  excludeTables: ["schema_migrations"], // リセット対象外テーブル
});

await lifecycle.runMigrations(); // スキーマを DROP して再作成後にマイグレーション実行
await lifecycle.resetDb();       // 全テーブルを TRUNCATE

CsvLoader

CSV ファイルの内容を PostgreSQL テーブルに INSERT します。ファイル名 (01_users.csv → users テーブル) からテーブル名を解決します。

import { CsvLoader } from "@yukinissie/gauge-playwright-helpers";

const loader = new CsvLoader(db);
await loader.loadCsvData("fixtures/01_users.csv");

WireMockClient / WireMockControl

WireMock の管理 API を操作するクライアントと、Gauge シナリオ名に基づいてモックファイルをロードするコントローラーです。

シナリオ名の末尾に -- <mock-name> を付けることで、対応するモックディレクトリが自動的に読み込まれます。

specs/
  my_spec/
    mocks/
      my-service/
        mappings/
          my-mock/
            response.json

import { WireMockControl } from "@yukinissie/gauge-playwright-helpers";

const wireMock = new WireMockControl([
  { name: "my-service", port: 8080 },
]);

// Gauge の BeforeScenario フックで呼び出す
await wireMock.loadMocksForScenario(context);

waitForUrl

指定した URL が HTTP 200 を返すまでポーリングします。サービスの起動待ちに使います。

import { waitForUrl } from "@yukinissie/gauge-playwright-helpers";

await waitForUrl("http://localhost:8080/health", 30000, 1000);

ライセンス

MIT