Autify Connect 連携

Autify Connectの概要 を最初に読むと、Autify Connect とは何なのかを理解することができます。

Autify Connect のユースケース

詳細に入る前に、Autify Connect のユースケースに関する意識をすり合わせておきましょう。Autify Connect は1つの重要な機能を提供しています、それはインターネット経由でアクセス不可能なエンドポイントであってもAutify のテストを実行できるということです。これによって、3つの異なるユースケースが可能となります:

1. プライベートネットワーク内のエンドポイントに対して、常時稼働している固定のアクセスポイントを利用してテストする
2. プライベートネットワーク内のエンドポイントに対して、ローカルマシン上の一時的なアクセスポイントを利用してテストする
3. localhost のエンドポイントに対して、ローカルマシン上の一時的なアクセスポイントを利用してテストする

ユースケース1

ユースケース1 はAutify のテストをプライベートなウェブサイト、例えばファイアウォールの後ろにあるステージング環境や内部向けの社内ウェブサイトに対して実行したい場合になります。この場合、"corp network" といった様な恒常的なアクセスポイントを使って、プライベートネットワーク内に少なくとも1つのAutify Connect Client を動かしておく必要があります。そうすることで、誰かがそのアクセスポイントの可用性を担保してくれる、つまりそのAutify Connect Client をデーモン化して監視することで、ずっと動き続けている状態を保ってくれる限り、そのアクセスポイントをプライベートネットワーク内で実行したいテストにいつでも利用することができます。

ユースケース2

ユースケース2 はターゲットのエンドポイントはユースケース1 と同じですが、アクセスポイントは一時的なものでローカルマシン上で実行します。この場合、常時稼働のプロセスを管理する必要はありません。代わりに、必要に応じて一時的なアクセスポイントを作成し、それを使ってAutify Connect Client を動かすことができます。すると、Autify Connect Client をターゲットのエンドポイントにアクセス可能なローカルマシン上で走らせ続けている限り、それを経由してプライベートネットワークに対してAutify のテストを実行できます。

ユースケース3

ユースケース3 は1 や2 とは全く異なる目的を持ちます。ターゲットエンドポイントはlocalhost/127.0.0.1 で例えば開発用のローカルサーバになりますが、それらに対してAutify のテストを実行したいという目的になります。ユースケース2 で説明した一時的なアクセスポイントはこの場合でも有効です、なぜならローカルマシンはlocalhost にももちろんアクセス可能だからです。そのため、ターゲットエンドポイントは全く異なりますが、ソリューションはユースケース2 と3 で同一のものになります。

Autify CLI は上記の全てのユースケースをサポートする最も簡単な方法を提供します。これから1つ1つ見ていきますが、特定のユースケースについて知りたければその章にジャンプして読むこともできます。

はじめてみよう

Autify CLI はAutify Connect をローカルマシンから簡単に操作するいくつかのコマンド群を提供しています。これからそれらを見ていくことで、つまづくことなくAutify Connect をはじめることができると理解して頂けると思います。

前提条件

テストシナリオをレコードする

Autify for Web でテストシナリオを作成する必要があります。プライベートなエンドポイントか開発サーバの様なlocalhost エンドポイントに対してレコーディングして下さい。そのレコードしたテストシナリオのAutify のURL、例えばhttps://app.autify.com/projects/0000/scenarios/0000 をメモしておきます。

Autify CLI をインストール

Autify CLI をインストールしてAutify for Web のパーソナルアクセストークンを設定する必要があります。詳しくはAutify CLI のドキュメントをご覧下さい。

Autify Connect Client をインストール

以下のコマンドを実行するだけです。これは適切なautifyconnect のバイナリをAutify CLI のキャッシュディレクトリにダウンロードしてくれます:

autify connect client install

アウトプット例:

$ autify connect client install
Installing Autify Connect Client (version: v0.6.1)... done
Successfully installed Autify Connect Client (path: /home/node/.cache/autify/autifyconnect, version: Autify Connect version v0.6.1, build ca0972e)

1. プライベートネットワーク内のエンドポイントに対して、常時稼働している固定のアクセスポイントを利用してテストする

このケースでは、固定のアクセスポイントを一度作成し、それを再利用します。まず、アクセスポイントをAutiyf CLI で作成します:

autify connect access-point create --name ACCESS_POINT_NAME --web-workspace-id WORKSPACE_ID

このコマンドは生成されたキーを自動でAutify CLI のコンフィグディレクトリ内に保存してくれます。

もしUI からアクセスポイントを作成したければ、それも可能です。作成したら、アクセスポイントの名前とキーを以下のコマンドを使って保存します。生成されたキーをSTDIN 経由で入力するように聞かれます:

autify connect access-point set --name ACCESS_POINT_NAME

それでは、作成したアクセスポイントを使ってAutify Connect Client を動かしてみましょう。このターミナルはどこかで動かし続けておいて下さい:

autify connect client start

これで、固定のアクセスポイントが利用可能になりました。レコードしたAutify のテストシナリオをこのアクセスポイントに実行してみます:

autify web test run TEST_SCENARIO_URL --autify-connect ACCESS_POINT_NAME --wait

このコマンドは、指定したアクセスポイントに繋ぎながらテストシナリオを実行し、テストが終了するまで待ちます。

2. プライベートネットワーク内のエンドポイントに対して、ローカルマシン上の一時的なアクセスポイントを利用してテストする

このケースでは、固定のアクセスポイントは不要で代わりに一時的なものが必要になります。Autify CLI では、Autify Connect Client を実行する時に、一時的なアクセスポイントの自動的な作成/削除をサポートしています。

以下のコマンドを実行します。これは一時的なアクセスポイントを作成し、Autify Connect Client を生成されたキーで動かし、テストシナリオを実行してくれます。テストシナリオの実行が終わると、Autify Connect Client を停止し一時的なアクセスポイントを自動的に削除もしてくれます:

autify web test run TEST_SCENARIO_URL --autify-connect-client --wait

アウトプット例:

$ autify web test run https://app.autify.com/projects/000/scenarios/0000 --autify-connect-client --wait
[Autify Connect Manager]  2022-09-15T19:54:39.213Z	info	Ephemeral Access Point was created: autify-cli-UUID
Starting Autify Connect Client...
[Autify Connect Manager]  2022-09-15T19:54:39.253Z	info	Starting Autify Connect Client (accessPoint: autify-cli-UUID, debugServerPort: 51035, path: /Users/runner/Library/Caches/autify/autifyconnect, version: Autify Connect version v0.6.2, build 0913a76)
Waiting until Autify Connect Client is ready...
[Autify Connect Client]   2022-09-15T19:54:39.262Z	info	start serving a debug server on http://localhost:51035
[Autify Connect Client]   2022-09-15T19:54:39.262Z	info	Starting to establish a secure connection with the Autify connect server. Your session ID is "...".
[Autify Connect Client]   2022-09-15T19:54:40.509Z	info	Successfully connected!
Autify Connect Client is ready!
✅ Successfully started: https://app.autify.com/projects/000/results/1111 (Capability is Linux Chrome 104.0)
🕐 Waiting for the test result: https://app.autify.com/projects/000/results/1111
  ✔ Waiting... (timeout: 300 s)
✅ Test passed!: https://app.autify.com/projects/000/results/1111
Waiting until Autify Connect Client exits...
[Autify Connect Client]   2022-09-15T19:54:51.932Z	info	Interrupt received.
[Autify Connect Client]   2022-09-15T19:54:51.932Z	info	Shutdown completed.
[Autify Connect Manager]  2022-09-15T19:54:52.358Z	info	Ephemeral Access Point was deleted: autify-cli-UUID
[Autify Connect Manager]  2022-09-15T19:54:52.362Z	info	Autify Connect Client exited (code: 0, signal: null)
Autify Connect Client exited.

このコマンドでほとんどのユースケースをカバーしていますが、もしAutify Connect Client を別で動かしたい場合は、レコードしたテストシナリオが属しているワークスペースID (URL の/projects/ の後がワークスペースID) を使って以下を実行します:

autify connect client start --web-workspace-id 000

そうしたら作成された一時的なアクセスポイント(その名前は前のコマンドの出力に Starting Autify Connect Client (accessPoint: autify-cli-UUID,... の様に出ます) に対してテストシナリオを実行します:

autify web test run TEST_SCENARIO_URL --autify-connect "autify-cli-UUID" --wait

3. localhost のエンドポイントに対して、ローカルマシン上の一時的なアクセスポイントを利用してテストする

このケースでは、単にローカルマシン上に一時的なアクセスポイントが必要なだけです。Autify CLI では、Autify Connect Client を実行する時に、一時的なアクセスポイントの自動的な作成/削除をサポートしています。

まず初めに、localhost サーバーを別のターミナルで立ち上げます。これはお使いのタスクランナーによりますが、rails server やnpm run start といったコマンドになります。また、テストシナリオはローカルのエンドポイント、例えばhttp://localhost.autify.com:3000 の様なものに対してレコードしておくようにします。(備忘: Autify ではlocalhost を何もせずに使えるようにしたいと思っていますが、現時点ではlocalhost.autify.com をレコーディング時かURL 置換で使う必要があります。)

そうしたら、ユースケース2 と同じコマンドを実行します:

autify web test run TEST_SCENARIO_URL --autify-connect-client --wait

autify web test run TEST_SCENARIO_URL --autify-connect-client --wait --url-replacements http://localhost=http://localhost.autify.com

localhost 開発するユースケースのデモ

こちらが、ユースケース3 における典型的な開発サイクルでのステップバイステップの例になります:

1. 簡単なlocalhost アプリケーションを立ち上げる
   • 以下のコマンドは、macOS で静的なHTTP サーバをhttp://localhost:8000 で立ち上げます。残りのステップをしている間、これをフォアグラウンドで走らせ続けておきます。

echo Hello world! > index.html
python3 -mhttp.server

2. http://localhost.autify.com:8000 のサーバに対してテストシナリオをレコードする
   • テキスト要素に、テキストが"Hello world!" であるかのアサーションを追加します。
   • 本当のユースケースでは、このテストシナリオはチーム内で共有され、更にはステージング/本番のエンドポイントに対しても利用されているかもしれません。
3. そのテストシナリオをAutify Connect Client を使いながら実行する

autify web test run https://app.autify.com/projects/000/scenarios/000 --autify-connect-client --wait

4. テストがパスすることを確認する
5. アプリケーションを変更する

echo Hello Autify! > index.html

6. 同じシナリオを同じコマンドでAutify Connect Client を使いながら実行する

autify web test run https://app.autify.com/projects/000/scenarios/000 --autify-connect-client --wait

7. 今回はテストが失敗することを確認する
   • これはローカルでの変更がリグレッションの失敗を引き起こした場合を再現しています。

上で見てきた様に、たった1コマンドでAutify からlocalhost のアプリケーションを検証することができます。必要であればこのコマンドをRake/npm/等のお使いのタスクランナーに埋め込むことで、ネイティブに実行することもできます。

Autify Connect のためのCI/CD 連携

Autify が提供する全てのCI/CD 連携はAutify CLI をその中で利用しています。そのため、上でやったのと全く同じことがこれらのCI/CD 連携でも行うことができます。

コードレビュープロセスの中で、CI/CD ランナー内のlocalhost サーバに対してテストシナリオを実行する

ユースケース3 を拡張すると、同じことをCI/CD ランナー、例えばGitHub Actions hosted runner の中でも実行できます。これによって、追加のインフラ無しにコードレビュープロセスの中でAutify のテストを実行することが可能となります。これはコードレビュープロセスとAutify を連携する際の極めて重要なブロッカーを解消してくれます。コードレビュー連携について詳しくはこちらもご覧ください。

この連携を有効にするために、お手持ちのlocalhost サーバがCI/CD ランナー内でも起動して正しく動作できるようにする必要があります。その際の典型的な落とし穴が、データベース(シード)、他のマイクロサービス(モック、モノレポ、Docker)、認証情報(必ず何らかのシークレットストアに保存)、それからネットワーク(CI/CD ランナーはプライベートネットワーク内にいないことがあります)になります。

これがローカルマシンと同じ様に動く様になれば、localhost サーバに対するテストシナリオをCI/CD ランナー内でも実行できるようになります。

こちらはGitHub Actions とRails アプリケーションの例です。このワークフローをRails アプリケーションのGitHub レポジトリに追加できます。すると、pull request 毎にCI/CD ランナー内でrails server が立ち上がり、Autify Connect Client を介してAutify のテストを実行することができます:

on:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.0'
      # Rails サーバをバックグラウンドで実行します。データベースのセットアップや環境変数で認証情報を渡すなどの追加のステップが必要になるかもしれません。
      - run: bundle exec rails server --daemon
      - uses: autifyhq/actions-web-test-run@v2
        with:
          access-token: ${{ secrets.AUTIFY_WEB_ACCESS_TOKEN }}
          # http://localhost.autify.com に対してシナリオがレコーディングされたと仮定しています。
          autify-test-url: https://app.autify.com/projects/000/scenarios/000
          autify-connect-client: true
          wait: true
          timeout: 300

既にどこかで実行中のAutify Connect Client を使ってテストシナリオを実行する

これはユースケース1 に相当しますが、既にAutify Connect Client は実行中なのでとても簡単にできます。既にソフトウェアをプライベートネットワーク内のアプリケーションにデプロイしたと仮定します。そうしたら、パブリックネットワークのアプリケーションと同様にテストシナリオを実行してあげるだけです。

以下はGitHub Actions の例で、デプロイステップの後に入れます。このステップはYOUR_ACCESS_POINT_NAME という名前のAutify Connect Access Point を使ってAutify のテストを開始します。

- uses: autifyhq/actions-web-test-run@v2
  with:
    access-token: ${{ secrets.AUTIFY_WEB_ACCESS_TOKEN }}
    autify-test-url: https://app.autify.com/projects/000/scenarios/000
    autify-connect: YOUR_ACCESS_POINT_NAME

まとめ

このドキュメントでは、Autify Connect のユースケース、Autify CLI を使ってどの様にAutify Connect Client を使うか、そしていかに簡単にAutify Connect Client とAutify のテストを一緒に実行できるかを説明してきました。この連携によって、プライベートネットワークに対してテストしたり、localhost の開発サーバに対してCI/CD ランナー内からでさえも簡単にテストを実行したりといった、ユニークな方法で皆さんのウェブサイトをテストする可能性を広げることができるでしょう。