feat: allow for external xctest file (#116)

## Description

<!-- Provide a general summary of your changes -->

Harness default behaviour on iOS is to build and run an xctest project.
This allows injecting an internal build, which implies to also skip
doing a build on its own.

## Related Issue

<!--- This project only accepts pull requests related to open issues -->
<!--- If suggesting a new feature or change, please discuss it in an
issue first -->
<!--- If fixing a bug, there should be an issue describing it with steps
to reproduce -->
<!--- Please link to the issue here: -->

/

## Context

<!-- Why this feature was implemented in this particular way? -->
<!-- Is there anything reviewer needs to know before conducting code
review? -->

In environments such as AWS we can't sign on the host runner. So, we
have to build beforehand, then upload the XCTest to AWS which will then
resign it internally.
This means we need a way to inject an externally build and signed
xctest.

## Testing

<!-- Please describe how you tested your changes -->

---------

Co-authored-by: Szymon Chmal <szymon@chmal.it>

Author: hannojg

.nx/version-plans/version-plan-1778676000000.md

@@ -0,0 +1,5 @@
+---
+__default__: patch
+---
+
+Harness on iOS can now start from an externally prepared `.xctestrun` and derived data directory, so you can run XCTest-based flows on hosted device infrastructure without rebuilding the agent on the runner.

packages/platform-ios/src/__tests__/xctest-agent.test.ts

@@ -75,6 +75,9 @@ const originalCwd = process.cwd();
 const simulatorRuntime = 'com.apple.CoreSimulator.SimRuntime.iOS-26-0';
 const simulatorSdkVersion = '26.0';
 const xcodeVersion = 'Xcode 26.0\nBuild version 17A123';
+const originalExternalXCTestRunFile = process.env.HARNESS_IOS_XCTESTRUN_FILE;
+const originalExternalDerivedDataPath =
+  process.env.HARNESS_IOS_XCTEST_DERIVED_DATA_PATH;
 
 const createLongRunningSubprocess = (options?: {
   ignoreSignal?: NodeJS.Signals;
@@ -230,6 +233,14 @@ describe('xctest-agent orchestration', () => {
   });
 
   afterEach(() => {
+    restoreEnvVar(
+      'HARNESS_IOS_XCTESTRUN_FILE',
+      originalExternalXCTestRunFile
+    );
+    restoreEnvVar(
+      'HARNESS_IOS_XCTEST_DERIVED_DATA_PATH',
+      originalExternalDerivedDataPath
+    );
     rmBuildRoot();
     process.chdir(originalCwd);
     fs.rmSync(tempProjectRoot, { recursive: true, force: true });
@@ -614,6 +625,44 @@ describe('xctest-agent orchestration', () => {
     expect(mocks.spawn).toHaveBeenCalledTimes(2);
   });
 
+  it('skips building when an external xctestrun file is provided', async () => {
+    const externalDerivedDataPath = path.join(tempProjectRoot, 'external-derived');
+    const externalXCTestRunFilePath = path.join(
+      tempProjectRoot,
+      'external.xctestrun'
+    );
+
+    fs.mkdirSync(externalDerivedDataPath, { recursive: true });
+    fs.writeFileSync(externalXCTestRunFilePath, 'external xctestrun');
+    process.env.HARNESS_IOS_XCTESTRUN_FILE = externalXCTestRunFilePath;
+    process.env.HARNESS_IOS_XCTEST_DERIVED_DATA_PATH = externalDerivedDataPath;
+
+    const controller = createXCTestAgentController({
+      port: 49152,
+      target: {
+        kind: 'simulator',
+        id: 'sim-123',
+      },
+    });
+
+    await controller.prepare();
+    await controller.ensureStarted();
+
+    expect(mocks.spawn).toHaveBeenCalledTimes(1);
+    expect(mocks.spawn).toHaveBeenNthCalledWith(
+      1,
+      'xcodebuild',
+      expect.arrayContaining([
+        'test-without-building',
+        '-xctestrun',
+        externalXCTestRunFilePath,
+        '-derivedDataPath',
+        externalDerivedDataPath,
+      ]),
+      expect.any(Object)
+    );
+  });
+
   it('fails fast when the checked-in xcode project is missing', async () => {
     const projectPath = path.join(projectRoot, 'HarnessXCTestAgent.xcodeproj');
     const hiddenProjectPath = path.join(
@@ -666,6 +715,15 @@ const rmBuildRoot = () => {
   });
 };
 
+const restoreEnvVar = (name: string, value: string | undefined) => {
+  if (value === undefined) {
+    delete process.env[name];
+    return;
+  }
+
+  process.env[name] = value;
+};
+
 const getCurrentInputsHash = (): string => {
   const hash = createHash('sha256');
 

packages/platform-ios/src/xctest-agent.ts

@@ -27,6 +27,9 @@ const XCTEST_AGENT_SCHEME_NAME = 'HarnessXCTestAgent';
 const XCTEST_AGENT_PORT_ENV = 'HARNESS_XCTEST_AGENT_PORT';
 const XCTEST_AGENT_TARGET_BUNDLE_ID_ENV =
   'HARNESS_XCTEST_AGENT_TARGET_BUNDLE_ID';
+const XCTEST_AGENT_XCTESTRUN_FILE_ENV = 'HARNESS_IOS_XCTESTRUN_FILE';
+const XCTEST_AGENT_DERIVED_DATA_PATH_ENV =
+  'HARNESS_IOS_XCTEST_DERIVED_DATA_PATH';
 const XCTEST_AGENT_STARTUP_TIMEOUT_MS = 120_000;
 const XCTEST_AGENT_SHUTDOWN_TIMEOUT_MS = 5_000;
 const XCTEST_AGENT_STARTUP_POLL_INTERVAL_MS = 250;
@@ -101,6 +104,11 @@ type SimulatorXCTestAgentCacheContext = Omit<
   'artifactName' | 'destinationKind' | 'schemaVersion' | 'xctestrunRelativePath'
 >;
 
+type ExternalXCTestConfiguration = {
+  derivedDataPath: string;
+  xctestrunFilePath: string;
+};
+
 export type XCTestAgentController = {
   prepare: () => Promise<void>;
   ensureStarted: () => Promise<void>;
@@ -146,6 +154,51 @@ const getXCTestAgentDerivedDataPath = (
   return path.join(getXCTestAgentBuildRoot(projectRoot), destination);
 };
 
+const getEnvironmentPath = (name: string): string | null => {
+  const value = process.env[name]?.trim();
+
+  if (!value) {
+    return null;
+  }
+
+  return value;
+};
+
+const getExternalXCTestRunFilePath = (): string | null => {
+  return getEnvironmentPath(XCTEST_AGENT_XCTESTRUN_FILE_ENV);
+};
+
+const getExternalDerivedDataPath = (): string | null => {
+  return getEnvironmentPath(XCTEST_AGENT_DERIVED_DATA_PATH_ENV);
+};
+
+const assertExternalXCTestRunFileExists = (filePath: string) => {
+  if (fs.existsSync(filePath)) {
+    return;
+  }
+
+  throw new Error(
+    `Missing external XCTest run file at ${filePath}. Check ${XCTEST_AGENT_XCTESTRUN_FILE_ENV}.`
+  );
+};
+
+const getExternalXCTestConfiguration = (
+  fallbackDerivedDataPath: string
+): ExternalXCTestConfiguration | null => {
+  const xctestrunFilePath = getExternalXCTestRunFilePath();
+
+  if (!xctestrunFilePath) {
+    return null;
+  }
+
+  assertExternalXCTestRunFileExists(xctestrunFilePath);
+
+  return {
+    derivedDataPath: getExternalDerivedDataPath() ?? fallbackDerivedDataPath,
+    xctestrunFilePath,
+  };
+};
+
 const getXCTestAgentBuildManifestPath = (derivedDataPath: string): string =>
   path.join(derivedDataPath, 'build-manifest.json');
 
@@ -877,6 +930,7 @@ export const createXCTestAgentController = (options: {
     'xcodebuild.log'
   );
   let preparedDerivedDataPath = getXCTestAgentDerivedDataPath(target.kind);
+  let preparedXCTestRunFilePath: string | null = null;
   let prepared = false;
   let agentProcess: Subprocess | null = null;
   let agentClient: ReturnType<typeof createXCTestAgentClient> | null = null;
@@ -912,6 +966,24 @@ export const createXCTestAgentController = (options: {
       return;
     }
 
+    const externalXCTestConfiguration = getExternalXCTestConfiguration(
+      preparedDerivedDataPath
+    );
+
+    if (externalXCTestConfiguration) {
+      preparedDerivedDataPath = externalXCTestConfiguration.derivedDataPath;
+      preparedXCTestRunFilePath =
+        externalXCTestConfiguration.xctestrunFilePath;
+
+      prepared = true;
+      xctestAgentLogger.info(
+        'Using external XCTest run file for %s target: %s',
+        target.kind,
+        preparedXCTestRunFilePath
+      );
+      return;
+    }
+
     let signing: XCTestAgentBuildSigning | undefined;
 
     if (target.kind === 'device') {
@@ -924,6 +996,7 @@ export const createXCTestAgentController = (options: {
     });
 
     preparedDerivedDataPath = buildResult.derivedDataPath;
+    preparedXCTestRunFilePath = null;
     prepared = true;
   };
 
@@ -943,12 +1016,18 @@ export const createXCTestAgentController = (options: {
       target.kind
     );
     xctestAgentLogger.debug('Using XCTest agent port %d', port);
+    const xcodebuildRunInputArgs = preparedXCTestRunFilePath
+      ? ['-xctestrun', preparedXCTestRunFilePath]
+      : [
+          '-project',
+          getXCTestAgentProjectFilePath(),
+          '-scheme',
+          XCTEST_AGENT_SCHEME_NAME,
+        ];
+
     const xcodebuildArgs = [
       'test-without-building',
-      '-project',
-      getXCTestAgentProjectFilePath(),
-      '-scheme',
-      XCTEST_AGENT_SCHEME_NAME,
+      ...xcodebuildRunInputArgs,
       '-destination',
       getXCTestAgentRunDestination(target),
       '-parallel-testing-enabled',