nukadoko

nukadokov0.18.0MIT

Typed step contracts for Gherkin, so a scenario can be told wrong before it runs. Every execution leaves a step record the tool measured rather than the agent reported, and every run a Markdown summary that is the run's evidence.

インストール

npm install nukadoko

• GitHub のソースコード
• 使っているツール: archstrict, depug
• このツールを使っているツール: archstrict, depug, finderscope, firstlight, solarsql, spacequery, stryker-agent-reporter

nukadoko は、型付きのステップ契約のもとで Gherkin のシナリオを実行し、実行のたびにステップ記録を書き出します。 実装は今や生成されるものになり、それを検査する基準は固定されていなければなりません。 受け入れ基準は、それを決めた人たちの言葉で書かれたままにします。 その文とテスト対象のシステムの間にあるものは、すべて型付きで、実行前に検査され、差分でレビューできます。 ステップ記録はツール自身が測定するので、実行についてのエージェントの説明を信じる必要はありません。 どの実行も、CI がプルリクエストに投稿する Markdown の実行サマリーで終わり、人は差分の中の .feature とそのサマリーを並べてレビューします。

特徴

• 実行前にわかる誤り。 nuka check は、すべてのフィーチャーファイルとステップファイルを読み、未定義のステップ、重複したパターン、あいまいなステップ、順序が誤っている from のバインディング、プロジェクトにインストールされていない Playwright を必要とするステップなどを報告します。 nuka check --codes は、すべての指摘コードを一覧表示します。 nuka run も実行の前に同じ検査を行い、エラーがあれば止まります。 --no-check を付けると、この検査を省きます。
• エージェントが読める語彙。 nuka steps --json は、各ステップのパターン、説明、mutates、needs を一覧表示します。 nuka describe は、ステップの契約を、スキーマを JSON Schema の形にして表示します。
• ステップ記録。 nuka do は 1 つのステップを単独で実行し、検証済みの結果と、ツールが観測したネットワークの読み書きを含むステップ記録を出力します。 nuka run はシナリオを実行し、同じ記録を残します。 エクスポートされた runCommand を呼ぶステップは、起動した各プロセスのコマンド、作業ディレクトリ、終了コードを observed.processes に残します。
• レビューする人のための実行サマリー。 どの nuka run も .nukadoko/runs/<run_id>/summary.md を書き出します。 そこには、コミット、各環境、フィーチャーごとの表、mutates: false と宣言したのに書き込みが測定されたステップ、失敗した各シナリオを再実行するコマンドが並びます。 $GITHUB_STEP_SUMMARY が設定されていれば、そこに追記します。 nuka run --since <git ref> を付けると、人が承認した基点から変わった基準とステップファイルが加わります。 nuka report --format markdown|allure|messages は、終わった実行を、その実行ディレクトリだけから、実行サマリー、Allure の結果、cucumber-messages のストリームとして描画します。 --out <path> を渡すと、CI のステップがプルリクエストのコメントとして投稿するサマリーを書き出します。
• 理由がわかる失敗。 ステップが失敗すると、nuka run はそのエラーの 1 行目とステップ記録のパスを stderr に出力します。 サマリーの後には、失敗した各シナリオについて scenario-failed の指摘を出力し、その do: の行がシナリオを再実行する nuka run <feature>:<line> を示します。 失敗したステップが値を読んだ先のステップで、プログラムが 0 以外のコードで終了していた場合は、used の行がそのステップ、終了コード、stderr の 1 行目を示します。
• 既存のスイートの入口。 import を 1 つ @cucumber/cucumber から nukadoko/compat に替えると、cucumber-js のスイートは動き続け、nukadoko がそのステップを記録し始めます。 その後、各ステップを個別に defineStep へ移せます。

エージェントでの使い方

エージェントは、人の手を借りずにループ全体を回せます。

1. nuka steps --json で語彙を調べます。
2. nuka describe で契約を読みます。
3. nuka do で 1 つのステップを実行し、ステップ記録を読んで、次の呼び出しを選びます。
4. 語彙に操作が足りなければ、nuka scaffold <name> --pattern "<line>" でステップを追加して実装し、nuka do で単独で動かします。 フィーチャーを先に書いた場合は、nuka scaffold --feature <file> が未定義の行ごとにスタブを 1 つ書き出します。 --then は Then のステップを書き出します。 --command <entry point> は、組み込みの scratch のディレクトリでプログラムを実行する When のステップを書き出します。 --from <step>.<key> は、前のステップの値を受け取るつながりを書き出し、--description はステップの説明を書き出します。 検証するだけのステップは returns を省けます。
5. フィーチャーを書き、そのフィーチャー、複数のファイル、またはディレクトリを対象に nuka check を通し、green になるまで nuka run <feature> を実行します。 失敗したときは、失敗したステップの記録を読みます。
6. フィーチャーとその実行サマリーを渡します。 人はプルリクエストで両方を読み、それを承認します。

nuka check は、毎回の実行の前に通す静的なゲートです。 nuka tend は、定期的な CI のジョブなどでときどき実行するもので、使われていない宣言や、どのフィーチャーの行にも結び付かないステップのように、壊れてはいないが傷みつつあるものを報告します。 説明のないスキーマのフィールドのような宣言についての指摘も、ここに含まれます。 その指摘はどれも注記で、--fail-on <code> を付けると、指定したコードで終了コードを失敗にできます。 パッケージには 2 つのスキルが含まれています。 acceptance は要求から、シナリオと、その証拠になる実行までを進めて人のレビューに渡し、migration は cucumber-js や Playwright Test のスイートを nukadoko に移行します。

はじめかた

nukadoko には、22 系の Node 22.18 以降か、Node 23.6 以降が必要です。 これらは、フラグなしで .ts のファイルを実行できるリリースです。 nukadoko は設定とステップファイルを Node 自身の型の除去で読み込むので、独自の TypeScript ローダーをインストールしません。

npm install -D nukadoko
npx nuka init
npx nuka scaffold run-greet --pattern "I run greet with {name:string}" --command src/cli.ts

nuka init は、CLI や API のプロジェクトを前提に準備をします。 nukadoko.config.ts と features/steps/ を書き出し、.gitignore に .nukadoko/ を追加し、tsconfig.json の include にステップと設定を加え、nuka run を実行する test:scenarios スクリプトを追加します。 以後、人も CI も npm run test:scenarios の 1 つだけを実行すれば済みます。 対象を指定しない nuka run は、featuresDir を検査してから実行します。 scaffold の行は、プログラム src/cli.ts を実行してその exitCode、stdout、stderr を返す When のステップを書き出します。 nukadoko はブラウザーをインストールしません。 Playwright は省略可能な peer dependency で、page や request を使うステップだけが必要とします。 nuka run は Allure の結果も cucumber-messages のストリームも書き出しません。 それらは nuka report が終わった実行から描画し、nuka init --allure は Allure のための allurerc.mjs を書き出します。 gh skill install meganemura/nukadoko --all で、2 つのスキルをインストールします。