mabl CLIのインストールと設定

mabl CLIは、mablにCI/CDパイプラインと開発者ワークフローを統合できるコマンドラインツールです。Node.jsパッケージとして配布されており、npmjs.comで入手できます。

mabl CLIは、mablにCI/CDパイプラインと開発者ワークフローを統合できるコマンドラインツールです。Node.jsパッケージとして配布されており、npmjs.comで入手できます。

Proxy環境の設定

Proxyを経由してインターネット接続する場合は、以下のコマンドで設定してください。

npm config set http-proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

CLIのインストール

最初に、Node.jsバージョン10.0.0以降をインストールする必要があります。Macを使用する場合は、Homebrewパッケージマネージャー経由でノードをインストールすることをお勧めします。ノードをインストールした後で、ターミナルで次のコマンドを実行してmabl CLIをインストールします。

$ npm i -g @mablhq/mabl-cli

インストールされているCLIのバージョンを確認するには、次のコマンドを実行します。

$ mabl --version
> 0.6.28-beta

CLIをインストールした後で、mablのログインのための資格情報またはワークスペースのAPIキーを使用した認証が必要です。ローカルマシンでCLIを使用する場合は、mablの資格情報を使用してログインできます。

$ mabl auth login

一方、ビルドプロセスの一環としてmabl CLIを使用する場合は、認証にAPIキーを使用する必要があります。APIキーを取得するには、mablアプリケーション > [Settings] > [APIS] でキーをコピーし、次のコマンドで認証します。

mabl auth activate-key <YOUR-API-KEY>

📘

ローカルマシンでのテスト実行

API認証はCI/CDパイプラインの一部としてデプロイ時にテストを実行するためのものなので、ヘッドレスモードを含めてローカルでテストを実行するには、mablのログイン認証を行ってください。

認証が成功したかどうかを確認するには、次のコマンドを実行します。

$ mabl auth info
> Logged in as user [[email protected]]
> Login expires in [3 hours, 23 minutes]

サポートされているトップレベルのコマンドは次のとおりです。CLIを使用する作業の基本的なパターンがわかるはずです。

$ mabl <command>

Commands:
  mabl applications <command>  Manage your applications
  mabl auth <command>          Manage auth for the mabl CLI
  mabl branches <command>      Manage mabl branches
  mabl config <command>        Configure defaults for the mabl CLI
  mabl credentials <command>   Manage your testing credentials
  mabl deployments <command>   Manage mabl deployments
  mabl environments <command>  Manage your environments
  mabl tests <command>         Manage tests
  mabl test-runs <command>     Manage existing test runs
  mabl workspaces <command>    Manage your workspaces

Options:
  --version   Show version number  [boolean]
  -h, --help  Show help  [boolean]

Read full docs @ https://help.mabl.com/docs/mabl-cli

サポートされているすべてのコマンドのヘルプを表示したり、特定のコマンドのオプションのヘルプを利用できるようにするには、次の例に示すように--helpフラグを使用します。

$ mabl --help
$ mabl <コマンド> --help

ワークスペースへのクエリの実行

mabl CLIを使用して、ワークスペース、アプリケーション、環境、テストなどに関する情報を取得できます。各タイプのエンティティリストを取得するには、次のいずれかのコマンドを実行します。

$ mabl workspaces list 
$ mabl branches list 
$ mabl applications list
$ mabl environments list
$ mabl deployments list
$ mabl credentials list
$ mabl tests list

環境などの特定のエンティティに関してより詳細な情報を取得するには、次のいずれかのコマンドを実行します。

$ mabl workspaces describe <ワークスペースID>
$ mabl applications describe <アプリケーションID>
$ mabl environments describe <環境ID>

この情報を他のCLIコマンドで使用できます。たとえば、リグレッションテストプランの実行をトリガーするmablデプロイイベントを作成できます。

テストの作成

mabl CLIを使用すれば、ターミナルにコマンドラインを入力して新しいテストを直接作成できます。mabl Webアプリケーションを使用する必要はありません。たとえば、新しい機能に取り組んでいるソフトウェア開発者は、ローカル環境に対する新しいエンドツーエンドテストをVisual Studio Codeのターミナルから直接作成できます。

コマンドラインでテストを作成するには、次のコマンドでテストのURLと名前を指定します。なお、テスト名の中でスペースを使用するには、名前全体を引用符で囲む必要があります (例: "My new test")。

$ mabl tests create <URL> <テスト名>

>Creating test:  My new mabl test
>Url:  https://example.com
>Workspace:  1111aa_222bbb333ccc44-w

このコマンドを実行すると、ローカルのChromeブラウザーのインスタンスが開きます。ブラウザーには指定したURLの内容が表示されます。これで、Trainerを使用してテストステップを作成できます。テストの作成が完了したら、作業内容を保存します。Trainerを閉じると、コマンドラインに戻ってきます。

テスト作成の全オプションの詳細を確認するには、次のように、tests createコマンドに--helpオプションを追加します。

$mabl tests create --help

Create a test using the mabl Trainer

Positionals:
  url        The url to test  [string] [required]
  test-name  The name of the test  [string] [required]

Options:
  --version                   Show version number  [boolean]
  -h, --help                  Show help  [boolean]
  --desc, --test-description  Description for the test  [string] [default: ""]
  --width                     Set the browser width in pixels  [number] [default: 1366]
  --height                    Set the browser height in pixels  [number] [default: 768]
  --mabl-branch               Branch to run the mabl test against  [string]
  --auto-branch               Create a mabl branch when a mabl-branch target is specified that does not exist  [boolean] [default: false]
  -w, --workspace-id          Workspace to create test in  [string]
  --creds, --credentials      Credentials ID to run the test with  [string]

ワークスペース内の作成済みテストをすべて表示するには、mabl tests listコマンドを実行します。

テストの実行

mabl CLIを使用してテストを実行するには、以下の3つの方法があります。

  1. ローカルマシンで実行する方法。テストを素早く検証できますが、エラーのトラブルシューティングに必要な診断機能は限定されています。
  2. mablクラウドで実行する方法。診断機能と並列処理機能を完備しています。
  3. デプロイイベントのCI/CDパイプラインの一環として実行する方法。ビルドに関するフィードバックを得ることができます。

ローカルでのテストの実行

テストをローカルで実行するには、まず、実行するテストのIDを取得する必要があります。コマンドラインでmabl tests listを実行してワークスペース内のテストのリストを表示し、必要なテストのIDをコピーします。あるいは、mabl Webアプリケーションのテスト詳細ページに移動し、URL内のIDをコピーする方法もあります。

テストIDを入手したら、CLIで次のコマンドを実行してローカル実行をトリガーします。ローカルマシンでChromeがフルブラウザーモード (ヘッドレスモードではない) で起動し、テストが実行されます。

$ mabl tests run --id <id>

テストの進捗状況をターミナルで監視できます。同時に、テスト対象アプリケーションのテスト中の動作をブラウザーで確認することもできます。

クラウドでのテストの実行

CLIを使用してローカルでテストを実行した後、各ステップの詳細なデータ (例: スクリーンショット、DOMスナップショット、ネットワークアクティビティなど) を取得するためにクラウドでのテストの実行が必要になったと仮定します。mablクラウドでテストの実行をトリガーするには、次のコマンドを実行します。

mabl tests run-cloud --id <id> --url <url>

テストIDの取得方法は、ローカルでのテストの実行と同じです。URLは、テストを開始するURLです。 オプションの代わりにデプロイIDを指定することもできます。指定したデプロイのテスト実行と同じURLとブラウザーが使用されます。詳細については、後述の「デプロイでのテストの実行」を参照してください。

ラベルやブランチによるテストの選択

ラベルを使用して、対象とするテストと除外するテストを指定することができます。たとえば、テストラベルfeature-xまたはfeature-yを持つテストから、処理中ラベル (例: wip) を持つテストを除外して実行するには、次の式を指定します。

# Launch all tests labeled 'feature-x' OR 'feature-y'
mabl tests run-cloud --labels feature-x feature-y

# Launch all tests with labels, but exclude WIP labeled tests
mabl tests run-cloud --labels feature-x feature-y --exclude-labels wip

実行対象のテストバリアントをブランチで選択することもできます。そのためには、--mabl-branch <ブランチ名> を使用します。さらに、ブランチで変更されたテストのみを実行できます (ブランチの残りのテストは実行しない)。そのためには、次に示すように--branch-changes-onlyフラグを使用します。

# Constrain tests to a specific branch
mabl tests run-cloud --mabl-branch my-feature-branch

# Constrain tests to only a specific branch AND only tests edited on that branch
mabl tests run-cloud --mabl-branch my-feature-branch --branch-changes-only

run-cloudコマンドのすべてのオプションを表示するには、--helpオプションを使用します。

$ mabl tests run-cloud --help  

Run test(s) in the mabl cloud

Options:
  --version              Show version number  [boolean]
  -h, --help             Show help  [boolean]
  --id                   the id of the test to run  [string]
  --deployment-id, -d    Deployment to run the mabl tests against  [string]
  --url, -u              URL to run the mabl test against  [string]
  --browsers, -b         Space delimited browsers to test against (e.g. "chrome firefox")  [array] [required]
  --api-key, -k          API key (found in the mabl web app)  [string]
  --mabl-branch          Mabl branch to run test against  [string]
  --branch-changes-only  Only execute tests changed on specified branch  [boolean] [default: false]
  --revision, --rev      Code revision hash (application under test)  [string]
  --labels               Space delimited test labels. Run tests that match any label.  [array]
  --exclude-labels       Space delimited test labels. Exclude tests that match any label.  [array]
  --workspace-id, -w     Workspace to run against  [string]
  --prompt               Prompt to confirm execution selections  [boolean] [default: true]
  --no-prompt, --yes     Do not prompt to confirm execution selections  [boolean]

Examples:
  mabl-dev tests run-cloud --id <id>                   run test by id
  mabl-dev tests run-cloud --labels <label1> <label2>  run tests by test label

デプロイでのテストの実行

特定のアプリケーションと環境のテストを実行するデプロイイベントをトリガーするには、次のコマンドを実行します。

$ mabl deployments create --application-id <アプリケーションID> --environment-id <環境ID>

# Specify source control information to use with mabl GitHub App
$ mabl deployments create\
 --application-id <アプリケーションID>\
 --environment-id <環境ID>\
 --revision 41d502b463a37e87047148a6000411a1e1bf9a79\
 --repository-url [email protected]:foo-org/bar-repo.git

このコマンドは、すべてのmablプランのうち、デプロイイベントで実行が設定されていて無効化されていないアプリケーション環境のプランの実行をトリガーします。--labelsオプションを使用すると、デプロイで実行するプランを絞り込むことができます。

--revisionフラグと--repository-urlフラグの指定についても、注意してください。

mablでアプリケーションと環境のIDを取得するには、mablアプリケーションで [Settings] > [APIS] の順に移動して、[Deployment Events API]、[Application and Environment] の順に選択します。ページの下までスクロールすると、各IDを示す生成済みのcurlコマンドがあります。

mablアプリケーションで [Results] > [By Deployment] の順に選択すると、すべてのデプロイイベントを表示できます。

mablですべてのデプロイイベントを表示するには、次のコマンドを実行します。

$ mabl deployments list

特定のデプロイの詳細を取得するには、次のコマンドを実行します。

$ mabl deployments describe <デプロイID>

サポート対象のデプロイコマンドとオプションをすべて表示するには、次のコマンドを実行します。

$ mabl deployments --help

テストデータのエクスポート

mabl CLIを使用して、特定のテストのスクリーンショットをすべてエクスポートできます。一般に、スクリーンショットは、チームとの製品設計のディスカッションや、コンプライアンス上の理由で使用します。たとえば、アプリケーションのユーザーサインアップおよびオンボーディングのフローをテストする場合、ユーザーエクスペリエンスを最適化してサインアップを増やす方法をチームと話し合うために、スクリーンショットを取得することができます。

スクリーンショットをダウンロードするには、まず、mablアプリケーションで特定のテスト実行の結果に移動し、URLバーからテスト実行IDをコピーします (例: .../journey-runs/n3k23bavavba-jrのn3k23bavavba-jrの部分)。

次に、ターミナルに移動し、先ほどコピーしたテスト実行IDを使用して次のmabl CLIコマンドを実行します。

$ mabl test-runs export <テスト実行ID>

すべてのスクリーンショットが1つのZIPファイルに圧縮され、コンピューターの、CLIコマンドを実行した作業ディレクトリにダウンロードされます。なお、テストのステップ数が多い場合、スクリーンショットのダウンロードに数分かかり、ファイルサイズは100MiB以上になる可能性があります。

すべてのエクスポートオプションを表示するには、次のコマンドを実行します。

$ mabl test-runs export --help

CLIツールの更新

mabl CLIツールのバージョンを更新するには、次のコマンドを実行します。

npm install -g @mablhq/mabl-cli@latest

設定

listサブコマンドを使用して、利用可能な構成オプションを取得、設定、および一覧表示することができます。このコマンドは、他のオプションに加えて、mabl CLIで現在のワークスペースのデフォルトを設定するために使用できます。

# view current configuration values 
mabl config list

# set a configuration value
mabl config set workspace <WORKSPACE_ID>

# get a configuration value
mabl config get workspace

Proxy設定

mabl CLIはフォワードプロキシをサポートしています。プロキシを使用するには、http.proxy構成値にプロキシサーバーのURLを設定します。このURLには、基本的な認証クレデンシャルとポート情報を含めることができます。

指定したURLが無効であるというエラーが発生した場合は、Node.jsのバージョン12以上を使用していることを確認してください。

# add a proxy with no credentials on port 3128 
mabl config set http.proxy http://proxy.mycompany.com:3128
 
# add a proxy using credentials on port 3128 
mabl config set http.proxy http://"username:password"@proxy.mycompany.com:3128
 
# delete the current proxy setting 
mabl config delete http.proxy

If you receive a 407 error when logging in, this is a proxy authentication error. Ensure your password and username have been set correctly above.

📘

プロキシ設定はmablのトラフィックにのみ適用

なお、上記の設定オプションが設定されていると、mabl固有のリクエストのみが転送プロキシを経由することになります。ローカルテストの実行では、テスト対象のアプリケーションへのすべてのトラフィックは、ブラウザまたはオペレーティングシステムのプロキシ設定を使用します。

SSL Verification

デフォルトでは、CLIはサーバー証明書が既知の認証局によって発行されたものであるかどうかを検証します。プロキシがHTTPSトラフィックを傍受している場合、証明書の検証が失敗することがあります。プロキシを使用していてSSL検証が失敗する場合は、以下のように証明書検証を無効にすることができます。これは、必要な場合にのみ行うことをお勧めします。

# disable SSL verification 
mabl config set http.sslVerify false
 
# delete the current ssl verification setting to use the default 
mabl config delete http.sslVerify

📘

システム要件

お使いのマシンにChromeブラウザがインストールされていることを確認してください。
現在、Windows Subsystem for Linux(WSL)からのCLI実行はサポートしていません。

CLIのアンインストール

mabl CLIを削除するには、以下のコマンドを実行するだけです。

npm remove -g @mablhq/mabl-cli