コンテンツにスキップ

English · 日本語

ブラウザでシナリオを実行する

このページでは、Getting started のループをどの OS でも完結させます。実際の web アプリに 対して、ブラウザ上で Playwright backend を使って実行します。macOS も Xcode も iOS Simulator も 要りません。Mac もある場合は、代わりにiOS トラックで同じループを Simulator 上で完結できます。

関連: Getting started · iOS トラック · drivers · 用語集

まず共通ウォークスルーのステップ 1〜3(インストール、ユニットテスト、シナリオを読む)を 済ませてください。ステップ 1 は基本のインストールを扱い、このページは web backend が追加で必要と する 1 行だけを足します。このページはステップ 4 から続きます。

なぜ web トラックがあるのか

Bajutsu の看板の主張は「プラットフォームは backend にすぎない」です。決定的コア、シナリオ形式、 レポーターは、UI を実際に操作する backend が何であっても同じです。iOS トラックは Simulator(XCUITest backend)で完結しますが、Xcode 入りの Mac が必要です。web トラックは同じ ループをブラウザ(web / Playwright backend)で完結させます。ブラウザなら、Linux でも Windows でも macOS でも同じように動きます。Bajutsu 自身の web デモを Linux のゲート上で動かしているのも、同じ backend です(demos/web)。

ここでの用語は用語集に従います。backend はターゲットが platform: で宣言する プラットフォーム(ここでは web)です。backend は actuator(タップや入力を実際に行う Playwright エンジン)に解決されます。target はテスト対象アプリを記述する targets.<name> の設定エントリ一つで、web の場合は iOS アプリの subject.id ではなく subject.url で識別されます。

必要なもの

目的 必要なもの
ステップ 1〜3(共通) 任意の OS、Python 3.13(uv で管理)
以下のステップ 4〜5 uv sync --extra web + uv run playwright install chromium(Mac / Simulator 不要)
uv sync --extra web                        # Playwright の Python パッケージを追加
uv run playwright install chromium         # Playwright が操作する Chromium バイナリを取得

--extra web の行と playwright install の行が、ステップ 1 の 基本インストールに web backend が上乗せする分です。Chromium バイナリは pip の依存ではなく、別途 ダウンロードされます。

ステップ 4:デモ web アプリを配信する

web デモは、demos/web/app の下に小さな静的アプリを同梱しています。 オンボーディング → ログイン → カウンターという流れを、素の JavaScript と安定した data-testid id で 書いたものです。ブラウザ(と Bajutsu)から届くように、ローカルで配信します。

make -C demos/web app-serve        # demos/web/app を 127.0.0.1:8787 で配信(Ctrl-C で停止)

配信したまま、自分のブラウザで http://127.0.0.1:8787/index.html を開くと、アプリに手で触れます。 Get started を押し、任意のメールアドレスとパスワードでサインインし、カウンターを増やしてみてください。 この流れそのものを、デモのシナリオが自動化しています。

scenarios:
  - name: onboard, log in, and increment the counter
    steps:
      - tap: { id: onboarding.start }
      - type: { text: "a@b.com", into: { id: auth.email } }
      - type: { text: "pw", into: { id: auth.password } }
      - tap: { id: auth.submit }
      - wait: { for: { id: home.title }, timeout: 5 }   # 固定 sleep ではなく条件待ち
      - tap: { id: counter.increment }
      - tap: { id: counter.increment }
    expect:
      - exists: { id: home.title }
      - value: { sel: { id: counter.value }, equals: "2" }

このシナリオは、共通ウォークスルーの iOS 側の smoke テストと まったく同じ step/expect の文法を使っています。

  • steps が操作し、expect が判定します。
  • セレクタは id 優先です。ここでの id は data-testid で、iOS の accessibilityIdentifier に相当する web 側の属性です。他のどの backend とも同じセレクタ解決コアを通ります (selectors、drivers 参照)。
  • 待機は条件です。
  • 曖昧なセレクタは即座に失敗します。

トラックごとに違うのは、個々のシナリオの中身だけです。全文は demos/web/scenarios/smoke.yaml にあります。

ステップ 5:ブラウザでシナリオを実行する

一発で済ませる経路は make ターゲットです。必要なら web backend を導入し、アプリをバックグラウンドで 配信し、デモのシナリオを Playwright で実行し、サーバーを片付けます。手動での配信は要りません。

make -C demos/web e2e

あるいは、ステップ 4 で配信したアプリに対して CLI を直接動かします(同じ実行を書き下したものです)。

uv run bajutsu run --scenario demos/web/scenarios/smoke.yaml --target web --backend web --config demos/web/demo.config.yaml

フラグの意味は次のとおりです。

  • --target web は demos/web/demo.config.yaml の targets.web (その platform: web、subject.url、シナリオディレクトリ)を選びます。ツール自体はアプリ非依存で、target ごとの差分は すべて config に置かれます(configuration)。
  • --backend web は backend を確かめます。actuator(Chromium を操作する Playwright エンジン)は ターゲットの platform: web がすでに選んでおり、食い違う値を渡すと終了コード 2 で終わります。 Xcode も Simulator も関わりません。
  • --scenario を省くと target のシナリオディレクトリ全体を実行します(make -C demos/web e2e が 行っているのがこれです)。

成功すると、次のような行が出ます。

PASS  runs/20260610-120000/manifest.json

run はすべてのシナリオが通れば 0、一つでも失敗すれば 1 を返します。この終了コードが CI (継続的インテグレーション)のゲートです(run-loop)。合否はシナリオの機械的な アサーション(カウンターが 2 を示すこと)だけで決まり、LLM は関わりません。

環境の問題(Chromium が未インストール、web extra が未導入など)に当たったら、まず uv run bajutsu doctor --target web --config demos/web/demo.config.yaml を走らせてください。 web backend が必要とするものの ✓/✗ チェックリストを表示します。

共通ウォークスルーのステップ 6:レポートを読むへ進んでください (macOS の open の代わりに Linux では xdg-open を使います)。

AI でオーサリングする(web)

Claude に web アプリをゴールへ向けて探索させ、シナリオを書かせられます(Tier 1)。.env ファイルに ANTHROPIC_API_KEY=sk-ant-… を入れてから、次を実行します。

make -C demos/web record GOAL="Get started, then increment the counter three times and confirm it shows 3."

キーもブラウザもない場合は、オフラインの双子が同じ record ループを決定的に再現します (make -C demos/web record-offline)。オーサリングループの仕組みは recording にあります。

自分の web アプリをオンボーディングする

新しい targets.<name> エントリ(platform: web)の subject.url を自分のアプリの URL に向け、要素に安定した data-testid id を 付けます。configuration を参照してください。