mabl CLIツールを使えば、ヘッドレスモードのmablランナーを使って、CI/CD環境内からmablテストを実行することができます。CI環境で実行するテストを編成する際には、mabl CLIコマンドを使って直接テストを実行することもできますし、mabl-cliノードパッケージをプロジェクトの依存関係として使用し、Jestなどのテストフレームワークを使ってmablテストを定義することもできます。

アーリーアクセスプログラム

mabl Runnerは現在、一部のお客様を対象にした「mabl Early Access Program」を実施しています。リクエストはこちらからどうぞ。

mabl CLIコマンドは、ローカルで使用するのと同様に、CI環境で直接使用することができます。

mabl CLIを初めてお使いになる場合は、CLI overview documentationで追加情報をご確認ください。

mabl CLIのインストール

以下のコマンドで、ビルドマシン/コンテナにmabl CLIをインストールします。

npm install @mablhq/mabl-cli

mabl CLIを認証する

CI環境でmabl CLIを実行する際には、"Command Line Interface "のmabl APIキーを使用する必要があります。このキーは、ここで取得するか、mablウェブアプリケーションのSettingsページに移動し、APIsタブを選択して、右上のCreate API keyボタンをクリックすることで取得できます。ここでは、Command Line Interfaceオプション（CI/CD Integrationオプションではない）を選択し、キーの名前を指定します。

CIにmabl CLIをインストールした後、次のコマンドを使用して、新しいAPIキーを使用してmablアカウントでCLIを認証します。

mabl auth activate-key KEY_VALUE

ウェブアプリケーションの起動

CI 環境内でテストを実行する前に、ウェブアプリケーションを起動して、mabl テストを実行する前にアプリにアクセスできるようにしておきましょう。すでに設定されているのであれば、このステップは省略できます。wait-onやwait-for-localhost-cliなどのツールを使って待機を行うことができます。たとえば、npm start を使ってアプリを起動した場合、次のようになります。

npm start & wait-on http://localhost:3000

mablテストの実行

オプション1：コマンドラインからテストを実行する

mabl-cliがインストールされ、ウェブアプリがCI環境内で動作している状態で、mablテストを実行することができます。mabl testsコマンドオプションを使用して、実行したいテストを指定することができます。

プランIDを使用してプランに所属するテストを実行する例は以下です。

mabl tests run --from-plan-id PLAN_ID --headless

このコマンドは、プラン情報をグループ化のためだけに使用します。プランを実行するわけではないので、高度なプラン設定（ステージや共有変数など）は適用されません。

テストラベルを使用して一連のテストを実行するには、次のようにします。

mabl tests run --labels LABEL_1 LABEL_2 --exclude-labels LABEL_3 --headless

特定のテストを実行するには以下のようなコマンドを実行します。

mabl tests run --id TEST_ID --headless

既存のクラウドテストと同じように構成されたテストを実行するには以下のように行います。

mabl tests run --run-id RUN_ID --headless

runコマンドの追加オプションには次のようなものがあります。

--environment-id flag to specify the mabl environment to run the test under. Specifying the environment allows mabl to use the appropriate environment variables and learned find information when running the test.
--url flag to specify a particular URL to run the test against.
--mabl-branch flag to specify a mabl branch to run the test under.
--creds flag to specify a testing credential set to use during the local run (`mabl credentials list` to see available ones).
--from-plan-id flag to get a list of tests from a plan.

オプション 2: コードからテストを実行する

CI環境でmablのテストを開始するためのもう一つのオプションは、ウェブアプリのnodeパッケージとしてmabl CLIを使用し、JavaScriptのテストライブラリを通してmablのテストをオーケストレーションすることです。

詳細については、JavaScriptテストフレームワークのページをご参照ください。

mablのテストをコードで定義することで、package.jsonファイルに必要なテストを実行するnpmコマンドを作成することができます。これには、オプション1と同様に、mablアプリのインストール、認証、起動に関する上記の手順が必要です。テストを実行するには、他のテストと一緒にバンドルするか、package.jsonファイルにテスト用の特定のスクリプトを作成することができます。

以下のコマンドで、mabl-cliをプロジェクトのdev依存関係にあるものとしてインストールしてください。

npm install --save-dev @mablhq/mabl-cli

例として、以下のスクリプトをpackage.jsonファイルに追加すると、Jestを使ってmablテストファイルを呼び出します。

“scripts”: {
    ...
    "mabl:test": "jest mablTests.test.ts",
    ….
}

import {createMablTestRunner, TestRunConfig} from '@mablhq/mabl-cli';

jest.setTimeout(180000);

const CICD_BRANCH_NAME = process.env.CI_BRANCH;

const runConfig: TestRunConfig = {
  credentialsId: 'CREDS_ID',
  environmentId: 'ENVIRONMENT_ID',
  workspaceId: 'WORKSPACE_ID',
  url: 'http://localhost:3000',
  branchName: CICD_BRANCH_NAME ?? 'master',
  headless: true, // toggle to watch tests locally
};

describe('Super important mabl tests', () => {
  it('This needs to always work', async () => {
    const mablTestRunner = await createMablTestRunner({
      testId: 'TEST_ID',
      ...runConfig,
    });
    const result = await mablTestRunner.run();
    expect(result.success).toEqual(true);
  });
});

これで、npm run mabl:test を CI 環境の中で実行して、mabl テストをキックオフすることができます。これは、開発者がmabl CLIを使ってローカルでmablテストを実行するための便利なコマンドでもあります。

まとめ

以下は、CLIを使ってmablテストを実行するためのCI構成の例です。

# install the CLI
npm install @mablhq/mabl-cli

# authenticate with API key
mabl auth activate-key KEY_VALUE

# install wait-on to wait for the app to start
npm install wait-on

# start the web app AND wait until it loads
npm start & wait-on http://localhost:3000

# run a single mabl test
mabl tests run --id TEST_ID --environment-id ENVIRONMENT_ID --creds CREDS_ID --headless

# run a set of tests by a label
mabl tests run --labels COOL_FEATURE_ONE --environment-id ENV_ID --headless

# run a test suite of mabl tests when using option 2
npm run mabl:test