ADB Extension | T-Plan Robot | T-Plan

Mobileコマンドとして標準で提供されています。このプラグインは今後メンテナンスされません。

1. 概要

ADB Extension Pluginは、Android Over ADB接続を使用してAndroidデバイスをテストするT-Plan Robot Enterpriseスクリプトに新機能を追加します。これには以下が含まれます:

デバイス上のローカル.apkファイルからアプリケーションをインストール/アンインストール、
クライアントマシンとデバイス間でのファイルコピー、
デバイス上でのシェルコマンドの実行。

このプラグインは主にTPR言語で記述されたスクリプト向けに設計されています。Javaからプラグインスクリプトを呼び出すには、DefaultJavaTestScript.run()メソッドを使用するか、Java Script Basicsドキュメントに記載されているスクリプトインスタンスのアプローチを使用してください。

このプラグインは、完全なソースコードとともに"現状のまま"提供されます。自由に変更・再利用できます。NetBeansやEclipseなどのIDEでコードをコンパイルできるようにするには、以下のライブラリをプロジェクトのクラスパスに追加してください:

robot.jarファイル(T-Plan Robot Enterpriseのインストールフォルダ内)
ddmlib.jar(<Android_SDK_home>/tools/lib内)

ご質問やご提案がございましたら、T-Plan supportまでご連絡ください。T-Planが提供する他のプラグインの一覧については、こちらをご覧ください。

2. プラグインのインストール

このプラグインには以下が必要です:

バージョン2以降は T-Plan Robot 3.4.2以降が必要です。バージョン1は2013年7月15日以降に公開されたT-Plan Robot 3.4.1またはそれ以降のリリースで動作します。
Robotには、Android SDKのインストール先への有効なパスを設定する必要があります。設定するには、以下のいずれかを行ってください:
- オプション1: "Android Over ADB"接続タイプを選択した状態で、Robotのログインウィンドウにパスを入力します。次にConnectを押して接続を確立すると、パスがユーザー環境設定に保存されます。
- オプション2: RobotのメニューからEdit->Preferencesを開始します。"Android Over ADB"パネルを選択してパスを入力し、OKで閉じます。

以下からプラグインをダウンロードします:

https://downloads.t-plan.com/releases/robot/plugins/adbextension_v3.zip

バージョン間の違いについてはChange Logを参照してください。

オプション1:

ファイルを解凍し、adbextension.jarファイルをRobotのインストールディレクトリ配下のplugins/ディレクトリにコピーします。これにより、起動時にRobotがクラスをロードするようになります。プラグインの古いバージョンが残っていないか必ず確認して削除してください。
Robotを起動または再起動します。

オプション2:

ファイルをハードドライブ上の任意の場所に解凍します。
TPRスクリプトでこのプラグインを使用する場合は、各スクリプトの先頭に以下のコマンドを記述します:

Include "<location>/adbextension.jar"

Javaスクリプトでこのプラグインを使用する場合は、adbextension.jarファイルをJavaのクラスパスに追加します。

プラグインをアンインストールするには、ファイルを削除するだけです。

3. 使用方法

このプラグインには7つのJavaスクリプトが含まれています:

スクリプト名	説明
com.tplan.adb.Install	デバイスにアプリケーションをインストールします。
com.tplan.adb.Uninstall	デバイスからアプリケーションをアンインストールします。
com.tplan.adb.Push	ローカルファイルをデバイスにプッシュ(コピー)します。
com.tplan.adb.Pull	デバイスからファイルをプル(コピー)します。
com.tplan.adb.Shell	デバイス上でシェルコマンドを実行します。
com.tplan.adb.Start	デバイス上でアクティビティ(アプリケーション)を開始します(バージョン2以降)。
com.tplan.adb.Stop	デバイス上でアプリケーションを強制終了します(バージョン2以降)。

プラグインスクリプトは、Runコマンドを使用してTPRスクリプトから呼び出します。コマンドインスタンスはCommand Wizardツールを使用すると簡単に作成できます。既存のRunコマンドを編集するには、右クリックしてコンテキストメニューからPropertiesを選択します。

バージョン2では、アプリケーションのテストライフサイクルが大幅に簡素化されました。.apk形式のアプリケーションは、以下のように簡単にインストール、開始、停止/強制終了、アンインストールできます:

// Load the ADB Extension plugin 
Include "C:\temp\ADB_Extension.jar" 

// Install the test application 
Run "com.tplan.adb.Install" file="C:\temp\myapp.apk" 

// Start the test application 
Run "com.tplan.adb.Start" 

// Do some testing here... 

// Restart the application 
Run "com.tplan.adb.Stop" 
Run "com.tplan.adb.Start" 

// Do some more testing here... 

// Uninstall the application 
Run "com.tplan.adb.Uninstall"

Android SDK APIには実行中のADB操作を停止する手段がないため、Install、Uninstall、Push、Pullの各スクリプトはキャンセルできません。操作の実行中にユーザーがスクリプトを手動で停止しても、その操作は完了するまでバックグラウンドで実行され続けます。例えば、Installの実行中にスクリプトを停止しても、他の理由で失敗しない限り、アプリケーションは結局インストールされる可能性が高いです。これは、APIが実行中のシェル呼び出しのキャンセルを許可しているShellスクリプトと、その派生であるStartおよびStopには当てはまりません。

3.1 Installスクリプト

説明

com.tplan.adb.Installスクリプトは、現在接続されているAndroidデバイスに、ローカルの.apkファイルからアプリケーションをインストールします。これはAndroid SDKの"adb install"コマンドを呼び出します。

アプリケーションのインストールが成功すると、このスクリプトは_ADB_INSTALLED_PACKAGE変数にアプリケーションのパッケージ名を設定します。この値は、Uninstallスクリプトによるアンインストール時に使用できます。パッケージ名は別タスクで.apkファイルから抽出されるため、.apk形式が更新された場合など、インストール自体は正常に完了しても変数の作成に失敗することがあります。そのような不具合が発生した場合はT-Plan supportまでご報告ください。

バージョン2では、_ADB_INSTALLED_ACTIVITY変数にメインアプリケーションアクティビティ名も設定されます。これはパッケージ名と組み合わせて、Startスクリプトでアプリケーションを起動する際に使用できます。呼び出し元のテストスクリプトがインストールするアプリケーションが1つだけの場合、Start、Stop、またはUninstallの各スクリプトでパッケージやアクティビティを指定する必要はありません。最後にインストールされたアプリケーションにフォールバックします。

インストールを確認するには、スクリプトの終了コードがゼロであることをテストします。あるいは、"pm list packages"コマンドをShellスクリプトで実行し、アプリケーションのパッケージがリストされていることを確認してください。コードサンプルについてはExamplesセクションを参照してください。

構文(TPRスクリプト)

Run com.tplan.adb.Install file=<apk_file> [reinstall=<false|true>]

構文(Javaスクリプト)

run("com.tplan.adb.Install", "file", "<apk_file>" [, "reinstall", < "false" | "true" >]);

※ 赤色は必須パラメータを示します

オプション

file=<apk_file>

- ローカルファイルシステム内の.apkファイルへのフルパス。標準パスの1つを基準とした相対パスで指定するには、以下のようなデフォルト変数のいずれかを使用します:

- _INSTALL_DIR - Robotのインストールディレクトリ、
- _PROJECT_DIR - スクリプトが属するプロジェクトのホームフォルダ、
- _SCRIPT_DIR - スクリプトフォルダ(TPRスクリプトのみ)。

例えば、プロジェクトのホームフォルダに保存されているmyapp.apkファイルをインストールするには、以下のように指定します:

"{_PROJECT_DIR}/myapp.apk"

reinstall=<true|false>

- "true"を指定すると、同じバージョンが既にデバイスにインストールされていても再インストールします。デフォルト値はfalse(オフ、再インストールしない)です。

戻り値

このコマンドは成功時に0(ゼロ)を返します。アプリケーションのインストールに失敗した場合は1を返し、失敗内容は実行ログにも記録されます。

使用例

// プロジェクトホームフォルダ内のファイルを相対パスでJAR参照する例

Include "{_PROJECT_DIR}/adbextension.jar"

// プロジェクトフォルダにも保存されているmyapp.apkをインストール
Run "com.tplan.adb.Install" file="{_PROJECT_DIR}/myapp.apk" reinstall="true"

// 戻り値を確認して失敗を検出することを推奨します
if ({_EXIT_CODE} == 0) {
Step "Install myapp (check 1)" actual="Installed myapp (package {_ADB_INSTALLED_PACKAGE}) successfully."
} else {
Step "Install myapp (check 1)" result="fail" actual="Failed to install the application (exit code={_EXIT_CODE})!"
Exit 1
}

// 代替テスト - "pm list packages"シェルコマンドを実行し、対象パッケージがリストされているか確認します。
// "adb shell pm"の詳細については以下を参照してください: http://developer.android.com/tools/help/adb.html#pm
Run "com.tplan.adb.Shell" command="pm list packages"
if ("{_ADB_SHELL_OUTPUT}" contains "{_ADB_INSTALLED_PACKAGE}") {
Step "Install myapp (check 2)" actual="The app is present in the list of installed Android packages."
} else {
Step "Install myapp (check 2)" result="fail" actual="The app is not listed as installed!"
Exit 1
}

// ここでアプリケーションのテストを実行

// 終了時にアプリケーションをアンインストール。
// プラグインバージョン2以降ではpackageパラメータを省略可能です。
Run "com.tplan.adb.Uninstall" package="{_ADB_INSTALLED_PACKAGE}"

3.`2` Uninstallスクリプト

説明

com.tplan.adb.Uninstallスクリプトは、現在接続されているAndroidデバイスからアプリケーションをアンインストールします。これはAndroid SDKの"adb shell pm uninstall"コマンドを呼び出します。

構文(TPRスクリプト)

Run com.tplan.adb.Uninstall package=<application_package>

構文(Javaスクリプト)

run("com.tplan.adb.Uninstall", "package", "<application_package>" );

※ 赤色は必須パラメータを示します

オプション

package=<application_package>

- アンインストールするアプリケーションのパッケージ。

- バージョン2では、このパラメータを省略できます。その場合、Installテストスクリプトを通じて最後にインストールされたアプリケーションがアンインストールされます。
- バージョン1では、このパラメータは必須です。以前にInstallを通じてアプリケーションをインストールしていた場合は、_ADB_INSTALLED_PACKAGE変数に格納されているパッケージ名を使用できます。

戻り値

このコマンドは成功時に0(ゼロ)を返します。アプリケーションのアンインストールに失敗した場合は1を返し、失敗内容は実行ログにも記録されます。

使用例

Installの使用例を参照してください。

3.`3` PushおよびPullスクリプト

説明

com.tplan.adb.Pushとcom.tplan.adb.Pull スクリプトは、ローカルマシンから現在接続されているAndroidデバイスへ(Push)、またはその逆方向へ(Pull)ファイルをコピーできます。これらのスクリプトはAndroid SDKの"adb push/pull"呼び出しに依存しています。

重要: プラグインv1では、PullおよびPush操作はファイルのみに限定されています。ディレクトリのプッシュまたはプルを試みると、Android SDK API内部の問題(NullPointerException)により失敗します。この問題は今後のリリースで対応予定です。

構文(TPRスクリプト)

Run com.tplan.adb.Push local=<local_file> remote=<remote_file>
Run com.tplan.adb.Pull local=<local_file> remote=<remote_file>

構文(Javaスクリプト)

run("com.tplan.adb.Push", "local", "<local_file>", "remote", "<remote_file>");
run("com.tplan.adb.Pull", "local", "<local_file>", "remote", "<remote_file>");

※ 赤色は必須パラメータを示します

オプション

local=<local_file>

- コピー元(Push)またはコピー先(Pull)となるローカルファイル(ディレクトリ)。フルパスで指定する必要があります。標準の場所を基準とした相対パスの指定方法についてはInstallのオプションを参照してください。

remote=<remote_file>

- コピー元(Pull)またはコピー先(Push)となるリモートファイル(ディレクトリ)。フルパスで指定する必要があります。

戻り値
このコマンドは成功時に0(ゼロ)を返します。ファイルのコピーに失敗した場合は1を返し、失敗内容は実行ログにも記録されます。

使用例

// この例では、プラグインのJARが呼び出し元スクリプトと同じフォルダにあることを前提としています
Include "{_SCRIPT_DIR}/adbextension.jar"

// C:\data.txtファイルをAndroidデバイスのSDカードにコピー
Run "com.tplan.adb.Push" local="C:\data.txt" remote="/mnt/sdcard/data.txt"

// ファイルをSDカードからC:\data2.txtに戻してコピー
Run "com.tplan.adb.Pull" remote="/mnt/sdcard/data.txt" local="C:\data2.txt"

3.`4` Shellスクリプト

説明

com.tplan.adb.Shellスクリプトは、現在接続されているAndroidデバイス上で単一のシェルコマンドを実行します。これはAndroid SDKの"adb shell"コマンドを呼び出します。

シェルコマンドの出力は_ADB_SHELL_OUTPUT変数に格納され、文字列比較のブール演算子やStringコマンドを使ってさらにテスト・処理できます。

構文(TPRスクリプト)

Run com.tplan.adb.Shell command=<shell_command> [timeout=<time_value>] [log=<false|true>]

構文(Javaスクリプト)

run("com.tplan.adb.Shell", "command", "<shell_command>"[, "timeout", "<time_value>"] [, "log", <"true" | "false">]);

※ 赤色は必須パラメータを示します

オプション

command=<shell_command>

- "adb shell"プレフィックスを除いたシェルコマンド。使用可能なコマンドの一覧についてはADB Documentationを参照してください。

timeout=<timeout>

- コマンドのタイムアウト(任意)。値を設定しない、または0の場合、スクリプトは時間制限なしにコマンドの完了を待機します。このパラメータを設定すると、タイムアウトに達した時点でコマンドがキャンセルされ、終了コード2が返されます。ADBは内部的にタイムアウトを適用することがあるため、このパラメータを有効にしていなくてもコマンドがタイムアウトする可能性がある点に注意してください。

log=<true|false>

- trueを指定すると、シェルコマンドの出力が実行ログに書き込まれます。これは、スクリプト呼び出しの後にLog "{_ADB_SHELL_OUTPUT}"コマンドを続けて実行した場合と同じ効果があります。デフォルト値はfalse(ログに記録しない)です。

戻り値

Android SDKにはシェルコマンドの終了コードを返す手段が用意されていないため、シェルコマンド自体が実際には失敗した場合でも、このスクリプトはコマンドがシェルに正しく渡されたことを示すために、ほとんどの場合0(ゼロ)を返します。コマンドの実行が成功したかどうかは、_ADB_SHELL_OUTPUT の出力が期待される文字列やパターンと一致するかをテストすることでのみ確認できます(以下の例を参照)。接続がシェル呼び出しの途中でクラッシュした場合など、I/Oエラーが発生すると1が返されます。タイムアウト値が設定されている場合、コマンドがタイムアウトすると2が返されます。いずれの失敗も実行ログに記録されます。

使用例
その他のコードサンプルについてはInstallの使用例を参照してください。

// Androidのシステムログをダンプし、Robotの実行ログに出力します。
Run "com.tplan.adb.Shell" command="logcat -d" log="true"

// /mnt/sdcard/test.txtファイルの存在を確認
Run "com.tplan.adb.Shell" command="ls /mnt/sdcard/*"
if ("{_ADB_SHELL_OUTPUT}" contains "test.txt") {
Step "Verify file existence" actual="The test.txt file is listed in the \"ls /sdcard\" shell command output."
} else {
Step "Verify file existence" result="fail" actual="The file is not present in the listing of: {_ADB_SHELL_OUTPUT}"
}

3.`5` Startスクリプト

説明

com.tplan.adb.Startスクリプトは、Androidデバイス上でアクティビティ(すなわちアプリケーション)を開始します。これはAndroid SDKの"adb am start -n"コマンドを呼び出します。

シェルコマンドの出力は_ADB_SHELL_OUTPUT変数に格納され、文字列比較のブール演算子やStringコマンドを使ってさらにテスト・処理できます。

構文(TPRスクリプト)

Run com.tplan.adb.Start activity=<activity> [timeout=<time_value>] [log=<false|true>]

構文(Javaスクリプト)

run("com.tplan.adb.Start", ["activity", "<activity>"][, "timeout", "<time_value>"] [, "log", <"true" | "false">]);

※ 赤色は必須パラメータを示します

オプション

activity=<activity>

- このパラメータは任意で、省略した場合はInstallを通じて最後にインストールされたアプリケーションがデフォルトとして使用されます。アクティビティは"<package_name>/<activity_name>"の形式で指定する必要があります。アクティビティが同じパッケージ内にある場合は、ドット表記を使ったシンプルな名前で参照できます。例えば、以下の指定は同等です:

com.mycompany.myapp/com.mycompany.myapp.MainActivity

com.mycompany.myapp/.MainActivity

アプリケーションのパッケージ名とメインアクティビティの名前は、いくつかの方法で取得できます:

- アプリケーションの開発者/製造元に名前を確認します。
- 以前にInstallを通じてアプリケーションをインストールしていた場合は、_ADB_INSTALLED_PACKAGEおよび_ADB_INSTALLED_ACTIVITY変数を使用します。
- ローカルPC上に.apk形式のアプリケーションがある場合は、以下のいずれかの方法でパッケージを取得できます:
- - スクリプトエディタで一時的なInstallスクリプト呼び出しを作成し、Propertiesウィンドウを開きます。次に、アプリケーションファイルフィールドの横にある「...」ボタンをクリックし、ファイルナビゲータで.apkファイルを選択します。ウィンドウにパッケージ名とアクティビティ名が表示されます。
  - エディタで一時的なUninstallスクリプト呼び出しを作成し、Propertiesウィンドウを開きます。次に、パッケージ名フィールドの横にある「...」ボタンをクリックし、「Read from .apk」ボタンを使って名前を表示させます。
  - Android SDKインストール内のbuild-toolsフォルダに移動し、以下を実行します: aapt dump badging <file>
- アプリケーションが既にデバイスにインストールされている場合は、adbツール(<Android_SDK>\platform-toolsフォルダ内)を使ってそこから.apkをダウンロードします:
  - デバイス上のすべての.apkファイルを一覧表示します: adb shell pm list packages -f
  - ファイルをダウンロードします: adb pull <file>

timeout=<timeout>

log=<true|false>

戻り値

使用例

使用方法の章を参照してください。

3.`6` Stopスクリプト

説明

com.tplan.adb.Stopスクリプトは、現在接続されているAndroidデバイス上でアプリケーションを停止(強制終了)します。これはAndroid SDKの"adb am force-stop"または"adb am kill"コマンドを呼び出します。

シェルコマンドの出力は_ADB_SHELL_OUTPUT変数に格納され、文字列比較のブール演算子やStringコマンドを使ってさらにテスト・処理できます。

構文(TPRスクリプト)

Run com.tplan.adb.Stop package=<package> [force=<false|true>] [log=<false|true>]

構文(Javaスクリプト)

run("com.tplan.adb.Stop" [,"package", "<package>"] [, "force", "<"true" | "false">"] [, "log", <"true" | "false">]);

※ 赤色は必須パラメータを示します

オプション

package=<package>

- アプリケーションのパッケージ名(任意)。省略した場合は、Installを通じて最後にインストールされたアプリケーションがデフォルトとして使用されます。スクリプトのPropertiesウィンドウでは、デバイスにインストールされているパッケージの一覧から選択することもできます。パッケージを取得する他の方法についてはStartスクリプトを参照してください。

force=<true|false>

- 停止モードの切り替え(任意)。デフォルト値の"true"では、am force-stopを呼び出してアプリケーションを強制停止します。"false"の場合はam killが代わりに呼び出されます。これはよりソフトな方式で、"safe to kill and that will not impact the user experience"であるかどうかによって、アプリケーションが停止するかどうかが決まります。詳細はActivity Managerのドキュメントを参照してください。

log=<true|false>

戻り値

使用例

使用方法の章を参照してください。

4. 変更履歴

バージョン3(2015年3月23日リリース)

ADBライブラリのロード処理と別の接続の初期化との間の競合状態が原因で発生する、断続的なRobotのハングを修正。
エラー報告の改善。

バージョン2(2014年5月15日リリース)

新たに追加されたStartおよびStopスクリプトにより、対象デバイス上でアプリケーションを開始/強制終了できるようになりました。
Install スクリプトによるパッケージ検出処理は、aapt(Android SDKのツール)を使用するように再実装されました。このスクリプトは、アプリケーションのメインアクティビティ名を含む_ADB_INSTALLED_ACTIVITYという新しい変数も設定するようになりました。これはStartスクリプトと組み合わせてアプリケーションを起動する際に使用できます。Propertiesウィンドウでアプリケーションファイルを設定する際のファイル選択ダイアログには、現在選択されているファイルのパッケージとアクティビティが表示されます。
Uninstallスクリプトでは、packageパラメータが必須ではなくなりました。省略した場合は、Installを通じて最後にインストールされたアプリケーションがアンインストールされます。

バージョン1(2013年8月7日リリース)

Install、Uninstall、Push、Pull、Shellの各スクリプトの初期セット。

1. 概要

2. プラグインのインストール

3. 使用方法

3.1 Installスクリプト

説明

3.2 Uninstallスクリプト

説明

3.3 PushおよびPullスクリプト

説明

3.4 Shellスクリプト

説明

3.5 Startスクリプト

説明

3.6 Stopスクリプト

説明

4. 変更履歴

3.`2` Uninstallスクリプト

3.`3` PushおよびPullスクリプト

3.`4` Shellスクリプト

3.`5` Startスクリプト

3.`6` Stopスクリプト