コンテンツにスキップ

English · 日本語

Getting started

手を動かして辿るチュートリアルです。Bajutsu のインストールから、ユニットテストの実行、シナリオの 読解、実際のアプリの操作、HTML レポートの表示までを順に進めます。他のページは各機能の役割を説明する リファレンスです。このページは、手順を順に実行していくチュートリアルです。

関連: cli · scenarios · run-loop · reporting


2 つのトラック、1 つのループ

以下のステップ 1〜3 と 6 は、何を操作するかに関わらず共通です。インストール、ユニットテスト、 シナリオを読む、レポートを読む、という部分です。異なるのはステップ 4〜5 だけです。対象アプリを ビルドまたは配信し、そのアプリに対してシナリオを実行する部分で、 backend ごとに変わります。「プラットフォームは backend にすぎない」からです(concepts)。

  • iOS トラック:XCUITest backend で iOS Simulator 上まで完結します。macOS と Xcode が 必要です。
  • web トラック:Playwright backend でブラウザに対して完結します。Linux、Windows、 macOS のどの OS でも動き、Xcode も Simulator も不要です。

自分のマシンに合うほうを選ぶか、両方試してください。同じシナリオスキーマ、ランナー、CLI が、 どちらのターゲットも変わらず操作します。

始めるのに Claude は要りません。 モデルに到達するのは AI オーサリングの経路だけです。run、 doctor、lint、codegen、trace などは設定ゼロで動きます。キーも .env もログインも不要です。 どのコマンドが Claude を使い、どれが使わないかは Claude を使う機能と使わない機能にまとめてあります。

ステータス注記。 Bajutsu は pre-alpha です。決定的コア、AI オーサリングループ、証跡サブシステム、 codegen はいずれも実装済みで、ユニットテストも揃っています。実機実行は iOS Simulator と Android エミュレータの両方で end-to-end に検証済みで、web(Playwright)backend も同じ決定的なループを ブラウザ上で動かします。実機ステップで不審な挙動が出たら、安定しているユニットテストに戻ってください。


ステップ 1:インストール

git clone <this repo> && cd bajutsu       # もしくはチェックアウト済みディレクトリへ cd
uv sync --group dev                        # .venv(Python 3.13)+ 依存 + 開発ツールを作成

uv は pyproject.toml / uv.lock を読み、隔離された .venv を構築します。プロジェクトの コマンドは uv run(例 uv run bajutsu …)を前に付け、この環境で実行してください。

PyPI からインストールする場合:基本パッケージは AI-free です。pip install bajutsu は 決定論的なオーサリングと実行の経路を AI SDK なしで導入し、pip install bajutsu[ai](または bajutsu[bedrock])が Claude の経路のための SDK を追加します。分離の詳細は What uses Claudeにあります。基本パッケージには サーバの依存(FastAPI、uvicorn、SQLAlchemy、Alembic、cryptography)も入っているので、 bajutsu serve は追加の extra なしに1台のマシンで起動します。server と db の extra が追加するのは、hosted のデプロイが使うクライアントだけです。S3 のバケット向けの boto3 と、 PostgreSQL 向けの psycopg がこれにあたります。

CLI(コマンドラインインターフェース)が配線されているかを確認します。

uv run bajutsu --help

run / doctor / record / crawl / repl / codegen / trace / triage / approve / serve / mcp / worker / lint / schema / audit / coverage / export / flakiness / impact / report / stats のコマンドが表示されます(完全なリファレンスは cli)。

web トラックは、この上にもう 1 つだけインストール手順(Playwright のブラウザ)を足します。iOS トラックに必要なのは Xcode だけで、XCUITest backend が Xcode を直接操作します。詳細は選んだ トラックのページを参照してください。


ステップ 2:ユニットテストを走らせる

ユニットテストの実行は、すべてが健全かを確かめる最速の手段です。ユニットテストは、決定性コア、 シナリオスキーマ、アサーション、run ループをインメモリの fake driver に対して検証します。 実機にもブラウザにも一切触れません。

uv run pytest -q          # テストスイート
make check                # または: ruff(lint)+ mypy(strict 型)+ pytest をまとめて

green なら、このマシンでエンジンは動作しています。どちらのトラックに進んでも、この結果が土台になります。


ステップ 3:シナリオを読む

シナリオファイルはただの YAML です。名前付きシナリオのリスト({ description, scenarios } の マッピングで包んでもかまいません)で、各シナリオは任意の preconditions、steps のリスト、 そして 機械チェック可能なアサーション からなる expect ブロックを持ちます。showcase 一式の smoke テスト demos/showcase/scenarios/smoke.yaml は、 起動時に固定件数の行が表示されることを確かめます。

- name: stable catalog smoke
  preconditions:
    subject:
      launch:
        env: { SHOWCASE_UITEST: "1" }     # アニメ無効 -> 条件待ちをタイトに
  steps:
    - wait: { for: { id: [stable.row.1, stable_row_1] }, timeout: 10 }
  expect:
    - count: { sel: { idMatches: ["stable.row.*", "stable_row_*"] }, equals: 5 }
    - exists: { id: [stable.row.1, stable_row_1] }

要点は次のとおりです。

  • steps が操作し、expect が判定します。 run は steps を実行し、合否は expect の アサーションだけが決めます。AI も人の判断も介在しません。これが決定性の境界です (concepts)。
  • セレクタは id を優先します({ id: stable.row.1 })。安定していて、ローカライズにも 左右されません。曖昧なセレクタは最初に一致した要素をタップしたりせず、即座に失敗します (selectors)。このシナリオの id が 2 つの形(stable.row.1 と stable_row_1)を列挙しているのは、同じファイルを Android でも変更なく動かすためです。 Android の native な id 構文は . を保持できません (scenarios)。
  • 待機は sleep ではなく条件です(wait: { for: …, timeout: 10 })。Bajutsu は要素が現れるまで、 timeout に達するまでポーリングします。

文法の全体(すべてのステップ種別、待機、アサーション)は scenarios にまとまって います。各トラックの smoke テストは中身が少しずつ異なります(web トラックはログインとカウンターの 流れです)が、この step/expect の文法自体はどのトラックでも共通です。


ステップ 6:レポートを読む

実行ごとに runs/<runId>/(runId は YYYYMMDD-HHMMSS)というフォルダを書き出し、同じ結果を 4 つのビューで残します。

runs/20260610-120000/
├── manifest.json     # step -> 結果の対応(唯一の正)
├── junit.xml         # CI 連携(1 シナリオ = 1 testcase)
├── ctrf.json         # Common Test Report Format(PR コメントやダッシュボードなど、より高機能な CI 連携向け)
└── report.html       # 自己完結 HTML(ブラウザで開く)

HTML レポートを開くと、各ステップとその結果、取得した証跡(スクリーンショットや要素スナップ ショット)をインラインで確認できます。

open runs/<runId>/report.html      # macOS。Linux では xdg-open を使ってください

ターミナルを離れずに、完了した実行をテキストのタイムラインとして見ることもできます。

uv run bajutsu trace               # runs/ 下の最新実行

各フォーマットと runs/ のレイアウトの詳細は reporting を参照してください。


次に読むもの

これで、インストール → ユニットテスト → シナリオ → 実機実行 → レポートというループを一周できます。 同じシナリオ形式を使う入口があと 2 つあります。

  • AI でオーサリングする。 Claude にゴールへ向けて探索させ、シナリオを書かせます(Tier 1)。 .env ファイルに ANTHROPIC_API_KEY=sk-ant-… を置いてから、bajutsu record --target <name> --goal "…" を実行します。正確な呼び出し方は選んだトラックのページに載っています。Web UI (make serve)の API key ボタンからも、実行中のセッション用に同じキーを設定できます。 キーは write-once です。マスクしたプレビューだけを表示し、設定後に内容を再表示することはありません。 変更するには新しいキーを設定します(読み出す手段はありません)。キーはメモリ上に保持するだけで ディスクには書き込まないため、再起動をまたいで保持したい場合は、引き続き .env を使ってください。 オーサリングループとシステムアラートガードの仕組みは recording を参照してください。 Web UI の各タブの操作方法は web-ui を参照してください。
  • ネイティブテストを出力する。 シナリオを XCUITest、Playwright、または UI Automator のネイティブ テストへ変換します(テスト実行時に Bajutsu のランタイムや AI は不要です)。
    uv run bajutsu codegen demos/showcase/scenarios/smoke.yaml --target showcase-swiftui -o UITests/Smoke.swift
    
    構造のマッピングは codegen を参照してください。

ここからは、各リファレンスページがそれぞれの要素を詳しく説明します。まず設計の根拠を concepts で確認し、続けてドキュメント概要の推奨読書順に従って ください。showcase やデモ以外の自前のアプリをオンボーディングするには configuration を参照してください。