Playwright
公式パッケージ @chobitmail/playwright は、Playwright テストごとにワンタイム受信箱を作成・削除し、OTP や確認リンクを待つ fixture を提供します。
生の REST で 408 再接続ループを書く必要はありません。
必要条件
- Node.js 18+
- ESM（
"type": "module"または bundler） @playwright/test>= 1.42.0（peer）
インストール
pnpm add -D @chobitmail/playwright
export CHOBITMAIL_API_KEY=cbm_live_...
キーははじめにのとおりダッシュボードで発行します。
AI コーディングエージェント向け Skill もあります。
npx skills add chobitapp/chobitmail-skills
最短の例
import { test, expect } from "@chobitmail/playwright";
test("サインアップの認証コードを検証できる", async ({ page, inbox }) => {
await page.goto("https://myapp.example/signup");
await page.getByLabel("Email").fill(inbox.address);
await page.getByRole("button", { name: /sign up|登録/i }).click();
// OTP は waitForCode（waitForOtp ではない）
const code = await inbox.waitForCode({ subject: "認証コード" });
await page.getByLabel(/code|otp|認証/i).fill(code);
await page.getByRole("button", { name: /submit|確認/i }).click();
await expect(page.getByText(/完了|welcome/i)).toBeVisible();
// inbox は fixture がテスト終了時に DELETE
});
主な API
| Fixture / API | 役割 |
|---|---|
inbox |
テストごとに自動作成・自動削除 |
chobitmail |
共有クライアント（追加受信箱・usage） |
inboxOptions |
test.use({ inboxOptions: { ttl, autoCreate, autoDelete } }) |
inbox.waitForMessage |
長ポーリング + 408 再接続 |
inbox.waitForCode |
条件に合う最初のメールから OTP |
inbox.waitForLink |
条件に合う最初のメールから URL |
ChobitmailClient |
fixture なしで利用 |
runWithInbox |
create / use / delete のライフサイクル補助 |
選択の意味（fail-fast）
waitForCode / waitForLink は、subject / from / timestamp_* に最初にマッチした 1 通を見ます。
そのメールに codes/links が無ければ ChobitmailSelectionError で失敗し、後続メールを待ちません。
対策:
subject/fromを OTP・確認メールのテンプレートに絞るtimestamp_from（テスト開始時刻の ms）で以前のノイズを除外する- または
waitForMessageで自分でmessage.codes/message.linksを選ぶ
確認リンク
const link = await inbox.waitForLink({
subject: "確認",
includes: "/verify",
});
await page.goto(link);
他 fixture との合成（mergeTests）
// fixtures/index.ts
import { mergeTests } from "@playwright/test";
import { test as chobitmailTest, expect } from "@chobitmail/playwright";
import { authTest } from "./auth";
export const test = mergeTests(chobitmailTest, authTest);
export { expect };
手動で受信箱を扱う
test.use({ inboxOptions: { autoCreate: false } });
test("manual", async ({ chobitmail }) => {
const box = await chobitmail.createInbox({ ttl: 600 });
try {
// ...
} finally {
await box.delete();
}
});
CI
# GitHub Actions
env:
CHOBITMAIL_API_KEY: ${{ secrets.CHOBITMAIL_API_KEY }}
無料枠の同時アクティブ受信箱は未検証で 1 です。メール依存プロジェクトでは並列を抑えてください。
// playwright.config.ts
export default defineConfig({
workers: 1, // free の concurrent=1 向け
});
送信元ドメインを検証すると同時枠と日次上限が広がります。詳しくは送信元ドメイン検証。
リポジトリ
- npm:
@chobitmail/playwright - ソース: github.com/chobitapp/chobitmail-playwright
- サンプル: monorepo の
example/playwright（開発者向け）