English · 日本語
Bajutsu ドキュメント¶
自然言語駆動のエンドツーエンド(E2E)テストツールの、実装に基づいたリファレンスです。決定的コアは プラットフォームに依存しません。プラットフォーム固有の継ぎ目は、1 つの
Driverインターフェースの背後の backend だけです。つまり、新しいプラットフォームは新しい backend になります。iOS Simulator (XCUITest)backend、web(Playwright)backend、Android(adb)backend はいずれも実装済みです。Flutter アプリは同じ backend の上でそのまま動き、専用の backend を持ちません。
README.mdは紹介を、DESIGN.mdは設計の根拠を扱います。この ドキュメント群は、現状のコードが実際に何をするかを機能ごとに説明します。今後の計画は ロードマップにあります。
Bajutsu は、自然言語で書かれた(または記録された)テストシナリオを受け取り、アプリを操作(tap / type / swipe / wait)し、機械チェック可能なアサーションで結果を検証します。
プラットフォーム固有の継ぎ目は backend だけです。backend を差し替えれば、同じシナリオが iOS Simulator (XCUITest)でもブラウザ(Playwright)でも動きます。
中心となる考え方は、AI を継続的インテグレーション(CI)のゲートに持ち込まないことです。AI はシナリオの 著者であり失敗時の調査役であって、合否は判定しません(concepts 参照)。
データフローの全体像¶
architecture では、各ボックスをどのモジュールが担当し、モジュール同士がどう依存して いるかを説明します。同じシステムを依存レイヤとして見た図も含みます。
トピック一覧(推奨の読む順)¶
はじめての方は Getting started チュートリアル から始めてください。 手を 動かして辿るチュートリアルです(インストール → ユニットテスト → シナリオ → 実機実行 → レポート)。 終えたら、下のリファレンス各ページに戻ってください。Mac のないマシン(Linux、Windows、コンテナ) では、代わりに web トラックを辿ってください。Playwright backend を使い、 ブラウザに対して同じループを回します。Xcode も Simulator も要りません。
| # | ページ | 何を説明するか |
|---|---|---|
| 1 | concepts | 設計思想と中核原則(決定性、2 層、安定度順ラダー、AI の関与境界) |
| 2 | glossary | ドメイン用語の一語ずつのリファレンス。混同しやすい語のかたまり(driver / backend / actuator / platform、target / app / device、scenario と test、trace と triage)を切り分けます |
| 3 | architecture | モジュール構成、依存関係、実装状況(実装済み / 未配線) |
| 4 | developer-guide | ソースツリーを読み、そこで手を動かすための案内。ファイル配置、4 つの契約、シナリオ DSL とセレクタ、レイヤごとのクラス、そして開発・動作確認のルーチンを扱います |
| 5 | scenarios | シナリオ YAML の文法(ステップ / 待機 / アサーション / 証跡トークン)= オーサリングリファレンス |
| 6 | dsl-grammar | シナリオ DSL(ドメイン固有言語)の 形式文法(EBNF と全検証制約)。scenarios の背後にある規範仕様です |
| 7 | selectors | セレクタモデルと決定的解決(0/1/2+ 件)、アサーション評価の仕組み = 決定性の核 |
| 8 | drivers | Driver 抽象、XCUITest (iOS) / playwright (web) / adb (Android) / fake、能力差の吸収、simctl 環境 |
| 9 | run-loop | Orchestrator(observe → act → verify)、待機、リトライ、実行結果 |
| 10 | evidence | 証跡サブシステム(瞬時 / 区間、capturePolicy、provider、redact) |
| 11 | reporting | レポート(manifest.json / JUnit / HTML)と runs/ レイアウト |
| 12 | configuration | 設定の階層(defaults × targets)、ターゲットのオンボーディング、doctor 充足度スコア |
| 13 | recording | AI オーサリング(Tier 1 record)、Agent 抽象、システムアラート対処 |
| 14 | codegen | シナリオ → ネイティブ XCUITest / Playwright / UI Automator 生成 |
| 15 | cli | CLI のコマンドとオプションの完全リファレンス |
| 16 | showcase | showcase 群(唯一の iOS フィクスチャ、全プリミティブを網羅) |
| 17 | ci | CI で動かす。リポ自身の workflow と再利用可能な bajutsu-e2e アクション |
| 18 | self-hosting | serve を単一 Mac 上でトークン認証付き LaunchAgent として常駐させ、Tailscale 越しに公開します(BE-0016 段階 A) |
| 19 | vision | 成長の 3 軸(reach / scale / authoring)。各軸がすでにどこまで進んでいるかと、そのすべてが守る制約を扱います。reach のプラットフォーム可搬性設計(セレクタ、id 規約、段階分け)も自身の節にあります |
| 20 | ai-development | AI エージェントと人間が並行して開発するための運用規約(ゲート、ブランチ、pre-push フック、worktree)。CLAUDE.md の詳細版です |
| 21 | roadmap-workflow | 着想から実装までの循環:ideation スキルが BE 提案を起草し、implement-be スキルがそれを出荷します(プレースホルダー ID、Approved → Implemented のライフサイクル) |
| 22 | contributor-workflow-tutorial | その循環を 手を動かしながら 辿る walkthrough:一つのアイデアを /ideation からマージ済みの提案へ、続いて /implement-be からマージ済みの PR へ。良い提案と悪い提案の実例、propose-and-build を使うときも扱います |
クイックスタート¶
uv sync --group dev # .venv 作成 + 依存 + 開発ツール
uv run pytest -q # ユニットテスト(実機不要)
# showcase フィクスチャに対して(実機 Simulator が必要)
make -C demos/showcase swiftui-build # フィクスチャアプリをビルド
make -C demos/showcase run-swiftui # iOS(XCUITest)バックエンドでシナリオを実行
CLI の最小形は次のとおりです。
bajutsu run --target <name> [--scenario file.yaml] # 既定: アプリのシナリオディレクトリ全体
bajutsu doctor --target <name> # 規約充足度スコア
bajutsu record --target <name> --goal "..." [--out file] # AI で探索・記録(要 API キー)
bajutsu codegen <scenario.yaml> --target <name> -o UITests/Foo.swift
bajutsu serve # ローカル Web UI(Tier 1・CI 用ではない)
コマンドとオプションの全体は cli にあります。
このドキュメントの方針¶
- コードが正:記述の 1 つ 1 つを現在の実装(
bajutsu/)に対応づけ、要所でfile.py:lineを示します。 - 設計と実装の差を明示:
DESIGN.mdに書かれていても、まだコードに配線されていない 機能(外部mockServerコマンド。シナリオのmocksで代替済み)は、各ページと architecture の実装状況で「未実装」と明記します。 - 言語:散文は日本語で書き(
DESIGN.mdに合わせます)、コード内のコメントと docstring は英語です。