@devicelab/maestro-runner-darwin-arm64 1.1.27 → 1.1.28

package/drivers/ios/WebDriverAgent/test/unit/webdriveragent.spec.ts

@@ -0,0 +1,562 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {describe, beforeEach, afterEach, it, mock} from 'node:test';
+
+import sinon from 'sinon';
+
+import type {WebDriverAgentArgs} from '../../lib/types.js';
+import * as utils from '../../lib/utils/index.js';
+import {selectWdaStartupStrategyName} from '../../lib/wda-strategies.js';
+
+let currentGetWDAUpgradeTimestamp: (...args: any[]) => any = utils.getWDAUpgradeTimestamp;
+
+mock.module('../../lib/utils/index.js', {
+  namedExports: {
+    ...utils,
+    getWDAUpgradeTimestamp: (...args: any[]) => currentGetWDAUpgradeTimestamp(...args),
+  },
+});
+
+const {BOOTSTRAP_PATH} = await import('../../lib/utils/index.js');
+const {WebDriverAgent} = await import('../../lib/webdriveragent.js');
+
+const fakeConstructorArgs: WebDriverAgentArgs = {
+  device: {
+    udid: 'some-sim-udid',
+  },
+  platformVersion: '9',
+  host: 'me',
+  realDevice: false,
+};
+
+const defaultAgentPath = path.resolve(BOOTSTRAP_PATH, 'WebDriverAgent.xcodeproj');
+const customBootstrapPath = '/path/to/wda';
+const customAgentPath = '/path/to/some/agent/WebDriverAgent.xcodeproj';
+const customDerivedDataPath = '/path/to/some/agent/DerivedData/';
+
+describe('WebDriverAgent', function () {
+  describe('startup strategy selection', function () {
+    it('should select an existing-url strategy for external WDA URLs', function () {
+      assert.strictEqual(selectWdaStartupStrategyName({webDriverAgentUrl: 'http://127.0.0.1:8100'}), 'existing-url');
+    });
+
+    it('should select a simulator strategy for simulator sessions', function () {
+      assert.strictEqual(selectWdaStartupStrategyName({realDevice: false}), 'simulator');
+    });
+
+    it('should select a real-device preinstalled strategy for no-xcode real-device sessions', function () {
+      assert.strictEqual(
+        selectWdaStartupStrategyName({realDevice: true, usePreinstalledWDA: true}),
+        'real-device-preinstalled',
+      );
+    });
+
+    it('should select a real-device xcodebuild strategy for default real-device sessions', function () {
+      assert.strictEqual(selectWdaStartupStrategyName({realDevice: true}), 'real-device-xcodebuild');
+    });
+  });
+
+  describe('Constructor', function () {
+    it('should have a default wda agent if not specified', function () {
+      const agent = new WebDriverAgent(fakeConstructorArgs);
+      assert.strictEqual(agent.bootstrapPath, BOOTSTRAP_PATH);
+      assert.strictEqual(agent.agentPath, defaultAgentPath);
+    });
+    it('should have custom wda bootstrap and default agent if only bootstrap specified', function () {
+      const agent = new WebDriverAgent({
+        ...fakeConstructorArgs,
+        bootstrapPath: customBootstrapPath,
+      });
+      assert.strictEqual(agent.bootstrapPath, customBootstrapPath);
+      assert.strictEqual(agent.agentPath, path.resolve(customBootstrapPath, 'WebDriverAgent.xcodeproj'));
+    });
+    it('should have custom wda bootstrap and agent if both specified', function () {
+      const agent = new WebDriverAgent({
+        ...fakeConstructorArgs,
+        bootstrapPath: customBootstrapPath,
+        agentPath: customAgentPath,
+      });
+      assert.strictEqual(agent.bootstrapPath, customBootstrapPath);
+      assert.strictEqual(agent.agentPath, customAgentPath);
+    });
+    it('should have custom derivedDataPath if specified', async function () {
+      const agent = new WebDriverAgent({
+        ...fakeConstructorArgs,
+        derivedDataPath: customDerivedDataPath,
+      });
+      if (agent.xcodebuild) {
+        assert.strictEqual(await agent.xcodebuild.retrieveDerivedDataPath(), customDerivedDataPath);
+      }
+    });
+
+    it('should not create xcodebuild for real-device preinstalled sessions', function () {
+      const agent = new WebDriverAgent({
+        ...fakeConstructorArgs,
+        realDevice: true,
+        usePreinstalledWDA: true,
+      });
+      assert.throws(() => agent.xcodebuild, /xcodebuild is not available/);
+    });
+
+    it('should throw for real watchOS device sessions', function () {
+      assert.throws(
+        () =>
+          new WebDriverAgent({
+            ...fakeConstructorArgs,
+            platformName: 'watchOS',
+            realDevice: true,
+          }),
+        /Real watchOS device testing is not supported/,
+      );
+    });
+
+    it('should not throw for watchOS simulator sessions', function () {
+      assert.doesNotThrow(
+        () =>
+          new WebDriverAgent({
+            ...fakeConstructorArgs,
+            platformName: 'watchOS',
+            realDevice: false,
+          }),
+      );
+    });
+  });
+
+  describe('launch', function () {
+    it('should use webDriverAgentUrl override and return current status', async function () {
+      const override = 'http://mockurl:8100/';
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.webDriverAgentUrl = override;
+      const agent = new WebDriverAgent(args);
+      const wdaStub = sinon.stub(agent as any, 'getStatus');
+      wdaStub.callsFake(function () {
+        return {build: 'data'};
+      });
+
+      assert.deepStrictEqual(await agent.launch('sessionId'), {build: 'data'});
+      assert.strictEqual(agent.url.href, override);
+      if (agent.jwproxy) {
+        assert.strictEqual(agent.jwproxy.server, 'mockurl');
+        assert.strictEqual(agent.jwproxy.port, 8100);
+        assert.strictEqual(agent.jwproxy.base, '');
+        assert.strictEqual(agent.jwproxy.scheme, 'http');
+      }
+      if (agent.noSessionProxy) {
+        assert.strictEqual(agent.noSessionProxy.server, 'mockurl');
+        assert.strictEqual(agent.noSessionProxy.port, 8100);
+        assert.strictEqual(agent.noSessionProxy.base, '');
+        assert.strictEqual(agent.noSessionProxy.scheme, 'http');
+      }
+      wdaStub.reset();
+    });
+  });
+
+  describe('use wda proxy url', function () {
+    it('should use webDriverAgentUrl wda proxy url', async function () {
+      const override = 'http://127.0.0.1:8100/aabbccdd';
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.webDriverAgentUrl = override;
+      const agent = new WebDriverAgent(args);
+      const wdaStub = sinon.stub(agent as any, 'getStatus');
+      wdaStub.callsFake(function () {
+        return {build: 'data'};
+      });
+
+      assert.deepStrictEqual(await agent.launch('sessionId'), {build: 'data'});
+
+      assert.strictEqual(agent.url.port, '8100');
+      assert.strictEqual(agent.url.hostname, '127.0.0.1');
+      assert.strictEqual(agent.url.pathname, '/aabbccdd');
+      if (agent.jwproxy) {
+        assert.strictEqual(agent.jwproxy.server, '127.0.0.1');
+        assert.strictEqual(agent.jwproxy.port, 8100);
+        assert.strictEqual(agent.jwproxy.base, '/aabbccdd');
+        assert.strictEqual(agent.jwproxy.scheme, 'http');
+      }
+      if (agent.noSessionProxy) {
+        assert.strictEqual(agent.noSessionProxy.server, '127.0.0.1');
+        assert.strictEqual(agent.noSessionProxy.port, 8100);
+        assert.strictEqual(agent.noSessionProxy.base, '/aabbccdd');
+        assert.strictEqual(agent.noSessionProxy.scheme, 'http');
+      }
+    });
+  });
+
+  describe('get url', function () {
+    it('should use default WDA listening url', function () {
+      const args = Object.assign({}, fakeConstructorArgs);
+      const agent = new WebDriverAgent(args);
+      assert.strictEqual(agent.url.href, 'http://127.0.0.1:8100/');
+      (agent as any).setupProxies('mysession');
+      if (agent.jwproxy) {
+        assert.strictEqual(agent.jwproxy.scheme, 'http');
+      }
+      if (agent.noSessionProxy) {
+        assert.strictEqual(agent.noSessionProxy.scheme, 'http');
+      }
+    });
+    it('should use default WDA listening url with emply base url', function () {
+      const wdaLocalPort = '9100';
+      const wdaBaseUrl = '';
+
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.wdaBaseUrl = wdaBaseUrl;
+      args.wdaLocalPort = parseInt(wdaLocalPort, 10);
+
+      const agent = new WebDriverAgent(args);
+      assert.strictEqual(agent.url.href, 'http://127.0.0.1:9100/');
+      (agent as any).setupProxies('mysession');
+      if (agent.jwproxy) {
+        assert.strictEqual(agent.jwproxy.scheme, 'http');
+      }
+      if (agent.noSessionProxy) {
+        assert.strictEqual(agent.noSessionProxy.scheme, 'http');
+      }
+    });
+    it('should use customised WDA listening url', function () {
+      const wdaLocalPort = '9100';
+      const wdaBaseUrl = 'http://mockurl';
+
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.wdaBaseUrl = wdaBaseUrl;
+      args.wdaLocalPort = parseInt(wdaLocalPort, 10);
+
+      const agent = new WebDriverAgent(args);
+      assert.strictEqual(agent.url.href, 'http://mockurl:9100/');
+      (agent as any).setupProxies('mysession');
+      if (agent.jwproxy) {
+        assert.strictEqual(agent.jwproxy.scheme, 'http');
+      }
+      if (agent.noSessionProxy) {
+        assert.strictEqual(agent.noSessionProxy.scheme, 'http');
+      }
+    });
+    it('should use customised WDA listening url with slash', function () {
+      const wdaLocalPort = '9100';
+      const wdaBaseUrl = 'http://mockurl/';
+
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.wdaBaseUrl = wdaBaseUrl;
+      args.wdaLocalPort = parseInt(wdaLocalPort, 10);
+
+      const agent = new WebDriverAgent(args);
+      assert.strictEqual(agent.url.href, 'http://mockurl:9100/');
+      (agent as any).setupProxies('mysession');
+      if (agent.jwproxy) {
+        assert.strictEqual(agent.jwproxy.scheme, 'http');
+      }
+      if (agent.noSessionProxy) {
+        assert.strictEqual(agent.noSessionProxy.scheme, 'http');
+      }
+    });
+    it('should use the given webDriverAgentUrl and ignore other params', function () {
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.wdaBaseUrl = 'http://mockurl/';
+      args.wdaLocalPort = 9100;
+      args.webDriverAgentUrl = 'https://127.0.0.1:8100/';
+
+      const agent = new WebDriverAgent(args);
+      assert.strictEqual(agent.url.href, 'https://127.0.0.1:8100/');
+    });
+    it('should set scheme to https for https webDriverAgentUrl', function () {
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.webDriverAgentUrl = 'https://127.0.0.1:8100/';
+      const agent = new WebDriverAgent(args);
+      (agent as any).setupProxies('mysession');
+      if (agent.jwproxy) {
+        assert.strictEqual(agent.jwproxy.scheme, 'https');
+      }
+      if (agent.noSessionProxy) {
+        assert.strictEqual(agent.noSessionProxy.scheme, 'https');
+      }
+    });
+
+    it('should accept scheme-less webDriverAgentUrl values', function () {
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.webDriverAgentUrl = 'localhost:8100/aabbccdd';
+      const agent = new WebDriverAgent(args);
+      assert.strictEqual(agent.url.href, 'http://localhost:8100/aabbccdd');
+      (agent as any).setupProxies('mysession');
+      if (agent.jwproxy) {
+        assert.strictEqual(agent.jwproxy.scheme, 'http');
+      }
+    });
+
+    it('should throw for invalid webDriverAgentUrl with explicit scheme', function () {
+      const args = Object.assign({}, fakeConstructorArgs);
+      args.webDriverAgentUrl = 'http://';
+      const agent = new WebDriverAgent(args);
+      assert.throws(() => agent.url);
+    });
+  });
+
+  describe('setupCaching()', function () {
+    let wda: InstanceType<typeof WebDriverAgent>;
+    let wdaStub: sinon.SinonStub;
+    const getTimestampStub = sinon.stub();
+    currentGetWDAUpgradeTimestamp = getTimestampStub;
+
+    beforeEach(function () {
+      wda = new WebDriverAgent(fakeConstructorArgs);
+      wdaStub = sinon.stub(wda as any, 'getStatus');
+    });
+
+    afterEach(function () {
+      for (const stub of [wdaStub, getTimestampStub]) {
+        if (stub) {
+          stub.reset();
+        }
+      }
+    });
+
+    it('should not cache when no WDA is running', async function () {
+      wdaStub.callsFake(function () {
+        return null;
+      });
+
+      assert.strictEqual(await wda.setupCaching(), undefined);
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, undefined);
+    });
+
+    it('should cache when running WDA has only time', async function () {
+      wdaStub.callsFake(function () {
+        return {build: {time: 'Jun 24 2018 17:08:21'}};
+      });
+
+      assert.strictEqual(await wda.setupCaching(), 'http://127.0.0.1:8100/');
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, 'http://127.0.0.1:8100/');
+    });
+
+    it('should not cache when bundle id is not default without updatedWDABundleId capability', async function () {
+      wdaStub.callsFake(function () {
+        return {
+          build: {
+            time: 'Jun 24 2018 17:08:21',
+            productBundleIdentifier: 'com.example.WebDriverAgent',
+          },
+        };
+      });
+
+      assert.strictEqual(await wda.setupCaching(), undefined);
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, undefined);
+    });
+
+    it('should not cache when bundle id is different with updatedWDABundleId capability', async function () {
+      wdaStub.callsFake(function () {
+        return {
+          build: {
+            time: 'Jun 24 2018 17:08:21',
+            productBundleIdentifier: 'com.example.different.WebDriverAgent',
+          },
+        };
+      });
+
+      assert.strictEqual(await wda.setupCaching(), undefined);
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, undefined);
+    });
+
+    it('should cache when bundle id is equal to updatedWDABundleId capability', async function () {
+      wda = new WebDriverAgent({
+        ...fakeConstructorArgs,
+        updatedWDABundleId: 'com.example.WebDriverAgent',
+      });
+      wdaStub = sinon.stub(wda as any, 'getStatus');
+
+      wdaStub.callsFake(function () {
+        return {
+          build: {
+            time: 'Jun 24 2018 17:08:21',
+            productBundleIdentifier: 'com.example.WebDriverAgent',
+          },
+        };
+      });
+
+      assert.strictEqual(await wda.setupCaching(), 'http://127.0.0.1:8100/');
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, 'http://127.0.0.1:8100/');
+    });
+
+    it('should not cache if current revision differs from the bundled one', async function () {
+      wdaStub.callsFake(function () {
+        return {build: {upgradedAt: '1'}};
+      });
+      getTimestampStub.callsFake(async () => 2);
+
+      assert.strictEqual(await wda.setupCaching(), undefined);
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, undefined);
+    });
+
+    it('should cache if current revision is the same as the bundled one', async function () {
+      wdaStub.callsFake(function () {
+        return {build: {upgradedAt: '1'}};
+      });
+      getTimestampStub.callsFake(async () => 1);
+
+      assert.strictEqual(await wda.setupCaching(), 'http://127.0.0.1:8100/');
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, 'http://127.0.0.1:8100/');
+    });
+
+    it('should cache if current revision cannot be retrieved from WDA status', async function () {
+      wdaStub.callsFake(function () {
+        return {build: {}};
+      });
+      getTimestampStub.callsFake(async () => 1);
+
+      assert.strictEqual(await wda.setupCaching(), 'http://127.0.0.1:8100/');
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, 'http://127.0.0.1:8100/');
+    });
+
+    it('should cache if current revision cannot be retrieved from the file system', async function () {
+      wdaStub.callsFake(function () {
+        return {build: {upgradedAt: '1'}};
+      });
+      getTimestampStub.callsFake(async () => null);
+
+      assert.strictEqual(await wda.setupCaching(), 'http://127.0.0.1:8100/');
+      assert.strictEqual(wdaStub.calledOnce, true);
+      assert.strictEqual(wda.webDriverAgentUrl, 'http://127.0.0.1:8100/');
+    });
+  });
+
+  describe('usePreinstalledWDA related functions', function () {
+    describe('bundleIdForXctest', function () {
+      it('should have xctrunner automatically', function () {
+        const args = Object.assign({}, fakeConstructorArgs);
+        args.updatedWDABundleId = 'io.appium.wda';
+        const agent = new WebDriverAgent(args);
+        assert.strictEqual(agent.bundleIdForXctest, 'io.appium.wda.xctrunner');
+      });
+
+      it('should have xctrunner automatically with default bundle id', function () {
+        const args = Object.assign({}, fakeConstructorArgs);
+        const agent = new WebDriverAgent(args);
+        assert.strictEqual(agent.bundleIdForXctest, 'com.facebook.WebDriverAgentRunner.xctrunner');
+      });
+
+      it('should allow an empty string as xctrunner suffix', function () {
+        const args = Object.assign({}, fakeConstructorArgs);
+        args.updatedWDABundleId = 'io.appium.wda';
+        args.updatedWDABundleIdSuffix = '';
+        const agent = new WebDriverAgent(args);
+        assert.strictEqual(agent.bundleIdForXctest, 'io.appium.wda');
+      });
+
+      it('should allow an empty string as xctrunner suffix with default bundle id', function () {
+        const args = Object.assign({}, fakeConstructorArgs);
+        args.updatedWDABundleIdSuffix = '';
+        const agent = new WebDriverAgent(args);
+        assert.strictEqual(agent.bundleIdForXctest, 'com.facebook.WebDriverAgentRunner');
+      });
+
+      it('should have an arbitrary xctrunner suffix', function () {
+        const args = Object.assign({}, fakeConstructorArgs);
+        args.updatedWDABundleId = 'io.appium.wda';
+        args.updatedWDABundleIdSuffix = '.customsuffix';
+        const agent = new WebDriverAgent(args);
+        assert.strictEqual(agent.bundleIdForXctest, 'io.appium.wda.customsuffix');
+      });
+    });
+
+    describe('host operations', function () {
+      let sandbox: sinon.SinonSandbox;
+
+      beforeEach(function () {
+        sandbox = sinon.createSandbox();
+      });
+
+      afterEach(function () {
+        sandbox.restore();
+      });
+
+      it('should delegate real-device preinstalled launch and terminate to injected host ops', async function () {
+        const launchPreinstalled = sandbox.stub().resolves();
+        const terminate = sandbox.stub().resolves();
+        const agent = new WebDriverAgent({
+          ...fakeConstructorArgs,
+          device: {udid: 'real-device-udid'},
+          realDevice: true,
+          usePreinstalledWDA: true,
+          wdaLocalPort: 9100,
+          updatedWDABundleId: 'io.appium.wda',
+          mjpegServerPort: 9200,
+          wdaBindingIP: '127.0.0.1',
+          maxHttpRequestBodySize: 1024,
+          hostOps: {
+            realDevicePreinstalled: {
+              launchPreinstalled,
+              terminate,
+            },
+          },
+        });
+        sandbox.stub(agent as any, 'getStatus').resolves({build: 'data'});
+
+        assert.deepStrictEqual(await agent.launch('sessionId'), {build: 'data'});
+        sinon.assert.calledOnce(launchPreinstalled);
+        assert.partialDeepStrictEqual(launchPreinstalled.firstCall.args[0], {
+          udid: 'real-device-udid',
+          bundleId: 'io.appium.wda.xctrunner',
+          wdaLocalPort: 9100,
+        });
+        assert.deepStrictEqual(launchPreinstalled.firstCall.args[0].env, {
+          USE_PORT: 9100,
+          WDA_PRODUCT_BUNDLE_IDENTIFIER: 'io.appium.wda.xctrunner',
+          MJPEG_SERVER_PORT: 9200,
+          USE_IP: '127.0.0.1',
+          MAX_HTTP_REQUEST_BODY_SIZE: 1024,
+        });
+
+        await agent.quit();
+        sinon.assert.calledOnceWithExactly(terminate, {
+          udid: 'real-device-udid',
+          bundleId: 'io.appium.wda.xctrunner',
+        });
+      });
+
+      it('should use wdaRemotePort rather than wdaLocalPort for the device USE_PORT', async function () {
+        const launchPreinstalled = sandbox.stub().resolves();
+        const terminate = sandbox.stub().resolves();
+        const agent = new WebDriverAgent({
+          ...fakeConstructorArgs,
+          device: {udid: 'real-device-udid'},
+          realDevice: true,
+          usePreinstalledWDA: true,
+          wdaLocalPort: 9100,
+          wdaRemotePort: 8100,
+          updatedWDABundleId: 'io.appium.wda',
+          hostOps: {
+            realDevicePreinstalled: {
+              launchPreinstalled,
+              terminate,
+            },
+          },
+        });
+        sandbox.stub(agent as any, 'getStatus').resolves({build: 'data'});
+
+        await agent.launch('sessionId');
+        sinon.assert.calledOnce(launchPreinstalled);
+        assert.deepStrictEqual(launchPreinstalled.firstCall.args[0].env, {
+          USE_PORT: 8100,
+          WDA_PRODUCT_BUNDLE_IDENTIFIER: 'io.appium.wda.xctrunner',
+        });
+      });
+
+      it('should require injected host ops for real-device preinstalled launch', async function () {
+        const agent = new WebDriverAgent({
+          ...fakeConstructorArgs,
+          device: {udid: 'real-device-udid'},
+          realDevice: true,
+          usePreinstalledWDA: true,
+        });
+
+        await assert.rejects(agent.launch('sessionId'), 'Host operations must be provided');
+      });
+    });
+  });
+});

package/drivers/ios/WebDriverAgent/tsconfig.json

@@ -2,15 +2,13 @@
   "$schema": "https://json.schemastore.org/tsconfig",
   "extends": "@appium/tsconfig/tsconfig.json",
   "compilerOptions": {
-    "strict": false,  // TODO: make this flag true
     "esModuleInterop": true,
     "outDir": "build",
-    "types": ["node", "mocha"],
-    "checkJs": true
+    "types": ["node"],
+    "checkJs": true,
+    "strict": true,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
   },
-  "include": [
-    "index.ts",
-    "lib",
-    "test"
-  ]
+  "include": ["lib", "test"]
 }

package/drivers/ios/devicelab-ios-agent/README.md

@@ -0,0 +1,51 @@
+# devicelab-ios-agent (prebuilt)
+
+> The agent builds in `simulator/` and `device/` are proprietary binaries, free to use with
+> maestro-runner but not open source: see [../../LICENSE-BINARIES.md](../../LICENSE-BINARIES.md).
+> `signing-stub/` is source under the Apache License 2.0.
+
+The XCUITest agent behind `--driver devicelab` on iOS simulators and real iPhones, built from
+the private `devicelab-ios-agent` repository with `scripts/build.sh`
+(universal arm64 + x86_64, Swift Testing interop libraries bundled).
+
+`simulator/manifest.json` records the agent commit (`version`), the wire
+protocol and a sha256 per file. The host re-installs the agent on a
+simulator when `version` changes.
+
+To update: build in the agent repository, then replace `simulator/` with its
+`dist/simulator/`.
+
+## Real iPhones
+
+`device/` is the same agent built with `scripts/build.sh --device --release`:
+arm64, unsigned, no XCTest frameworks. Replace it with the agent repository's
+`dist/device/`.
+
+`signing-stub/` is a tiny public Xcode project (a host app and a UI-test
+bundle, no agent code) with the agent's bundle ids. On the first run on a
+device, maestro-runner builds it with `-allowProvisioningUpdates
+DEVELOPMENT_TEAM=<--team-id>` so Xcode provisions the device, then re-signs a
+copy of `device/` with the stub's certificate, profiles, entitlements and
+XCTest frameworks. The signed agent is cached under
+`~/.maestro-runner/cache/devicelab-ios-agent/device-signed/<version>-<team>-<udid>/`
+until the agent changes or its profile nears expiry.
+
+```bash
+maestro-runner --platform ios --driver devicelab --team-id <TEAM_ID> \
+  --device <UDID> --app-file <signed .app or .ipa> test <flows>
+```
+
+Regenerate `SigningStub.xcodeproj` from `signing-stub/project.yml` with
+`xcodegen generate`.
+
+Overrides:
+
+- `DEVICELAB_IOS_AGENT_DIR` — use an agent build from another directory
+- `DEVICELAB_IOS_AGENT_LAUNCH` — `auto` (default), `simctl` or `xcodebuild`
+- `DEVICELAB_IOS_AGENT_KEEP=0` — stop the agent when the run ends
+  (by default an agent started with simctl stays up for the next run)
+- `DEVICELAB_IOS_AGENT_DEVICE_DIR` — use a device agent build from another
+  directory
+- `DEVICELAB_IOS_AGENT_BUNDLE_ID` — sign the agent on a device as another
+  bundle id (a personal team cannot use the team wildcard App ID, and
+  `dev.devicelab.agent` may already be registered elsewhere)

package/drivers/ios/devicelab-ios-agent/device/DevicelabIOSAgent.app/PkgInfo

@@ -0,0 +1 @@
+APPL????