インタラクティブでテスト済みのドキュメントへのアプローチ
WebdriverIOフレームワークは、多様な機能を提供する汎用性の高いツールです。私たちのプロジェクトドキュメントの目標は、これらの機能を効果的に伝え、プロジェクトへの適用方法を理解してもらうことです。これの中心的な要素はコード例です。多くの場合、コード例は、百聞は一見にしかずというように、機能の主要なアイデアを伝えることができます。
多くのプロジェクトで、プロジェクトドキュメントにコード例が埋め込まれていることは驚くべきことではありません。それらの多くはインタラクティブで、ユーザーがリアルタイムでコードを操作できるようにするものもあります（例：新しいReactドキュメント）、またはsvelte.devのようなライブ例を含む「プレイグラウンド」を提供するものもあります。
ドキュメントページにコード例を含める場合、よくある問題として、例が
- 作り上げられたもので、現実を反映していないことが多い
- 私たち全員が人間であるため、エラーが含まれている
- インターフェースの変更に伴い、時代遅れになっている
- 独自のプロジェクトに適用するのが難しい
このプロジェクトページのコード例を改善するために、これらの問題に対処することを目指して、ドキュメントにいくつかの変更を加え始めました。
loading...
ご覧のように、いくつかの例には、実行またはGitHubで表示するための2つのボタンがあります。しかし、それはどういう意味でしょうか？
ドキュメントからの例の出処
最初のステップとして、ドキュメントページからすべてのコード例を削除し、専用のレポジトリに移動しました。これにより、これらの例をコードとして扱い、品質と正確性を確保するためのCI/CDや自動化された依存関係の更新などの必要なインフラストラクチャをセットアップできます。
そのため、この組織の新しいレポジトリにようこそ👋。このウェブサイトで再利用している多くの例が含まれています。
すべての例が独自のディレクトリに自己完結型で含まれていることがわかります。膨大な数のNPMスクリプトを使用すると、単一のコマンドで特定の例を実行できます。
例をウェブサイトに埋め込むために、GitHubのシンプルな参照リンクに基づいてコードをダウンロードするDocusaurusのプラグインを使用しています。そのため、マークダウンファイル内にコードを含める代わりに、GitHub上の場所を参照するだけです（例：
loading...
次に、プラグインはそのコードをダウンロードし、そのファイルの指定されたコード行のみを表示します。これが最終的な結果です。
loading...
静的ドキュメントの構築に別のツールを使用している場合、同様のプラグインが利用できる可能性があります。
例のテスト
専用のリポジトリにすべてをうまくカプセル化したので、CI/CDを使用してすべての例を定期的にテストできます。シンプルなGitHubワークフローは、これらの例の実行をトリガーし、いずれかの例にエラーがある場合、パイプラインを失敗させることができます。
name: Test
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
exampleDir:
- click
# more example directories here
# ...
- api/webdriver
steps:
- name: Checkout
uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
- name: Install
run: npm install
- name: Test
run: npm run ${{ matrix.exampleDir }}
working-directory: ${{ matrix.exampleDir }}
ほとんどの例は通常のWebdriverIOテストファイルとして記述されており、他のテストと同様に通常のアサーションが含まれています。たとえば、コマンドチェーンを使用して要素を取得する方法を示す例は、次のように記述されます。
it('should get the text of a menu link', async () => {
const menu$ = await $('#menu') // or `browser.$('#menu')`
console.log(await menu$.$$('li')[2].$('a').getText()) // outputs: "API"
await expect(menu$.$$('li')[2].$('a')).toHaveText('API')
})
特定のコード行を参照できるため、例のテスト部分を切り捨て、重要な部分に焦点を当てることができます。
loading...
例を最新の状態に保つ
CI/CDインフラストラクチャを使用するもう1つの利点は、すべてを最新の状態に保つワークフローを使用できることです。WebdriverIOコードはGitHubでホストされているため、Dependabotを使用してすべての依存関係を毎週更新するように設定しました。追加のGitHubワークフローは、これらの依存関係の更新を自動的にマージするのに役立ちます。そのため、テストの失敗により問題が発生した場合にのみ対処する必要があります。
このプロセスは非常に重要であり、WebdriverIOの変更によってドキュメントで使用している例が壊れないようにするのに役立ちます。また、優れた追加のフィードバックループであり、新しいバージョンがリリースされても、例が壊れていないという信頼性を高めます。
例へのアクセスを容易にする
最後に、すべての例へのアクセスと実行を非常に簡単にするために、Runmeと呼ばれる非常に優れたVS Code拡張機能の機能を使用しています。ボタンをクリックするだけでコードをローカルでチェックアウトするのに役立ちます。まだRunmeをインストールしていない場合は、VS Code Marketplaceで確認するか、VS Codeで見つけてください。
多くの調査によると、VS Codeは世界中の多くの開発者にとって主要なIDEです。「例の実行」ボタンを使用すると、これらのユーザー全員がシングルクリックでリポジトリにアクセスできます。このボタンは、VS Codeで開くための許可を求めるカスタムvscode://プロトコルを使用するシンプルなリンクです。そこで、拡張機能は、チェックアウトする必要があるリポジトリと開く必要があるマークダウンファイルを含むリンク情報を取得します。拡張機能がインストールされていない場合は、同意すれば自動的にインストールされます。
リポジトリがチェックアウトされると、Runmeはインタラクティブなノートブックエクスペリエンスで例の専用のREADME.mdを開きます。例を説明し、手順を説明します。これにより、VS Codeターミナル内でコードセルを安全に実行できるため、例の設定と実行はシンプルなクリックで行われ、追加のアプリケーションを開く必要がありません。
VS Codeをインストールしていないユーザーは、引き続きリポジトリにアクセスし、手動でチェックアウトして例を実行することもできます。
参加する
WebdriverIOには多くの例と多くのコマンドとAPIがあり、ドキュメント化が必要です。これは、プロジェクトに参加して貢献する絶好の機会です。
webdriverio/example-recipesにさらに例を追加するか- ドキュメントで既存の例を参照する
ご質問やフィードバックがある場合は、お気軽に問題を提起してください。
これは、ブラウザではない特定の環境（例：Node.js）を必要とするフレームワークのコード例を提供するためのインタラクティブで簡単な方法であり、非常にクールな方法だと思います。フレームワークの作者であり、Docusaurusでドキュメントを実行している場合は、気に入ったらこのアプローチをコピーしてください。オープンソースで無料です。
お読みいただきありがとうございます！
