@react-native-harness/config 1.5.0 → 1.7.0

package/dist/cli-options.d.ts

@@ -0,0 +1,14 @@
+export declare const harnessCliOptions: {
+    readonly harnessRunner: {
+        readonly type: "string";
+        readonly description: "Specify which Harness runner to use";
+        readonly requiresArg: true;
+    };
+    readonly metroPort: {
+        readonly type: "number";
+        readonly description: "Set the preferred Metro port for this run";
+        readonly requiresArg: true;
+        readonly coerce: (value: unknown) => number;
+    };
+};
+//# sourceMappingURL=cli-options.d.ts.map

package/dist/cli-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-options.d.ts","sourceRoot":"","sources":["../src/cli-options.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,iBAAiB;;;;;;;;;;iCAWV,OAAO,KAAG,MAAM;;CAU1B,CAAC"}

package/dist/cli-options.js

@@ -0,0 +1,24 @@
+import { MetroPortSchema } from './types.js';
+// The options Harness adds to Jest's command line. The CLI registers them with
+// Jest's argument parser and the Jest integration reads them back, so an option
+// listed here is both accepted and read.
+export const harnessCliOptions = {
+    harnessRunner: {
+        type: 'string',
+        description: 'Specify which Harness runner to use',
+        requiresArg: true,
+    },
+    metroPort: {
+        type: 'number',
+        description: 'Set the preferred Metro port for this run',
+        requiresArg: true,
+        // Rejects a port the config would reject, before Jest starts any work.
+        coerce: (value) => {
+            const result = MetroPortSchema.safeParse(value);
+            if (!result.success) {
+                throw new Error(`Invalid --metroPort: ${result.error.issues[0]?.message}`);
+            }
+            return result.data;
+        },
+    },
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { getConfig } from './reader.js';
-export type { Config } from './types.js';
-export { ConfigSchema, DEFAULT_METRO_PORT, isDiagnosticsEnabled, resolveMetroCacheEnabled, resolveSkipAlreadyIncludedModules, } from './types.js';
+export { harnessCliOptions } from './cli-options.js';
+export type { Config, ResolvedDiagnosticsOptions } from './types.js';
+export { ConfigSchema, DEFAULT_METRO_PORT, isDiagnosticsEnabled, resolveDiagnosticsOptions, resolveMetroCacheEnabled, resolveSkipAlreadyIncludedModules, } from './types.js';
 export { ConfigValidationError, ConfigNotFoundError, ConfigLoadError, } from './errors.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,iCAAiC,GAClC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,MAAM,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACxB,iCAAiC,GAClC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { getConfig } from './reader.js';
-export { ConfigSchema, DEFAULT_METRO_PORT, isDiagnosticsEnabled, resolveMetroCacheEnabled, resolveSkipAlreadyIncludedModules, } from './types.js';
+export { harnessCliOptions } from './cli-options.js';
+export { ConfigSchema, DEFAULT_METRO_PORT, isDiagnosticsEnabled, resolveDiagnosticsOptions, resolveMetroCacheEnabled, resolveSkipAlreadyIncludedModules, } from './types.js';
 export { ConfigValidationError, ConfigNotFoundError, ConfigLoadError, } from './errors.js';

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import type { HarnessPlugin } from '@react-native-harness/plugins';
 export declare const DEFAULT_METRO_PORT = 8081;
 type AnyHarnessPlugin = HarnessPlugin<object, unknown>;
+export declare const MetroPortSchema: z.ZodNumber;
 export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
     entryPoint: z.ZodString;
     appRegistryComponentName: z.ZodString;
@@ -11,8 +12,10 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         runner: z.ZodString;
         cli: z.ZodOptional<z.ZodString>;
         metroConfigEnhancer: z.ZodOptional<z.ZodString>;
+        bundlePlatform: z.ZodOptional<z.ZodString>;
         platformId: z.ZodString;
         getResourceLockKey: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnion<[z.ZodString, z.ZodPromise<z.ZodString>]>>>;
+        deferMetroPrewarm: z.ZodOptional<z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodBoolean>>;
     }, "strip", z.ZodTypeAny, {
         config: Record<string, any>;
         name: string;
@@ -20,7 +23,9 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         platformId: string;
         cli?: string | undefined;
         metroConfigEnhancer?: string | undefined;
+        bundlePlatform?: string | undefined;
         getResourceLockKey?: ((...args: unknown[]) => string | Promise<string>) | undefined;
+        deferMetroPrewarm?: ((...args: unknown[]) => boolean) | undefined;
     }, {
         config: Record<string, any>;
         name: string;
@@ -28,7 +33,9 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         platformId: string;
         cli?: string | undefined;
         metroConfigEnhancer?: string | undefined;
+        bundlePlatform?: string | undefined;
         getResourceLockKey?: ((...args: unknown[]) => string | Promise<string>) | undefined;
+        deferMetroPrewarm?: ((...args: unknown[]) => boolean) | undefined;
     }>, "many">;
     plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodType<AnyHarnessPlugin, z.ZodTypeDef, AnyHarnessPlugin>, "many">>>;
     defaultRunner: z.ZodOptional<z.ZodString>;
@@ -94,7 +101,44 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
     }>>;
     forwardClientLogs: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    diagnostics: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    diagnostics: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        probes: z.ZodOptional<z.ZodObject<{
+            host: z.ZodOptional<z.ZodBoolean>;
+            node: z.ZodOptional<z.ZodBoolean>;
+            snapshots: z.ZodOptional<z.ZodBoolean>;
+            platform: z.ZodOptional<z.ZodBoolean>;
+        }, "strict", z.ZodTypeAny, {
+            host?: boolean | undefined;
+            node?: boolean | undefined;
+            snapshots?: boolean | undefined;
+            platform?: boolean | undefined;
+        }, {
+            host?: boolean | undefined;
+            node?: boolean | undefined;
+            snapshots?: boolean | undefined;
+            platform?: boolean | undefined;
+        }>>;
+        sampleIntervalMs: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        probes?: {
+            host?: boolean | undefined;
+            node?: boolean | undefined;
+            snapshots?: boolean | undefined;
+            platform?: boolean | undefined;
+        } | undefined;
+        sampleIntervalMs?: number | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        probes?: {
+            host?: boolean | undefined;
+            node?: boolean | undefined;
+            snapshots?: boolean | undefined;
+            platform?: boolean | undefined;
+        } | undefined;
+        sampleIntervalMs?: number | undefined;
+    }>]>>>;
     include: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     entryPoint: string;
@@ -106,7 +150,9 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         platformId: string;
         cli?: string | undefined;
         metroConfigEnhancer?: string | undefined;
+        bundlePlatform?: string | undefined;
         getResourceLockKey?: ((...args: unknown[]) => string | Promise<string>) | undefined;
+        deferMetroPrewarm?: ((...args: unknown[]) => boolean) | undefined;
     }[];
     plugins: AnyHarnessPlugin[];
     metroPort: number;
@@ -122,7 +168,16 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
     crashDetectionInterval: number;
     disableViewFlattening: boolean;
     forwardClientLogs: boolean;
-    diagnostics: boolean;
+    diagnostics: boolean | {
+        enabled?: boolean | undefined;
+        probes?: {
+            host?: boolean | undefined;
+            node?: boolean | undefined;
+            snapshots?: boolean | undefined;
+            platform?: boolean | undefined;
+        } | undefined;
+        sampleIntervalMs?: number | undefined;
+    };
     defaultRunner?: string | undefined;
     host?: string | undefined;
     webSocketPort?: number | undefined;
@@ -152,7 +207,9 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         platformId: string;
         cli?: string | undefined;
         metroConfigEnhancer?: string | undefined;
+        bundlePlatform?: string | undefined;
         getResourceLockKey?: ((...args: unknown[]) => string | Promise<string>) | undefined;
+        deferMetroPrewarm?: ((...args: unknown[]) => boolean) | undefined;
     }[];
     plugins?: AnyHarnessPlugin[] | undefined;
     defaultRunner?: string | undefined;
@@ -186,7 +243,16 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
     } | undefined;
     forwardClientLogs?: boolean | undefined;
-    diagnostics?: boolean | undefined;
+    diagnostics?: boolean | {
+        enabled?: boolean | undefined;
+        probes?: {
+            host?: boolean | undefined;
+            node?: boolean | undefined;
+            snapshots?: boolean | undefined;
+            platform?: boolean | undefined;
+        } | undefined;
+        sampleIntervalMs?: number | undefined;
+    } | undefined;
     include?: string[] | undefined;
 }>, {
     entryPoint: string;
@@ -198,7 +264,9 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         platformId: string;
         cli?: string | undefined;
         metroConfigEnhancer?: string | undefined;
+        bundlePlatform?: string | undefined;
         getResourceLockKey?: ((...args: unknown[]) => string | Promise<string>) | undefined;
+        deferMetroPrewarm?: ((...args: unknown[]) => boolean) | undefined;
     }[];
     plugins: AnyHarnessPlugin[];
     metroPort: number;
@@ -214,7 +282,16 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
     crashDetectionInterval: number;
     disableViewFlattening: boolean;
     forwardClientLogs: boolean;
-    diagnostics: boolean;
+    diagnostics: boolean | {
+        enabled?: boolean | undefined;
+        probes?: {
+            host?: boolean | undefined;
+            node?: boolean | undefined;
+            snapshots?: boolean | undefined;
+            platform?: boolean | undefined;
+        } | undefined;
+        sampleIntervalMs?: number | undefined;
+    };
     defaultRunner?: string | undefined;
     host?: string | undefined;
     webSocketPort?: number | undefined;
@@ -244,7 +321,9 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         platformId: string;
         cli?: string | undefined;
         metroConfigEnhancer?: string | undefined;
+        bundlePlatform?: string | undefined;
         getResourceLockKey?: ((...args: unknown[]) => string | Promise<string>) | undefined;
+        deferMetroPrewarm?: ((...args: unknown[]) => boolean) | undefined;
     }[];
     plugins?: AnyHarnessPlugin[] | undefined;
     defaultRunner?: string | undefined;
@@ -278,16 +357,42 @@ export declare const ConfigSchema: z.ZodEffects<z.ZodObject<{
         } | undefined;
     } | undefined;
     forwardClientLogs?: boolean | undefined;
-    diagnostics?: boolean | undefined;
+    diagnostics?: boolean | {
+        enabled?: boolean | undefined;
+        probes?: {
+            host?: boolean | undefined;
+            node?: boolean | undefined;
+            snapshots?: boolean | undefined;
+            platform?: boolean | undefined;
+        } | undefined;
+        sampleIntervalMs?: number | undefined;
+    } | undefined;
     include?: string[] | undefined;
 }>;
 export type Config = z.infer<typeof ConfigSchema>;
 /**
  * Resolves whether diagnostics tracing is enabled: either explicitly via the
- * `diagnostics` config option, or via the `RN_HARNESS_DIAGNOSTICS` environment
- * variable (any value other than unset, `''`, `'0'`, or `'false'`).
+ * `diagnostics` config option (`true`, or an object that does not set
+ * `enabled: false`), or via the `RN_HARNESS_DIAGNOSTICS` environment variable
+ * (any value other than unset, `''`, `'0'`, or `'false'`).
  */
 export declare const isDiagnosticsEnabled: (config: Pick<Config, "diagnostics"> | undefined, env?: NodeJS.ProcessEnv) => boolean;
+export type ResolvedDiagnosticsOptions = {
+    probes: {
+        host: boolean;
+        node: boolean;
+        snapshots: boolean;
+        platform: boolean;
+    };
+    /** Undefined means "use the default sampling interval". */
+    sampleIntervalMs: number | undefined;
+};
+/**
+ * Resolves the diagnostics tuning options. Every probe is on unless the object
+ * form of `diagnostics` switches it off, which is also what the boolean form
+ * and the `RN_HARNESS_DIAGNOSTICS` environment variable mean.
+ */
+export declare const resolveDiagnosticsOptions: (config: Pick<Config, "diagnostics"> | undefined) => ResolvedDiagnosticsOptions;
 /**
  * Resolves the effective value of `skipAlreadyIncludedModules`, reconciling
  * it with the deprecated `unstable__skipAlreadyIncludedModules` alias:

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAInE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AA+BvC,KAAK,gBAAgB,GAAG,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAOvD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8MtB,CAAC;AAEJ,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,EAC/C,MAAK,MAAM,CAAC,UAAwB,KACnC,OAOF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iCAAiC,GAC5C,QAAQ,IAAI,CACV,MAAM,EACN,4BAA4B,GAAG,sCAAsC,CACtE,KACA,OAiBF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,GACnC,QAAQ,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,4BAA4B,CAAC,KAC3D,OAiBF,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAInE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAqCvC,KAAK,gBAAgB,GAAG,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAOvD,eAAO,MAAM,eAAe,aAIqB,CAAC;AAElD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4PtB,CAAC;AAEJ,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,EAC/C,MAAK,MAAM,CAAC,UAAwB,KACnC,OAWF,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE;QACN,IAAI,EAAE,OAAO,CAAC;QACd,IAAI,EAAE,OAAO,CAAC;QACd,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,KAC9C,0BAaF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iCAAiC,GAC5C,QAAQ,IAAI,CACV,MAAM,EACN,4BAA4B,GAAG,sCAAsC,CACtE,KACA,OAiBF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,GACnC,QAAQ,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,4BAA4B,CAAC,KAC3D,OAiBF,CAAC"}

package/dist/types.js

@@ -15,6 +15,9 @@ const RunnerSchema = z.object({
     // runner. Set by a platform factory (`HarnessPlatform.metroConfigEnhancer`);
     // imported and run by the bundler while it composes the config.
     metroConfigEnhancer: z.string().optional(),
+    // The Metro platform the app requests when it differs from platformId
+    // (e.g. Vega apps request "kepler"). Set by the platform factory.
+    bundlePlatform: z.string().optional(),
     platformId: z.string(),
     // Set by the platform factories (`HarnessPlatform.getResourceLockKey`) to
     // scope the run's resource lock — e.g. per emulator/simulator/device rather
@@ -25,8 +28,16 @@ const RunnerSchema = z.object({
         .args()
         .returns(z.union([z.string(), z.promise(z.string())]))
         .optional(),
+    // Set by platform factories (`HarnessPlatform.deferMetroPrewarm`) to start
+    // the Metro prewarm only after the platform is ready on small hosts.
+    deferMetroPrewarm: z.function().args().returns(z.boolean()).optional(),
 });
 const PluginSchema = z.custom((value) => isHarnessPlugin(value), 'Invalid Harness plugin');
+export const MetroPortSchema = z
+    .number()
+    .int('Metro port must be an integer')
+    .min(1, 'Metro port must be at least 1')
+    .max(65535, 'Metro port must be at most 65535');
 export const ConfigSchema = z
     .object({
     entryPoint: z.string().min(1, 'Entry point is required'),
@@ -37,13 +48,7 @@ export const ConfigSchema = z
     plugins: z.array(PluginSchema).optional().default([]),
     defaultRunner: z.string().optional(),
     host: z.string().min(1, 'Host is required').optional(),
-    metroPort: z
-        .number()
-        .int('Metro port must be an integer')
-        .min(1, 'Metro port must be at least 1')
-        .max(65535, 'Metro port must be at most 65535')
-        .optional()
-        .default(DEFAULT_METRO_PORT),
+    metroPort: MetroPortSchema.optional().default(DEFAULT_METRO_PORT),
     webSocketPort: z
         .number()
         .optional()
@@ -174,13 +179,53 @@ export const ConfigSchema = z
         .describe('Enable forwarding of console.log, console.warn, console.error, and other console method calls from the React Native app during the active test run. ' +
         "When enabled, app console output is attached to the active test result's console output."),
     diagnostics: z
-        .boolean()
+        .union([
+        z.boolean(),
+        z
+            .object({
+            enabled: z
+                .boolean()
+                .optional()
+                .describe('Turns diagnostics on or off. Defaults to true when the object form is used.'),
+            probes: z
+                .object({
+                host: z
+                    .boolean()
+                    .optional()
+                    .describe('Sample host load, CPU split and memory pressure. Defaults to true.'),
+                node: z
+                    .boolean()
+                    .optional()
+                    .describe('Sample Harness process memory and event loop lag. Defaults to true.'),
+                snapshots: z
+                    .boolean()
+                    .optional()
+                    .describe('Record a process listing at run milestones (macOS). Defaults to true.'),
+                platform: z
+                    .boolean()
+                    .optional()
+                    .describe('Record platform specific measurements, such as the process count inside an iOS simulator. Defaults to true.'),
+            })
+                .strict()
+                .optional(),
+            sampleIntervalMs: z
+                .number()
+                .int()
+                .min(250, 'sampleIntervalMs must be at least 250')
+                .optional()
+                .describe('How often host and process metrics are sampled, in milliseconds. Defaults to 5000.'),
+        })
+            .strict(),
+    ])
         .optional()
         .default(false)
-        .describe('Enable diagnostics tracing for the harness session. Records spans for ' +
-        'session setup, Metro bundling, bridge/client events, and per-file test runs, ' +
-        'then writes a Chrome Trace Event JSON file and prints a summary after each run. ' +
-        'Can also be enabled via the RN_HARNESS_DIAGNOSTICS environment variable.'),
+        .describe('Enable diagnostics for the harness session. Records spans for session ' +
+        'setup, Metro bundling, bridge/client events, and per-file test runs, ' +
+        'samples host and process resource metrics, then writes a Chrome Trace ' +
+        'Event JSON file, an incremental JSONL log and a KPI summary, and prints ' +
+        'a summary after each run. Pass an object to tune the probes and the ' +
+        'sampling interval. Can also be enabled via the RN_HARNESS_DIAGNOSTICS ' +
+        'environment variable.'),
     // Deprecated property - used for migration detection
     include: z.array(z.string()).optional(),
 })
@@ -195,16 +240,39 @@ export const ConfigSchema = z
 });
 /**
  * Resolves whether diagnostics tracing is enabled: either explicitly via the
- * `diagnostics` config option, or via the `RN_HARNESS_DIAGNOSTICS` environment
- * variable (any value other than unset, `''`, `'0'`, or `'false'`).
+ * `diagnostics` config option (`true`, or an object that does not set
+ * `enabled: false`), or via the `RN_HARNESS_DIAGNOSTICS` environment variable
+ * (any value other than unset, `''`, `'0'`, or `'false'`).
  */
 export const isDiagnosticsEnabled = (config, env = process.env) => {
-    if (config?.diagnostics === true) {
+    const diagnostics = config?.diagnostics;
+    if (diagnostics === true) {
+        return true;
+    }
+    if (typeof diagnostics === 'object' && diagnostics.enabled !== false) {
         return true;
     }
     const envValue = env.RN_HARNESS_DIAGNOSTICS;
     return !!envValue && envValue !== '0' && envValue !== 'false';
 };
+/**
+ * Resolves the diagnostics tuning options. Every probe is on unless the object
+ * form of `diagnostics` switches it off, which is also what the boolean form
+ * and the `RN_HARNESS_DIAGNOSTICS` environment variable mean.
+ */
+export const resolveDiagnosticsOptions = (config) => {
+    const diagnostics = config?.diagnostics;
+    const options = typeof diagnostics === 'object' ? diagnostics : undefined;
+    return {
+        probes: {
+            host: options?.probes?.host ?? true,
+            node: options?.probes?.node ?? true,
+            snapshots: options?.probes?.snapshots ?? true,
+            platform: options?.probes?.platform ?? true,
+        },
+        sampleIntervalMs: options?.sampleIntervalMs,
+    };
+};
 /**
  * Resolves the effective value of `skipAlreadyIncludedModules`, reconciling
  * it with the deprecated `unstable__skipAlreadyIncludedModules` alias:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-harness/config",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -17,8 +17,8 @@
   "dependencies": {
     "tslib": "^2.3.0",
     "zod": "^3.25.67",
-    "@react-native-harness/tools": "1.5.0",
-    "@react-native-harness/plugins": "1.5.0"
+    "@react-native-harness/plugins": "1.7.0",
+    "@react-native-harness/tools": "1.7.0"
   },
   "license": "MIT"
 }

package/src/cli-options.ts

@@ -0,0 +1,27 @@
+import { MetroPortSchema } from './types.js';
+
+// The options Harness adds to Jest's command line. The CLI registers them with
+// Jest's argument parser and the Jest integration reads them back, so an option
+// listed here is both accepted and read.
+export const harnessCliOptions = {
+  harnessRunner: {
+    type: 'string',
+    description: 'Specify which Harness runner to use',
+    requiresArg: true,
+  },
+  metroPort: {
+    type: 'number',
+    description: 'Set the preferred Metro port for this run',
+    requiresArg: true,
+    // Rejects a port the config would reject, before Jest starts any work.
+    coerce: (value: unknown): number => {
+      const result = MetroPortSchema.safeParse(value);
+      if (!result.success) {
+        throw new Error(
+          `Invalid --metroPort: ${result.error.issues[0]?.message}`
+        );
+      }
+      return result.data;
+    },
+  },
+} as const;

package/src/index.ts

@@ -1,9 +1,11 @@
 export { getConfig } from './reader.js';
-export type { Config } from './types.js';
+export { harnessCliOptions } from './cli-options.js';
+export type { Config, ResolvedDiagnosticsOptions } from './types.js';
 export {
   ConfigSchema,
   DEFAULT_METRO_PORT,
   isDiagnosticsEnabled,
+  resolveDiagnosticsOptions,
   resolveMetroCacheEnabled,
   resolveSkipAlreadyIncludedModules,
 } from './types.js';

package/src/types.ts

@@ -22,6 +22,9 @@ const RunnerSchema = z.object({
   // runner. Set by a platform factory (`HarnessPlatform.metroConfigEnhancer`);
   // imported and run by the bundler while it composes the config.
   metroConfigEnhancer: z.string().optional(),
+  // The Metro platform the app requests when it differs from platformId
+  // (e.g. Vega apps request "kepler"). Set by the platform factory.
+  bundlePlatform: z.string().optional(),
   platformId: z.string(),
   // Set by the platform factories (`HarnessPlatform.getResourceLockKey`) to
   // scope the run's resource lock — e.g. per emulator/simulator/device rather
@@ -32,6 +35,9 @@ const RunnerSchema = z.object({
     .args()
     .returns(z.union([z.string(), z.promise(z.string())]))
     .optional(),
+  // Set by platform factories (`HarnessPlatform.deferMetroPrewarm`) to start
+  // the Metro prewarm only after the platform is ready on small hosts.
+  deferMetroPrewarm: z.function().args().returns(z.boolean()).optional(),
 });
 
 type AnyHarnessPlugin = HarnessPlugin<object, unknown>;
@@ -41,6 +47,12 @@ const PluginSchema = z.custom<AnyHarnessPlugin>(
   'Invalid Harness plugin'
 );
 
+export const MetroPortSchema = z
+  .number()
+  .int('Metro port must be an integer')
+  .min(1, 'Metro port must be at least 1')
+  .max(65535, 'Metro port must be at most 65535');
+
 export const ConfigSchema = z
   .object({
     entryPoint: z.string().min(1, 'Entry point is required'),
@@ -51,13 +63,7 @@ export const ConfigSchema = z
     plugins: z.array(PluginSchema).optional().default([]),
     defaultRunner: z.string().optional(),
     host: z.string().min(1, 'Host is required').optional(),
-    metroPort: z
-      .number()
-      .int('Metro port must be an integer')
-      .min(1, 'Metro port must be at least 1')
-      .max(65535, 'Metro port must be at most 65535')
-      .optional()
-      .default(DEFAULT_METRO_PORT),
+    metroPort: MetroPortSchema.optional().default(DEFAULT_METRO_PORT),
     webSocketPort: z
       .number()
       .optional()
@@ -221,14 +227,66 @@ export const ConfigSchema = z
       ),
 
     diagnostics: z
-      .boolean()
+      .union([
+        z.boolean(),
+        z
+          .object({
+            enabled: z
+              .boolean()
+              .optional()
+              .describe(
+                'Turns diagnostics on or off. Defaults to true when the object form is used.'
+              ),
+            probes: z
+              .object({
+                host: z
+                  .boolean()
+                  .optional()
+                  .describe(
+                    'Sample host load, CPU split and memory pressure. Defaults to true.'
+                  ),
+                node: z
+                  .boolean()
+                  .optional()
+                  .describe(
+                    'Sample Harness process memory and event loop lag. Defaults to true.'
+                  ),
+                snapshots: z
+                  .boolean()
+                  .optional()
+                  .describe(
+                    'Record a process listing at run milestones (macOS). Defaults to true.'
+                  ),
+                platform: z
+                  .boolean()
+                  .optional()
+                  .describe(
+                    'Record platform specific measurements, such as the process count inside an iOS simulator. Defaults to true.'
+                  ),
+              })
+              .strict()
+              .optional(),
+            sampleIntervalMs: z
+              .number()
+              .int()
+              .min(250, 'sampleIntervalMs must be at least 250')
+              .optional()
+              .describe(
+                'How often host and process metrics are sampled, in milliseconds. Defaults to 5000.'
+              ),
+          })
+          .strict(),
+      ])
       .optional()
       .default(false)
       .describe(
-        'Enable diagnostics tracing for the harness session. Records spans for ' +
-          'session setup, Metro bundling, bridge/client events, and per-file test runs, ' +
-          'then writes a Chrome Trace Event JSON file and prints a summary after each run. ' +
-          'Can also be enabled via the RN_HARNESS_DIAGNOSTICS environment variable.'
+        'Enable diagnostics for the harness session. Records spans for session ' +
+          'setup, Metro bundling, bridge/client events, and per-file test runs, ' +
+          'samples host and process resource metrics, then writes a Chrome Trace ' +
+          'Event JSON file, an incremental JSONL log and a KPI summary, and prints ' +
+          'a summary after each run. Pass an object to tune the probes and the ' +
+          'sampling interval. Can also be enabled via the RN_HARNESS_DIAGNOSTICS ' +
+          'environment variable.'
       ),
 
     // Deprecated property - used for migration detection
@@ -253,14 +311,19 @@ export type Config = z.infer<typeof ConfigSchema>;
 
 /**
  * Resolves whether diagnostics tracing is enabled: either explicitly via the
- * `diagnostics` config option, or via the `RN_HARNESS_DIAGNOSTICS` environment
- * variable (any value other than unset, `''`, `'0'`, or `'false'`).
+ * `diagnostics` config option (`true`, or an object that does not set
+ * `enabled: false`), or via the `RN_HARNESS_DIAGNOSTICS` environment variable
+ * (any value other than unset, `''`, `'0'`, or `'false'`).
  */
 export const isDiagnosticsEnabled = (
   config: Pick<Config, 'diagnostics'> | undefined,
   env: NodeJS.ProcessEnv = process.env
 ): boolean => {
-  if (config?.diagnostics === true) {
+  const diagnostics = config?.diagnostics;
+  if (diagnostics === true) {
+    return true;
+  }
+  if (typeof diagnostics === 'object' && diagnostics.enabled !== false) {
     return true;
   }
 
@@ -268,6 +331,39 @@ export const isDiagnosticsEnabled = (
   return !!envValue && envValue !== '0' && envValue !== 'false';
 };
 
+export type ResolvedDiagnosticsOptions = {
+  probes: {
+    host: boolean;
+    node: boolean;
+    snapshots: boolean;
+    platform: boolean;
+  };
+  /** Undefined means "use the default sampling interval". */
+  sampleIntervalMs: number | undefined;
+};
+
+/**
+ * Resolves the diagnostics tuning options. Every probe is on unless the object
+ * form of `diagnostics` switches it off, which is also what the boolean form
+ * and the `RN_HARNESS_DIAGNOSTICS` environment variable mean.
+ */
+export const resolveDiagnosticsOptions = (
+  config: Pick<Config, 'diagnostics'> | undefined
+): ResolvedDiagnosticsOptions => {
+  const diagnostics = config?.diagnostics;
+  const options = typeof diagnostics === 'object' ? diagnostics : undefined;
+
+  return {
+    probes: {
+      host: options?.probes?.host ?? true,
+      node: options?.probes?.node ?? true,
+      snapshots: options?.probes?.snapshots ?? true,
+      platform: options?.probes?.platform ?? true,
+    },
+    sampleIntervalMs: options?.sampleIntervalMs,
+  };
+};
+
 /**
  * Resolves the effective value of `skipAlreadyIncludedModules`, reconciling
  * it with the deprecated `unstable__skipAlreadyIncludedModules` alias: