このページでは、コマンドラインからMagicPodでテストをローカル一括実行する方法を説明します。
ローカルPC環境の場合、MagicPodDesktopを使って行います。インストール手順についてはローカルPCでブラウザテストを行う前にを参照してください。
目次
- Macでのテスト一括実行
- Windowsでのテスト一括実行
- Linuxでのテスト一括実行
- Macでの並列実機テスト一括実行
- MagicPod一括実行設定を参照するmagic_pod_config.jsonを作成する
1. Macでのテスト一括実行
設定ファイルを記述
まずは、テストのコマンドライン実行に必要な設定ファイルの記述を行います。
簡単な方法として、MagicPod上のテスト一括実行設定画面より「テスト結果の表示言語」以外の項目を設定、残りの項目を設定ファイルにて記述するのがおすすめです。全ての項目を設定ファイルにて記述したい場合は、記述ファイルから"testSettingsNumber"項目を削除してください。
MagicPodDesktopを一度でも起動していれば、ディレクトリ「/Users/<ユーザー名>/Library/Application Support/magic_pod_desktop」に「magic_pod_config.json」というファイルがあるはずなので(これがMagicPodDesktopが利用している設定ファイルです)、これをデスクトップなど適当な場所にコピーします。
コピーしたら、以下の形式に従い設定ファイルをJSON形式で記述します。
{
"owner": <組織名。表示名でなくURL中のアルファベット表記のもの>,
"project": <プロジェクト名。表示名でなくURL中のアルファベット表記のもの>,
"capabilities": <ターゲットOSや対象アプリの設定。AppiumのCapabilitiesと同じ>,
"sendMail": <テスト結果通知メールを配信するか。省略するとfalse>,
"captureType": <テスト結果画面キャプチャの設定。on_error、on_ui_transit、on_each_stepのいずれか。省略するとon_each_step>,
"xmlTestOutput": <JUnit形式のテスト結果XMLを出力するか。主にJenkins連携用。省略するとfalse>,
"workDir": <作業ディレクトリのフルパス。省略するとデスクトップの「magicPod」>,
"authTokenFilePath": <認証トークンファイルのフルパス。省略すると~/.magic_pod_token>
"envVars": <KEY=VALUE形式の環境変数文字列のリスト。省略すると空リスト>,
"testNumber": <実行対象のテスト番号をカンマ区切りで記載。空または省略すると全テストを実行。特定のテストを複数回実行したい場合は「1*100」のように記載(この例ではテスト番号1を100回実行)>,
"includedTestCaseLabels": <テスト対象のラベルを文字列リスト形式で指定>,
"excludedTestCaseLabels": <テスト対象外のラベルを文字列リスト形式で指定>,
"logLevel": <ログを出す量の設定。beginner、expert、magic_pod_bug_investigationのいずれか。省略するとbeginner>,
"retryCount": <失敗したテストを最大何回リトライするか。省略すると0(つまりリトライはしない)>,
"externalAppium": <MagicPodDesktopの外部のAppiumサーバを使用するか。省略するとfalse>,
"externalAppiumUrl": <externalAppiumがtrueの場合、接続するAppiumサーバのURLを指定します。>,
"language": <テスト実行ログの表示言語。jaまたはen。省略するとen>,
"visualDiffPattern": <画像差分パターン名。skipを指定することも可能。省略すると未指定扱い>,
"testSettingsNumber": <MagicPod一括実行設定の番号>,
"testSettingsPatternName": <設定パターン名。対応する設定内に複数のパターンがある場合のみ必須>
}
共有変数を指定する場合はこちらを参考にしてください。
設定ファイル内の値に変数を用いる場合はこちらを参考にしてください。
以上を踏まえると、設定の記述は、以下のようになります。
{
"owner": "SampleCompany",
"project": "SampleApp",
"capabilities": {
"platformName": "iOS",
"platformVersion": "17.2",
"deviceName": "iPhone 15",
"app": "/Users/<yourUserName>/magicpod_demo_app.app",
"automationName": "XCUITest"
},
"sendMail": true,
"workDir": "/Users/<yourUserName>/magicpod-work"
}
テストを実行
設定ファイルを作成したら、以下の手順でテストを実行します。
- MagicPodDesktopが起動している場合は終了しておきます。
- Macのターミナル上でMagicPodDesktopのあるディレクトリに移動します。
- 次のコマンドを実行します。
# MagicPodDesktopの最新版があれば更新
"MagicPodDesktop.app/Contents/MacOS/MagicPodDesktop" update --magic_pod_config="<magic_pod_config.jsonのフルパス>"
# テスト一括実行
"MagicPodDesktop.app/Contents/MacOS/MagicPodDesktop" run --magic_pod_config="<magic_pod_config.jsonのフルパス>" - magic_pod_config.jsonの設定に従い、テストが実行されます。テストが成功した場合はプロセスの返り値は0、失敗した場合は1、異常終了した場合は-1になります。
magic_pod_config.jsonをコピーすれば、他のMac PCでも同様にしてコマンドライン実行が可能です。
ただし、認証情報だけではmagic_pod_config.jsonに保存されていないので、一度MagicPodDesktopを起動してメールアドレスとパスワードを入力し、認証情報をPCに保存しておく必要があります。
2. Windowsでのテスト一括実行
WindowsのPowerShellから行うことができます。
設定ファイルを記述
まずは、テストのコマンドライン実行に必要な設定ファイルの記述を行います。
簡単な方法として、MagicPod上のテスト一括実行設定画面より「テスト結果の表示言語」以外の項目を設定、残りの項目を設定ファイルにて記述するのがおすすめです。全ての項目を設定ファイルにて記述したい場合は、記述ファイルから"testSettingsNumber"項目を削除してください。
MagicPodDesktopを一度でも起動していれば、フォルダ「C:\Users\<ユーザー名>\AppData\Roaming\magic_pod_desktop」に「magic_pod_config.json」というファイルがあるはずなので(これがMagicPodDesktopが利用している設定ファイルです)、これをデスクトップなど適当な場所にコピーします。
コピーしたら、以下の形式に従い設定ファイルをJSON形式で記述します。
{
"owner": <組織名。表示名でなくURL中のアルファベット表記のもの>,
"project": <プロジェクト名。表示名でなくURL中のアルファベット表記のもの>,
"capabilities": <対象ブラウザ等の設定。SeleniumのDesired Capabilitiesと同じ>,
"sendMail": <テスト結果メールを配信するか。省略するとfalse>,
"baseUrl": <ベースURL>,
"captureType": <テスト結果画面キャプチャの設定。on_error、on_ui_transit、on_each_stepのいずれか。省略するとon_each_step>,
"stepCaptureScope": <各行の画面キャプチャにHTMLの内容だけを含めるか、ブラウザウィンドウ全体を含めるか。html、windowのいずれか。省略するとhtml>
"xmlTestOutput": <JUnit形式のテスト結果XMLを出力するか。主にJenkins連携用。省略するとfalse>,
"workDir": <作業ディレクトリのフルパス。省略するとデスクトップの「magicPod」>,
"authTokenFilePath": <認証トークンファイルのフルパス。省略するとC:\Users\【ユーザ名】\.magic_pod_token>
"envVars": <KEY=VALUE形式の環境変数文字列のリスト。省略すると空リスト>,
"testNumber": <実行対象のテスト番号をカンマ区切りで記載。空または省略すると全テストを実行>,
"includedTestCaseLabels": <テスト対象のラベルを文字列リスト形式で指定>,
"excludedTestCaseLabels": <テスト対象外のラベルを文字列リスト形式で指定>,
"logLevel": <ログを出す量の設定。beginner、expert、magic_pod_bug_investigationのいずれか。省略するとbeginner>,
"retryCount": <失敗したテストを最大何回リトライするか。省略すると0(つまりリトライはしない)>,
"language": <テスト実行ログの表示言語。jaまたはen。省略するとen>,
"visualDiffPattern": <画像差分パターン名。skipを指定することも可能。省略すると未指定扱い>,
"testCondition": <テスト実行時の条件(※後述の例参照)>,
"testSettingsNumber": <MagicPod一括実行設定の番号>,
"testSettingsPatternName": <設定パターン名。対応する設定内に複数のパターンがある場合のみ必須>
}
共有変数を指定する場合はこちらを参考にしてください。
設定ファイル内の値に変数を用いる場合はこちらを参考にしてください。
以上を踏まえると、設定の記述は、例えば以下のようになります。
- capabilitiesとtestConditionに似たような内容を書かなければならないのは現状の仕様ですが、今後改善予定です。testConditionはなくてもテスト実行できますが、Web上でテスト結果を閲覧する際にブラウザの情報が抜け落ちてしまいます。
テストを実行
設定ファイルを作成したら、以下の手順でテストを実行します。
- MagicPodDesktopが起動している場合は終了しておきます。
- WindowsのPowerShellを開きます。方法はいくつかありますが、スタートメニューの「Windows PowerShell」から開くのが簡単です。
- 次のコマンドを実行します。「MagicPodDesktopのバージョン」の部分は、実際に存在するフォルダに応じて(0.36.0など)入力してください。PowerShell上で補完も効きます。先頭の「&」がないとエラーになりますので注意してください(PowerShell上で1から入力している場合には自動的に挿入されます)
& "C:\Users\<ユーザ名>\AppData\Local\magic_pod_desktop\app-<MagicPodDesktopのバージョン>\MagicPodDesktop.exe" run --magic_pod_config="<magic_pod_config.jsonのフルパス>"; Wait-Process -Name MagicPodDesktop -Timeout 3600
コマンド中の「3600」は、テストが終わるまでの最大待機秒数で、最大3600秒待つという意味です。この待ち時間は、テストの長さに応じて変更してください。 - magic_pod_config.jsonの設定に従い、テストが実行されます。
magic_pod_config.jsonをコピーすれば、他のWindows PCでも同様にしてコマンドライン実行が可能です。
ただし、認証情報だけはmagic_pod_config.jsonに保存されていないので、一度MagicPodDesktopを起動してメールアドレスとパスワードを入力し、認証情報をPCに保存しておく必要があります。
3. Linuxでのテスト一括実行
Windowsと似たような手順で、Linux上でのテスト一括実行も可能です。
必要なライブラリのインストール
まずは、xvfb(ブラウザの描画を行うために必要なライブラリ)とimagemagick(ブラウザウィンドウ全体のスクリーンショットを取得するのに必要なライブラリ)をインストールします。Ubuntuの場合は、以下のコマンドでインストールできます。
なお、CircleCIなど一部のクラウドCIサービスではxvfbとimagemagickが最初からインストールされているので、この手順は不要です。
次に、Chromeを使ってテストを実行する場合は、Chromeをインストールします。Ubuntuの場合は、以下のコマンドでインストールできます。
wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list'
sudo apt-get update
sudo apt-get install google-chrome-stable
次に、日本語の画面キャプチャが文字化けしないように日本語フォントをインストールします。Ubuntuの場合は、以下のコマンドでインストールできます。
以下コマンドをコマンドラインで実行してダウンロード
curl -L "https://app.magicpod.com/api/v1.0/magicpod-clients/local/linux/latest/" -H "Authorization: Token {apikey}" --output {filename}.zip
- {apikey}: APIトークン
- {filename}: お好きなファイル名
もしくはダウンロードページからmagicpod-command-line for Linuxのzipファイルを取得して解凍し、得られたmagicpod-command-lineとnode_modulesディレクトリを適当な場所に配置します(2つとも同じ場所に配置してください)。
設定ファイルを記述
Windowsの場合と同様の形式で、「magic_pod_config.json」を作成します(コピーできるような元ファイルは無いので、エディタなどで作成してください)。
認証情報を設定
MagicPodDesktopによるログインが成功したことがあるPCなら、Macならフォルダ「/Users/<ユーザー名>」以下に、Windowsならフォルダ「C:\Users\<ユーザー名>」に「.magic_pod_token」というファイルがあるはずです。このファイルがログインユーザーの認証情報ファイルなので、これをLinuxマシンの「~/」以下にコピーします。
もしくは、以下のコマンドを実行して{"token":"****"}という形式のトークン情報を取得し、****の部分の内容をファイル「~/.magic_pod_token」に保存することでも、認証情報を設定可能です。(SAML認証設定済みでないユーザのみ)
# xxxxにはMagicPodで使うメールアドレス、yyyyにはパスワードを指定
curl -X POST -L --data-urlencode "email=xxxx" --data-urlencode "password=yyyy" https://app.magicpod.com/api/v0.1/internal/token-auth/
なお、「~/.magic_pod_token」のパスはmagic_pod_config.jsonのauthTokenFilePathで変更することも可能です。
Xvfbの起動
テストを実行する前にxvfbを起動し、終わったら終了しておく必要があります。CircleCIなど一部のクラウドCIサービスではこの処理は自動的に行われるので不要です。Jenkinsを使っている場合は、Xvfbプラグインを使うとジョブ実行時に自動的にXvfbが起動します。それ以外の場合は、テスト実行時のコマンドを変えることでXvfbとテストを一緒に起動できます(後述)。
テストを実行
準備ができたら、以下のコマンドでテストを実行できます。こちらはCircleCIやJenkins等で既にXvfbが起動している場合のコマンドです。
Xvfbとテストを一緒に起動する場合のコマンドは以下のようになります。
いずれの場合も、magicpod-command-lineにパスを通すか実行時にフルパスもしくはmagicpod-command-lineへの相対パスを指定する必要があります。
テスト結果を動画で保存する
Linux環境でのローカルテスト実行に限り、テスト中の様子を動画として保存することができます。
テスト実行前に、動画の保存に必要なffmpegというツールをインストールします。
sudo apt install ffmpeg
続いて、テスト用の設定ファイルに動画保存用のオプションを追加します。このオプションは画面操作では追加できず、必ず設定ファイルを手で編集する必要があるので注意してください。キーにrecord_type、値にalwaysを指定するとテスト実行のたびに毎回動画を保存します。値にonly_failedを指定するとテスト失敗時のみ保存、neverを指定すると保存しないという設定になります。
{
"owner": "MyCompany",
"project": "SampleWebApp",
"capabilities": {
"browserName": "chrome"
},
"sendMail": true,
"testCondition": {
"browser": "chrome",
"record_type": "always"
}
}
テスト実行時には必要に応じていくつかの環境変数を設定します。
# 原則必須
export MAGIC_POD_RECORDING_SCREEN_SIZE=1280x1024
# オプション
export MAGIC_POD_RECORDING_DISPLAY=:99.0
export MAGIC_POD_RECORDING_FRAME_RATE=8
xvfb-run magicpod-command-line --magic_pod_config=""
変数名 | 意味 | デフォルト値 |
MAGIC_POD_RECORDING_SCREEN_SIZE | Xvfbで描画しているディスプレイのうち、動画として保存する領域のサイズを指定します。(調べ方は後述) | なし (指定しなくても適当な範囲で動画が保存されますが、ブラウザのごく一部になってしまうことがあります) |
MAGIC_POD_RECORDING_DISPLAY | Xvfbで描画しているディスプレイの番号です。(調べ方は後述) | :99.0 |
MAGIC_POD_RECORDING_FRAME_RATE | 動画のフレームレート(1秒あたりのフレーム数)を指定します。値が大きいほど細かな動きを保存できますが、ファイルサイズが大きくなるためアップロードに時間がかかったり、ファイルサイズ上限(50MB)を超えてアップロードできないことがあります。 | 8 |
上2つの環境変数に何を指定するか調べるには、Xvfbを起動した状態にして使われているディスプレイ番号等を調べます。
# XvfbとChromeを手で起動する場合の例。普段のテストで使っている方法で起動してください
xvfb-run google-chrome --no-sandbox &
# 動作しているXvfbのプロセスと引数を確認
ps -ef | grep Xvfb
(出力例)
root 213 202 0 02:17 pts/1 00:00:00 Xvfb :99 -screen 0 640x480x16 -nolisten tcp -auth /tmp/xvfb-run.uyTR8o/Xauthority
root 810 13 0 02:18 pts/1 00:00:00 grep --color=auto Xvfb
640x480x16が画面の解像度を指定している箇所です。この場合、MAGIC_POD_RECORDING_SCREEN_SIZEは「640x480」となります。ディスプレイ番号は、最初の引数とscreenオプションの値を合わせて「:99.0」となります。デフォルト値が「:99.0」なのでこの場合は指定しなくても動きますが、値が異なる場合は環境変数で指定してください。変数の値を確認したあとは、必ず関連するプロセス(Xvfb、xvfb-run、google-chrome等)を終了させておいてください。
4. Macでの並列実機テスト一括実行
複数のテストをローカルPCに接続した実機で並列に実行する場合は、以下のようなmagic_pod_config.jsonを複数用意し、複数の実機を1つのPCに接続した上で、それぞれのmagic_pod_config.jsonを指定してMagicPodDesktopを実行します。なお、並列実機テストの場合、"testSettingsNumber"を使用せずに、設定ファイルを記述する必要があります。
iOSの並列実行設定
{
....
"capabilities": {
"udid": "<端末のUDID>",
"wdaLocalPort": <PC内の全てのMagicPod設定と重複しないポート番号>,
....
},
"internalAppiumPort": <PC内の全てのMagicPod設定と重複しないポート番号>,
"internalMagicPodPort": <PC内の全てのMagicPod設定と重複しないポート番号>,
"workDir": "<PC内の全てのMagicPod設定と重複しないディレクトリ>",
....
}
Androidの並列実行設定
{
....
"capabilities": {
"udid": "<端末のUDID>",
"systemPort": <PC内の全てのMagicPod設定と重複しないポート番号>,
"chromeDriverPort": <PC内の全てのMagicPod設定と重複しないポート番号>,
....
},
"internalAppiumPort": <PC内の全てのMagicPod設定と重複しないポート番号>,
"internalMagicPodPort": <PC内の全てのMagicPod設定と重複しないポート番号>,
"workDir": "<PC内の全てのMagicPod設定と重複しないディレクトリ>",
....
}
- ポートやworkDirは、ブラウザテスト、Androidテスト、iOSテスト全体を通して同じPC内で重複しないようにする必要があります。
- 端末のudidは、端末をUSBでマシンに接続した上で、iOSの場合はコマンドinstruments -s devices で(iOSシミュレータの情報もたくさん表示されるので注意してください。)、Androidの場合はコマンド ~/Library/Android/sdk/platform-tools/adb devices で取得することができます。
5. MagicPod一括実行設定を参照するmagic_pod_config.jsonを作成する
magic_pod_config.jsonを以下の形式で記述することで、事前に作成したMagicPod一括実行設定を参照できます。
- ご利用にはバージョン0.99.12以上のクライアントが必要です。
{
"owner": <組織名。表示名でなくURL中のアルファベット表記のもの>,
"project": <プロジェクト名。表示名でなくURL中のアルファベット表記のもの>,
"testSettingsNumber": <MagicPod一括実行設定の番号>,
"testSettingsPatternName": <設定パターン名。対応する設定内に複数のパターンがある場合のみ必須>
}
MagicPod一括実行設定から参照される項目
「テスト結果の表示言語」項目以外について、設定ファイル内に重複して記述した場合、MagicPod一括実行設定が優先されます。
例えば以下のtestConditionが実行時に参照されることはありません。
{
"owner": "MagicPodOrganization",
"project": "MagicPodProject",
"testSettingsNumber": 1,
"testCondition": {
"browser": "chrome",
}
}