sync-test-cases-with-tms

TMS とテストケースを同期する

ローカルプロジェクトと Testomat.io の間で、Markdown テストケース（*.test.md）を同期します。

次のような場合に使用します。

• Testomat.io からテストをローカルの Markdown ファイルに取得／エクスポート／ダウンロードする。
• ローカルの Markdown テストを Testomat.io にプッシュ／アップロード／インポートする。
• 一括編集する：ケースを取得 -> ローカルで編集 -> TMS に戻す。

セットアップ

• TESTOMATIO トークンを確認します：スキル入力 -> プロジェクトルートの .env -> ユーザーに尋ねる。
• トークンを .env に保存します：TESTOMATIO=tstmt_xxxxx。
• キーを持っていない場合は、Testomat.io の Settings → Project → Project Reporting API key（https://app.testomat.io/projects/<project-id>/settings/project）から取得します。

CLI の実行

• npx 経由で check-tests を実行します。プロジェクト依存関係としてインストールしないでください。
• セッション内で最初に実行する check-tests の呼び出しは、最新バージョンを解決するために npx check-tests@latest … にしてください。 同じセッション内のそれ以降の呼び出しでは、通常の npx check-tests … を使用します。
• ここ、TESTOMATIO_CLI.md、または npx check-tests --help に記載されたオプションのみ使用してください。オプションを独自に作らないでください（例：--pattern、--force）。

取得

Testomat.io からテストシナリオをダウンロードし、ローカルの Markdown ファイルとして保存します。

ディレクトリの選択 — testDir 入力が指定されている場合、またはユーザーが -d <path> を渡した場合は、そのパスを使用します。それ以外の場合：

• ワークスペースが空、または手動テスト専用の場合：ルートに取得します。
• エンドツーエンドテストのプロジェクトの場合：test-cases ディレクトリに取得します。
• その他の場合：.testeiya/test-cases に取得します（.testeiya/ が存在することを確認し、Git の追跡対象から除外します）。

キャッシュフォルダーのルール：

• 取得先のデフォルトは、Git の追跡対象から除外されるキャッシュ .testeiya/test-cases/ です。プロジェクトの .gitignore に .testeiya/ がまだなければ追加します。
• 取得したケースを追跡対象のフォルダー（test-cases/ など）に保存してはいけません。リポジトリに不要なファイルが増えてしまいます。
• Git の追跡対象から除外されていても、ファイルの編集や再プッシュは可能です。
• リポジトリで *.test.md ファイルをすでに追跡対象のフォルダーに保存している場合は、取得せず、その場で作業するか、-d <that folder> を渡して同じ場所に更新します。
• これは、手動テストのリポジトリ内で実行した場合に scan-automation-project が コード を .testeiya/code/ に取得する動作と一致しています。

npx check-tests pull -d .testeiya/test-cases

• 特定のスイートのみを取得する場合（ユーザーがスイート名を指定するか、スイート ID を渡した場合）：npx check-tests pull --suite-ids "@S12345678,@S87654321"。
• その他の取得オプション：TESTOMATIO_CLI.md。

プッシュ

ローカルの Markdown テストを Testomat.io にアップロードします。

プッシュ前のファイルフィルタリング — テストケースファイルのみをプッシュし、プロジェクトのドキュメントや要件はプッシュしないでください。

• *.test.md に一致するファイル、または有効な `` ブロックを含む Markdown ファイルを含めます。
• その他の Markdown（README.md、CHANGELOG.md、ドキュメント）はすべて無視します。
• テストケースがほかのファイルと同じ場所にある場合は、まずテストファイルを .testeiya/test-cases/ にコピーまたは移動します。

プッシュ前の検証：

1. *.test.md ファイルが少なくとも 1 つ存在すること。
2. 各ファイルに有効なテストブロックが含まれていること：

# ... (test case title)

... (test case description)

# Specific files (preferred when known)
npx check-tests push --files login.test.md checkout.test.md

# Testeiya cache folder
npx check-tests push -d .testeiya/test-cases

• プッシュするファイルが決まっている場合（例：qa-write-test-cases／improve-test-cases で生成したばかりの場合）は、--files（エイリアス -f）を使ってファイルを明示的に渡してください。--files を指定しない場合、CLI はデフォルトの glob **/*.test.md にフォールバックし、無関係なファイルを選択する可能性があります。
• glob パターンは引用符で囲みます。パスは --dir を基準に解決されます。
• .testeiya または test-cases ディレクトリが存在する場合は -d を使用します。
• テストケースのディレクトリのみをプッシュしてください（例：.testeiya/ ではなく .testeiya/test-cases）。
• その他のプッシュオプションと使用例：TESTOMATIO_CLI.md。

サマリー出力

同期後、短いログ形式のサマリーを出力します。

Sync Complete:
- Action: pull/push
- Directory: <path>
- Tests synced: 15
- Status: Success