コンテンツにスキップ

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 参照)。

データフローの全体像

データフロー図。自然言語のゴールまたは人手編集がシナリオ YAML を生成し、Tier 2 の Orchestrator が backend 非依存の Driver API を通じて XCUITest・adb・Playwright のいずれかに対して決定的に実行します。合否は Reporter に渡り、失敗時は triage がシナリオへの修正案を提案します。

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 は英語です。