docurun

ドキュラン

DocuRun は、ドキュメントを統合テストとして実行するツールです。

なぜ ？

統合テストとドキュメントの両方が期待外れだったと思います。

• 統合テストはおそらく、書くのも読むのもデバッグするのも難しいものです。何か問題が発生した場合は、コードを調べて、ブラウザで手動で実行していることとどの部分が異なるかを推測する必要があります。
• 開発者はコードを変更するたびにドキュメントを更新したくないため、エンド ユーザー ドキュメントはおそらく最新ではありません。ボタンの文言を変更するときは、ドキュメント内のスクリーンショットを忘れずに更新する必要がありますが、おそらく更新しないでしょう。

文書化されたユーザー インターフェイスの動作を壊すような変更を行った場合、おそらくユーザーから苦情が出たときに初めて気づくことになります。

ドキュランとは何ですか？

DocuRun は、Playwright コード ブロックを含むマークダウン ファイルを取得し、それらを統合テストとして実行するツールです。テスト中に撮影されたスクリーンショットを含む美しいドキュメント Web サイトが作成されます。

DocuRunの使い方

1. アプリケーションの使用方法を説明するコード ブロックを含むドキュメントをマークダウン ファイルに記述します。次のようなdocurun/index.mdファイルを作成します。
2. マークダウン ファイルに対して DocuRun を実行する

   npx docurun

3. Docurun は、どのマークダウン ファイルが正常に実行され、どのマークダウン ファイルが失敗したかを示す優れたレポートを標準出力に表示します。すべてのテストが合格した場合は終了コードが 0 になり、一部のテストが失敗した場合は終了コードが 1 になるため、CI/CD パイプラインに簡単に統合できます。また、ドキュメントとスクリーンショットを含む静的 Web サイトを含むdocurun/website/ディレクトリも作成されます。一部のテストが失敗した場合、ドキュメントには失敗時のページのスクリーンショットとエラー メッセージが含まれます。

ドッカー

マシンに Node.js をインストールせずに、Docker コンテナーで DocuRun を実行することもできます。

docker run -v $( pwd ) /docurun:/docurun -it lovasoa/docurun

Docker Hub の lovaoa/docurun を参照してください。

スクリーンショット

SQLページ

これは、SQLPage Web サイト構築ツールの実行可能ドキュメントを示しています。

Github のスター

エラー

エラー実行はターミナルで次のように表示されます

 $ npx docurun

> [email protected] start
> node cli.js

Processing all files in ./docurun/:
 - download_sqlpage.md
 - star_a_repository.md.
Saving results to ./docurun/website/.

✅ download_sqlpage
Error while executing code:
await page.getByText('inexistent element').click()

locator.click: Timeout 30000ms exceeded.
Call log:
  - waiting for getByText('inexistent element')

 star_a_repository

そしてレンダリングされました: