ハートコア株式会社
HeartCore Roboドキュメント一覧
2023-01-04

XCodeを利用したiOSの自動化(XCode経由のiOS接続)

最終更新日:2023年2月20日

目次:
1. はじめに
2. Java要件
3. セットアップ
4. ロボットからの接続
5. トラブルシューティング
6. オートメーション


1.はじめに

注: XCode 7 での iOS 9デバイスの自動化について説明した旧マニュアルはこちら(英語)をご覧ください。

HeartCore Robo (Desktop)4.3.1以降で、Mac OS X上のXCode 8以降でのiOS 10+デバイスの自動化をサポートしています。

主な機能:
※接続がiOS Mirrorよりも遅いためにゲームなどのリアルタイムコントロールが必要なアプリケーションのテストには適していません。 代わりにiOSミラー接続(こちらは開発中アプリケーションプロジェクトへの組込が必要、開発アプリ以外のコントロール不可)を使用してください。 または、必要に応じてConnectコマンドを使用してオンザフライで接続を切り替えます。
※「XCode経由のiOS」接続に関しては、HeartCore RoboとJava、XCode、およびiOS(iPadOS)のバージョン違いやOSのシステム変更等の要因で接続できない場合があります。


2.Java要件

MacOS X Catalina以降で導入された新しいセキュリティ制限に関連する問題により、一部バージョンのJavaではLightning USBスクリーンミラーリングがサポートされません。お使いのJavaが対応していない場合は、HeartCore RoboのUI上で通知されます。

セキュリティ上の観点からもJava8、11、17等のJavaLTS版の最新Var.(Java8が最も安定しています)と各種バグフィクスに対応したHeartCore Robo v7以降の組み合わせを推奨します。Arm系CPU(M1Chip等)についてはいくつかの不具合がある可能性があります。 古いバージョンのHeartCore Roboでは、入手困難な古いバージョンのJavaでしか動作しません(OracleのJavaリリースアーカイブはOracleへのユーザー登録が必要になります)。 また、古いバージョンのJavaにおいては「PKIXエラー」が発生してHeartCore Roboが動作しなくなる事例が確認されておりますためサポート対象外とさせていただいております。ご了承ください。

Java Product Line サポートバージョン(v7以降) サポートバージョン(v6.3.2以降) サポートバージョン(v6.2.4以前)
Java 8(LTS) update251と262を除くJava8(推奨) update251と262を除くJava8 Java8 update242 (1.8.0_242)以前
Java 9 サポート終了 All supported All supported
Java 10 サポート終了 All supported All supported
Java 11(LTS) 11.0.7と11.0.8を除く全てのJava11 11.0.7と11.0.8を除く全てのJava11 Java 11.0.6以前
Java 12 サポート終了 All supported All supported
Java 13 サポート終了 All supported -
Java 14 サポート終了 - -
Java 15以降 サポート終了 All supported -
Java 17(LTS)以降 17(LTS)〜19対応(v7)、ただしLTS以外は順次サポート終了 17(LTS)、18対応(v6.3.5)、ただしLTS以外は順次サポート終了 -

  • サポートのためのテストは以下で行なっています:
  • Oracle Java(旧リリースへのアクセスはOracleとのサブスクリプション契約が必要です。)
  • Open JDK
  • AdoptOpenJDK
  • Amazon Corretto version 8 or 11 or 17 or 18 or 19
  • ※ LTS版においても提供ディストリビューター側のサポート期間終了に伴い順次弊社サポートが対応できない状況になる場合がございます。ご了承ください。



    3.セットアップ

    要件:


    1.WebDriverAgentのダウンロード:


    最新のWebDriverAgentプロジェクトをこのリンクからダウンロードします。(必ずこのリンクよりダウンロード)
    • 前バージョンからのアップグレードではありません。旧版を削除し新しいXCodeプロジェクトを設定してください。
    注1:公式の WebDriverAgentプロジェクトは使用しないでください。上述したリンクからダウンロードしたWebDriverAgentは、公式版をベースにランドスケープモードと完全なiOSコントロールを可能にするためのバグ修正と機能拡張を追加しているためです。
    注2:接続環境設定にはスイッチがありHeartCore Roboに対してカスタムプロジェクトバージョンを受け付けさせることができますが、その機能を保証するものではありません。


    2.プロジェクトのセットアップ手順:

    • 初回設定:プロジェクトに関しては リンクURLでの設定手順(または詳細な手順はこちらも確認)(ともに英語)に従ってください。
      以下は、導入のための簡単な解説です。※文章中に「$〜」とあるのはターミナルでの入力コマンドです($は入力しません)。
      • プロジェクトの依存関係にあるアプリケーションのインストール:以下はnpm、Carthage、およびGitの推奨手順:
      • ターミナルを開き、Homebrewをインストールします。Homebrewのインストールはページ内の手順で行ってください。
        下記記載テキストは一例です:
            $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
      • Homebrewを使用してNPM、Git、およびCarthageをインストールします。
            $ brew install node
            $ brew install git
            $ brew install carthage
      • ターミナルでWDAのホームディレクトリに切り替えてブートストラップスクリプトを実行します。Scriptsディレクトリ内にbootstrap.shが存在しない場合はこの手順をスキップできます。
           $ ./Scripts/bootstrap.sh
    • WDAプロジェクトをアップグレードした場合は上記セットアップを繰り返す:(Homebrew、NPM、Git、Carthageのアップグレード作業後)
      • ターミナルからWDAホームフォルダーに移動し、 ./Scripts/bootstrap.sh のスクリプトを実行します。依存関係をアップグレードするように求められたら、スクリプトを再実行してください。Scriptsディレクトリ内にbootstrap.shが存在しない場合はこの手順をスキップできます。


    3. XCodeのセットアップ手順:

    以下の場合はこの項のXCodeセットアップを繰り返す必要があります:

    • WebDriverAgentプロジェクトを更新または再ダウンロードした後。
    • XCodeが更新された後。
    • ターゲットデバイス上のiOSが更新された後。
    • 新しいデバイスをセットアップする必要がある場合。

    XCodeのバージョンによって表示画面が大きく変更される可能性があることにご注意ください。

    手順:

    • XCodeを起動します。 アプリケーションフォルダからWDAプロジェクトファイルを開きます。 
    • XCodeプロジェクトの場合:

    1. トップバーのWebDriverAgentRunnerスキームとターゲットデバイスを選択します。
    2. WebDriverAgentLibターゲットを選択します。「署名を自動的に管理する」 オプションがオンで、AppleDeveloper登録されている有効なチームが設定されていることを確認します。
    3. WebDriverAgentRunnerターゲットを選択します。「署名を自動的に管理する」 オプションがオンで、AppleDeveloper登録されている有効なチームが設定されていることを確認します。

  • WebDriverAgentLibでGeneralタブを選択します。
  • iOSマシンの動作OSバージョンを設定します。
  • MacOSのバージョンを設定します。オプションがオンで、AppleDeveloper登録されている有効なチームが設定されていることを確認します。
    • View-> Debug Area-> Activate Consoleでデバッグコンソールを開きます。
    • [XCode]メニューの[ Product-> Test ]を選択します。すべてが正常に動作するとアプリケーションはテストモードで起動し、XCode内のコンソール出力の下部に下記のような記述行が含まれ表示されます:
      ※記載されているhttp://~の部分は接続設定ごとで異なります。
    20xx-xx-xx xx:xx:xx.xxxxx+0100 WebDriverAgentRunner-Runner[785:276949] ServerURLHere->http://192.168.1.3:8100<-ServerURLHere

    • WDAサーバーが動作していることを確認するには、上記記載の行に含まれるURL(IPアドレス)を使用しMacOSのSafariで以下のような記載でURL(IPアドレス)を開きます。Safari上で「I-AM-ALIVE」と表示されれば接続は成功しています。 Safariにうまく表示されない場合でも、iOS上でWebDriverAgentが動作していればHeartCore RoboとiOS機器を接続することが可能です。
      また、この作業後iOSの画面上に「WebDriverAgentRunner」というアイコン画像のないアイコンが作成されますがこれは手動での接続時に利用できるアプリケーションになります。
    例:http://192.168.1.3:8100/health

    この作業を行った後は、HeartCofre Robo接続前にXCodeを実行する必要はありません。また、WebDriverAgentアプリケーションに関してもターゲットiOSデバイスに事前インストールする必要はありません。HeartCore Roboが接続時にXCode CLIツールを起動し、XCode CLIツールを使用してデバイスへ自動インストールします。上記プロセスは、WDAプロジェクトがXCode CLIツールを使用して構築および実行されるように正しく設定されていることを確認するためにのみ必要です。また、接続開始時間を短縮するコードをコンパイルしてくれます。


    4.HeartCore Roboでの接続

    ログイン画面で「XCode経由のiOS接続」を選択して接続します。

    接続時に以下情報を設定する必要があります:

    • 接続先のデバイスの名前。MacとiOS機器が正しく接続されていれば接続デバイスの選択リストに機器名が表示されます。
      v5.0.6以降では{_IOS_DEVICES}変数を利用してロボット実行時に必要なデバイス(リスト)名を取得することができます。
    • XCodeを使用して適切に構成され、かつ接続iOSデバイスに対して正しく設定されたWDAプロジェクトのパス

    注:キーボードマッピングは非常に遅く、10分以上かかる場合があります。HeartCore Roboで一度接続した後にキーマップオプションを保存し再接続時に使用すれば、繰り返し接続の際に起こる遅延を回避できます。


    5.トラブルシューティング

    • iOSデバイスに同梱のオリジナルのLightning USBケーブルを使用してください。AppleはiOSを他社製品のケーブルで接続拒否する場合がしばしば報告されています。
    • ケーブルを直接MacのUSBポートに接続します。USBスイッチまたはハブを使用しないでください。
    • Apple社のソフトウェアバージョンアップにより、接続手順が変わったり接続そのものができない場合が報告されています。詳細は弊社サポートまでお問い合わせください。

    6.自動化

  • 接続
  • タッチスクリーンのサポート
  • キーボードサポート
  • キーボードマッピング
  • システムアラート対応
  • 接続
    テストスクリプトからiOSデバイスに接続する場合は、Connectコマンド(TPRスクリプト)またはconnect()メソッド(Javaテストスクリプト)を使用します。 引数の URL は "xcode://localhost" の形式で、デバイス名 ("device") と WebDriverAgent のプロジェクトフォルダへのパス ("project") を指定する必要があります。"app" パラメータはオプションです。ローカルに保存された iOS アプリケーション (.ipa) をデバイスにインストールすることができます。その場合に、アプリケーションはWDAのデプロイメントに使用したのと同じ設定(証明書)で署名されている必要があります。
    たとえば、次のコマンド/メソッド呼び出しは、最初に検出されたデバイスに接続します:

    TPRテストスクリプトの例:    Connect XCode://localhost device="My iPhone" app="/Users/Joe/WebDriverAgent"
    Javaテストスクリプトの例:    connect("My iPhone", newFile("/Users/Joe/WebDriverAgent"), (File) null , false);

    もう1つの方法は、パラメータを接続URLクエリにエンコードすることです。この形式は、-c/--connect CLI接続にも適しています。
    最近使用した接続のURLは、ツール-> CLIウィザードウィンドウからコピーすることができます。もう1つの選択肢は、デスクトップ - >接続マネージャウィンドウで接続名を指定し、URLの代わりに使用することです。
    TPRテストスクリプトの例:     Connect "XCode://localhost?device=My%20iPhone&project=/Users/Joe/WebDriverAgent"

    タッチスクリーンのサポート

    ポートレート(縦位置)ランドスケープ左画面の向きのみサポートされています。他の位置でもは接続が切断されることはありませんが、タッチイベント(タップなど)は誤って配置される可能性があります。これはAppleのベースになっているフレームワークのバグが原因です。
    リモート接続されたiOS機器の画面向きを変えるには、Mac側のF4キーを押すか、テストスクリプトにF4キーを押させます(Press "F4")。これはv4.4.3からサポートされています。

    マウスジェスチャーは、以下のように解釈されます。
    • マウスクリックは、タッチスクリーンタップにマッピングされます。v4.4.2以降、ダブルクリック(タップ)とロングクリック(ロングタップ、「タッチアンドホールド」)がサポートされています。
    • マウスドラッグはスワイプにマッピングされます。
    • マウスホイールイベントはサポートされず、無視されます。
    • 他のタッチスクリーンジェスチャーは、「XCode経由のiOS接続」対応プラグインを介してサポートされることがあります。
    • Gestureコマンドを使ったモバイル機器のジェスチャー自動化にv6.2以降で対応しました。

    キーボードサポート

    HeartCore Roboにおいて、MacとiOS機器はライトニングケーブルでリモート接続されています。その際にはiOS機器のクリップボードに仕様上アクセスができないため、日本語のTypeコマンドでのテキスト入力およびPasteコマンドを利用したコピー&ペーストはできません。英語に関してはスクリーンキーボードの画像認識を利用し、リモート画面上に表示されたスクリーンキーボードを直接タップする形で文字入力を再現しています。

    ハードウェアキーマッピング:

    iOSハードウェアキー
    スクリプトキー名称
    (アクションの内容)

    キー操作の説明
    ホームボタン
    'Home'(右マウスクリック)
    ホームボタン動作。長押しとホームボタンのダブルタップはサポートされていません。
    <画面回転>
    'F4'
    画面を縦から横に回転、逆に戻します(4.4.3以降)

    他のキーはスクリーンキーボードでシミュレートされます。この接続はユーザ操作として機能します。つまり、表示されているキーボードページを切り替え、個々のキー(文字)を画像認識を利用してタップする仕組みになっています。 英語スクリーンキーボードのみの対応です。英文字の入力にはTypeコマンドを使用します。

    ルール:
    • Typeコマンドで入力する際にはキーボードを表示する必要があります。キーボードがオフのときに入力してもコマンドは無視されます。
    • 現在サポートされているキーボードロケール(言語)は英語だけです。ロボットの処理中にキーボードを手動などで切り替えると、間違ったキーが入力されるため、切り替えを行わないでください。
    • 接続は、現在のキーボードにあるキーだけをサポートします。複数キーマップを設定している場合は、ロボット動作前に標準キーボードに設定してください。
    • 一部のキーは、デバイスがポートレートモードのときに使用できない場合があります。たとえば、iPhoneのキーボードの「キーボードを隠す」キーは、ポートレートモードで押すことはできません。このキーが横長のキーボードだけに含まれているからです。
    • キーの長押しで表示されるリストにあるキーなどはサポートされません。
    • 絵文字キーボードはサポートされていません。回避策は、キーボードを表示した状態でのMouse "click"コマンドなどを使用して手動でロボット化することです。
    • 接続時の標準はSafariのキーボードマップです。アプリケーションによってキーボードレイアウトをカスタマイズしている場合は入力に失敗します。「XCode経由のiOS接続」対応プラグインcom.tplan.iosx.LoadKeyboardcom.tplan.iosx.RemapKeyboardスクリプトを使用してテストスクリプトから修正してください。
    スクリーンキーボードのほとんどのキーは、PCのキーボードと同等に配置されています(a-z、A-Z、0-9など)。ソフトキーボードの主なマッピングは、下表のとおりです。デバイスの種類や画面の向きによって使用できないキーが存在します。

    iOSキーボードキー
    (スクリーンキーボード)

    スクリプトキー名称
    (アクションの内容)

    キー動作の説明
    ENTER、GO
    'Enter'(改行)
    Enterキー。
    DELETE(削除)
    'Backspace'、'Delete'
    バックスペースキー。挿入ポイントの前にある文字を削除します。
      シフトキー
    'Up'(上矢印)
    シフトキーは、キーボードをシフトした文字(小文字=>大文字など)に切り替えます。
    キーボードのページによってラベルや外観が変わります。
    接続がそれ自身でスイッチを切り替えるので、シフト文字を入力するためにこのキーを手動で押す必要はありません。
      キーの切替
    'Right'(右矢印)
    このキーは、キーボードを次のキーボードページに切り替えます。
    キーボードのページによってラベルや外観が変わります。
    接続によって別のページから文字が入力される場合、このキーを手動で押す必要はありません。
      次のキーボード
    'F5'
    キーは次のキーボードロケールに切り替わります。
    接続がSafari標準のロケールだけをサポート(マッピング)しているので、ロケールを切り替えるとType、Typelineコマンドが適用できなくなります。
    その場合は手動でキーの入力ルーチンを作成する必要があります。入力支援を元に戻すには、基本キーボードロケールに戻す必要があります。
      ディクテーション
    'F6'
    ディクテーションを開始します。

    キーボードマッピング

    HeartCore Roboは起動時にキーボードマッピングを実行します。これは、現在のキーボードのすべてのページ(「レイアウト」と呼ばれる)を表示し、そのキーの位置を記録するプロセスです。この設定作業にはかなりの時間がかかります。そのため、ファイルへのキーマップデータ保存チェックボックスを有効にすることをお勧めします。こうすることでキーマッピングは最初の記録時の1度だけ実行され、2回目以降の接続は保存データを再利用します。動作キーボードを変更するとマッピングが無効になりますのでご注意ください。
    ※HeartCore Roboへの接続前に、必ず画面の回転ロック設定を解除しておいてください。ロックしたままだと回転してからのキーボードマッピングが動作しません。
    ※今後iOSのアップデートで、その設定を無効にする変更が導入される可能性があります。


    ログイン初回接続時のキーボードマッピングは、SafariブラウザのURLフィールドをクリックした際に表示されたキーボードに対して実行されます。他のアプリで異なるキーボード設定を使用したり、キーボードをカスタマイズしている場合はSafariのキーボードマッピングが正しく動作しません。これを修正するには、「XCode経由のiOS接続」対応プラグインを使用します:

  • com.tplan.iosx.LoadKeyboardスクリプトは、キーマップ・ファイルをロードすることができます。
  • com.tplan.iosx.RemapKeyboard>スクリプトは、デバイスの画面に表示されているキーボードの再マッピングを即座に実行します。com.tplan.iosx.LoadKeyboardよりかなり時間がかかりますがキーマップファイルを作成する手間を省くことができます。

  • キーボードマップファイルの表示と編集には、メニューからデスクトップ -> XCode経由のiOSキーマップエディタ… ウィンドウを使用します:

    • 現在表示されているレイアウトを特定するには、[レイアウトを検出]を選択します。
    • 「キーマップを作成」ボタンは、新しいキーボードマップを作成するためのマッピングプロセス全体を繰り返し新しいキーマップを作成します。
    • デバイス画面に表示された個々のレイアウトを再作成または修正するには、[マップレイアウト]を選択します。たとえば、上記のスクリーンショットの「Q」レイアウトは、Safariがいくつかの追加キーを追加するため、Notesアプリケーションには適用されません。文字を正しく入力するには、文字を再マッピングする必要があります。
    • 不足しているレイアウトを追加する場合も[マップレイアウト]を使用します。たとえば、上記のマップには3つのポートレートレイアウトしか含まれていません。'['を追加すると、画面に表示されマッピングされます。
    • スクリプトを無視するキーを削除するには、[削除]を使用します。レイアウトを削除することもできますが、レイアウトを再作成しないのであればレイアウト削除はお勧めしません。
    • 現在の接続セッションに変更を適用するには、[接続に適用]をクリックします。
    • 変更をキーマップファイルに保存するには、[ファイルに保存]をクリックします。保存されたキーマップは、キーマップ保存フラグが有効な場合に以降の接続で読み込まれます。
    • 変更内容を別のファイルに保存するには、[名前を付けて保存]をクリックします。これにより、LoadKeyboardスクリプトで使用するファイルを作成することができます。


    現在のマップファイルを削除し、最終的にデフォルトのSafariを再作成するには:
    • ログインダイアログを開き、[iOS Over XCode]接続を選択し、[デバイス名]フィールドの横にある[ ...]ボタンをクリックします。
    • このウィンドウにはUSB経由で接続されたデバイスのリストが表示され、デバイスのキーボードマップが作成されているかどうかが示されます。無効なキーボードを削除するには、[キーボードを削除] ボタンを使用します。
    • 保存されたキーマップオプションを有効にして再度接続すると、Safariのスクリーンキーボードを元にした新しいキーマップが作成されます。

    警告:この接続により、キーボードマッピングの処理中に画面の向きが強制的に変更されます。この手順により内蔵のジャイロスコープが作動するため、デバイスを手動で回転させて画面の向きを変更することができなくなります。この機能を再度有効にするには、デバイスをUSBに再接続し、保存されたキーボードを使用して再接続によるプログラムによる向きの変更を回避します。また、画面の回転を完全に無効にすることも可能です。


    システムアラート対応

    システムアラート(ポップアップ)を処理する場合、「XCode経由のiOS接続」対応プラグイン v0.5以降を使用してください。

  • com.tplan.iosx.GetAlertスクリプトは、アラートが表示されている場合、終了コード0を返します。アラートテキストとボタンは、変数として返されます。
  • com.tplan.iosx.DismissAlertスクリプトでは、警告を解除・受入やテキスト入力することができます。また、タップするボタン指定も可能です。


  • 付録:iOS接続時コマンド対応表

    XCode経由のiOS接続時のHeartCore Roboコマンド対応一覧表(PDF)