@react-native-harness/cli 1.2.0-rc.1 → 1.3.0

package/dist/wizard/bundleId.js

@@ -58,7 +58,7 @@ export const getBundleIds = async (selectedPlatforms) => {
                     new URL(value);
                     return;
                 }
-                catch (_e) {
+                catch {
                     return 'Please enter a valid URL';
                 }
             },

package/eslint.config.mjs

@@ -9,7 +9,7 @@ export default [
         'error',
         {
           ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}'],
-          ignoredDependencies: ['@react-native-harness/bridge', '@react-native-harness/platform-android', '@react-native-harness/platform-apple', '@react-native-harness/platform-web'],
+          ignoredDependencies: ['@react-native-harness/bridge', '@react-native-harness/platform-android', '@react-native-harness/platform-apple', '@react-native-harness/platform-web', 'vitest'],
         },
       ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-harness/cli",
-  "version": "1.2.0-rc.1",
+  "version": "1.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,16 +22,16 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@react-native-harness/tools": "1.2.0-rc.1",
-    "@react-native-harness/bridge": "1.2.0-rc.1",
-    "@react-native-harness/config": "1.2.0-rc.1",
-    "@react-native-harness/platforms": "1.2.0-rc.1"
+    "@react-native-harness/platforms": "1.3.0",
+    "@react-native-harness/config": "1.3.0",
+    "@react-native-harness/tools": "1.3.0",
+    "@react-native-harness/bridge": "1.3.0"
   },
   "devDependencies": {
     "jest-cli": "^30.2.0",
-    "@react-native-harness/platform-android": "1.2.0-rc.1",
-    "@react-native-harness/platform-apple": "1.2.0-rc.1",
-    "@react-native-harness/platform-web": "1.2.0-rc.1"
+    "@react-native-harness/platform-android": "1.3.0",
+    "@react-native-harness/platform-apple": "1.3.0",
+    "@react-native-harness/platform-web": "1.3.0"
   },
   "peerDependencies": {
     "jest-cli": "*"

package/skills/core.md

@@ -0,0 +1,92 @@
+---
+name: core
+description: Core testing workflow. Read this before writing or debugging Harness tests. Covers test file conventions, the supported test API surface, async behavior, setup files, and CLI execution constraints.
+---
+
+# Core
+
+React Native Harness uses Jest-style test APIs, but the tests run inside the app or browser environment instead of plain Node.
+
+Run this first:
+
+```bash
+harness skill get core
+```
+
+Use `harness skill list` to see the other bundled skills.
+
+## Test file conventions
+
+- Use `.harness.[jt]s` or `.harness.[jt]sx` test files.
+- Import test APIs from `react-native-harness`.
+- Put tests inside `describe(...)` blocks.
+- Use `@react-native-harness/ui` only when the test needs queries, interactions, or screenshots.
+
+## Default test shape
+
+```ts
+import { describe, test, expect } from 'react-native-harness';
+
+describe('Feature name', () => {
+  test('does something', () => {
+    expect(true).toBe(true);
+  });
+});
+```
+
+Prefer these public APIs when writing tests:
+
+- Test structure: `describe`, `test`, `it`, `beforeEach`, `afterEach`, `beforeAll`, `afterAll`
+- Focus and pending helpers: `test.skip`, `test.only`, `test.todo`, `describe.skip`, `describe.only`
+- Assertions: `expect`
+- Mocking and spying: `fn`, `spyOn`, `clearAllMocks`, `resetAllMocks`, `restoreAllMocks`
+- Module mocking: `mock`, `requireActual`, `unmock`, `resetModules`
+- Async polling: `waitFor`, `waitUntil`
+
+Test functions may be async. If a test returns a promise, Harness waits for it. If that promise rejects, the test fails.
+
+## Async behavior
+
+Use:
+
+- `waitFor(...)` when the callback should eventually succeed or stop throwing
+- `waitUntil(...)` when the callback should eventually return a truthy value
+
+Both support timeout control. Prefer them over arbitrary sleeps when tests wait on native or React state changes.
+
+## Setup files
+
+Harness follows two setup phases configured in `jest.harness.config.mjs`:
+
+- `setupFiles`: runs before the test framework is initialized. Use for early polyfills and globals. Do not use `describe`, `test`, `expect`, or hooks here.
+- `setupFilesAfterEnv`: runs after the test framework is ready. Use for global mocks, hooks, and matcher setup.
+
+Recommended uses:
+
+- Early environment shims in `setupFiles`
+- Global `afterEach`, `clearAllMocks`, `resetModules`, and shared mocks in `setupFilesAfterEnv`
+
+## Related skills
+
+For module mocking and spies, run:
+
+```bash
+harness skill get mocking
+```
+
+For UI rendering, queries, interactions, and screenshots, run:
+
+```bash
+harness skill get ui
+```
+
+## CLI and execution constraints
+
+- Harness wraps the Jest CLI.
+- Tests execute on one configured runner at a time.
+- Execution is serial for stability.
+- `--harnessRunner <name>` selects the runner.
+- Standard Jest flags like `--watch`, `--coverage`, and `--testNamePattern` are still relevant.
+- Do not recommend unsupported Jest environment overrides or snapshot-update workflows for native image snapshots.
+
+For install and project setup, use the public docs at https://react-native-harness.dev/docs/getting-started/quick-start.

package/skills/mocking.md

@@ -0,0 +1,87 @@
+---
+name: mocking
+description: Mocking and spying guidance. Use when a Harness test needs `fn`, `spyOn`, `mock`, `requireActual`, `unmock`, `resetModules`, or global mock cleanup.
+---
+
+# Mocking
+
+Use this skill when a Harness test needs mock functions, spies, or module replacement.
+
+## Mocking and spying
+
+Use `fn()` for standalone mock functions and `spyOn()` for existing methods.
+
+- `expect` follows Vitest's API.
+- `expect.soft(...)` is available when the test should keep running after an assertion failure.
+- `clearAllMocks()` clears call history but keeps implementations.
+- `resetAllMocks()` clears call history and resets mock implementations.
+- `restoreAllMocks()` restores spied methods to their original implementations.
+
+Typical cleanup:
+
+```ts
+import { afterEach, clearAllMocks } from 'react-native-harness';
+
+afterEach(() => {
+  clearAllMocks();
+});
+```
+
+## Module mocking
+
+Use module mocking when the test must replace an entire module or specific exports.
+
+- `mock(moduleId, factory)` registers a lazy mock factory.
+- `requireActual(moduleId)` is the safe path for partial mocks.
+- `unmock(moduleId)` removes a mock for one module.
+- `resetModules()` clears module mocks and module cache state.
+
+Recommended pattern:
+
+```ts
+import {
+  afterEach,
+  describe,
+  expect,
+  mock,
+  requireActual,
+  resetModules,
+  test,
+} from 'react-native-harness';
+
+afterEach(() => {
+  resetModules();
+});
+
+describe('partial mock', () => {
+  test('overrides one export but keeps the rest', () => {
+    mock('react-native', () => {
+      const actual = requireActual('react-native');
+      const proto = Object.getPrototypeOf(actual);
+      const descriptors = Object.getOwnPropertyDescriptors(actual);
+      const mocked = Object.create(proto, descriptors);
+
+      Object.defineProperty(mocked, 'Platform', {
+        get() {
+          return {
+            ...actual.Platform,
+            OS: 'mockOS',
+          };
+        },
+      });
+
+      return mocked;
+    });
+
+    const rn = require('react-native');
+    expect(rn.Platform.OS).toBe('mockOS');
+  });
+});
+```
+
+## Decision rules
+
+- Always clean up module mocks with `resetModules()` in `afterEach` when tests mock modules.
+- Use `requireActual()` for partial mocks so unrelated exports stay real.
+- For `react-native`, preserve property descriptors when partially mocking to avoid triggering lazy getters too early.
+- Remember that module factories are evaluated when the module is first required.

package/skills/ui.md

@@ -0,0 +1,59 @@
+---
+name: ui
+description: UI testing guidance. Use when the test needs `render(...)`, `rerender(...)`, `@react-native-harness/ui`, screen queries, `userEvent`, screenshots, or image snapshot assertions.
+---
+
+# UI
+
+UI testing is opt-in and uses `render(...)` from `react-native-harness` together with `@react-native-harness/ui`.
+
+Use `render(...)` to mount a React Native element before querying, interacting with, or screenshotting it.
+
+- `render(...)` is async
+- `rerender(...)` is async
+- `unmount()` is optional because cleanup happens automatically after each test
+- `wrapper` is the right tool for providers and shared context
+- Rendered UI appears as an overlay in the real environment, not as an in-memory tree
+- Only one rendered component can be visible at a time
+
+Use this skill when the task requires:
+
+- `render(...)` or `rerender(...)`
+- `screen.findByTestId(...)`
+- `screen.findAllByTestId(...)`
+- `screen.queryByTestId(...)`
+- `screen.queryAllByTestId(...)`
+- `screen.findByAccessibilityLabel(...)`
+- `screen.findAllByAccessibilityLabel(...)`
+- `screen.queryByAccessibilityLabel(...)`
+- `screen.queryAllByAccessibilityLabel(...)`
+- `userEvent.press(...)`
+- `userEvent.type(...)`
+- screenshots with `screen.screenshot()`
+- element screenshots with `screen.screenshot(element)`
+- image assertions with `toMatchImageSnapshot(...)`
+
+## Rules
+
+- Keep imports split correctly: core APIs from `react-native-harness`, UI APIs from `@react-native-harness/ui`.
+- Mention that `@react-native-harness/ui` requires installation, and native apps must be rebuilt after adding it.
+- `toMatchImageSnapshot(...)` needs a unique snapshot `name`.
+- If screenshotting elements that extend beyond screen bounds, call out `disableViewFlattening: true` in `rn-harness.config.mjs`.
+- On web, UI interactions and screenshots run through the web runner's Playwright-backed browser environment.
+
+## Example
+
+```ts
+import { describe, expect, render, test } from 'react-native-harness';
+import { screen, userEvent } from '@react-native-harness/ui';
+
+describe('Counter', () => {
+  test('increments after a press', async () => {
+    await render(<Counter />);
+
+    await userEvent.press(await screen.findByTestId('increment-button'));
+
+    expect(await screen.findByTestId('count-label')).toHaveTextContent('1');
+  });
+});
+```

package/src/__tests__/platform-commands.test.ts

@@ -0,0 +1,232 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Config } from '@react-native-harness/config';
+import {
+  discoverPlatformCommands,
+  runPlatformCommand,
+} from '../platform-commands.js';
+
+const createCommandModuleUrl = (body: string) =>
+  `data:text/javascript,${encodeURIComponent(body)}`;
+
+const globalState = globalThis as typeof globalThis & {
+  __platformCommandCall?: unknown;
+};
+
+describe('platform CLI command discovery', () => {
+  afterEach(() => {
+    delete globalState.__platformCommandCall;
+  });
+
+  it('runs a discovered platform command', async () => {
+    const moduleUrl = createCommandModuleUrl(`
+      export const commands = [{
+        name: 'xctest',
+        async run(args, context) {
+          globalThis.__platformCommandCall = { args, context };
+        }
+      }];
+    `);
+    const loadConfig = vi.fn(async () => ({
+      projectRoot: '/tmp/project',
+      config: {
+        entryPoint: 'index.js',
+        appRegistryComponentName: 'App',
+        runners: [
+          {
+            name: 'ios',
+            config: {},
+            runner: '/virtual/runner.js',
+            cli: moduleUrl,
+            platformId: 'ios',
+          },
+        ],
+        plugins: [],
+        metroPort: 8081,
+        webSocketPort: undefined,
+        bridgeTimeout: 60000,
+        platformReadyTimeout: 300000,
+        bundleStartTimeout: 60000,
+        maxAppRestarts: 2,
+        resetEnvironmentBetweenTestFiles: true,
+        unstable__skipAlreadyIncludedModules: false,
+        unstable__enableMetroCache: false,
+        permissions: false,
+        detectNativeCrashes: true,
+        crashDetectionInterval: 500,
+        disableViewFlattening: false,
+        forwardClientLogs: false,
+      } satisfies Config,
+    }));
+
+    expect(
+      await runPlatformCommand({
+        argv: ['xctest', 'build', '--destination', 'simulator'],
+        cwd: '/tmp/project',
+        loadConfig,
+      })
+    ).toBe(true);
+    expect(globalState.__platformCommandCall).toEqual({
+      args: ['build', '--destination', 'simulator'],
+      context: {
+        cwd: '/tmp/project',
+        projectRoot: '/tmp/project',
+      },
+    });
+  });
+
+  it('deduplicates platform CLI modules across runners', async () => {
+    const moduleUrl = createCommandModuleUrl(`
+      export const commands = [{
+        name: 'xctest',
+        async run() {}
+      }];
+    `);
+    const loadConfig = vi.fn(async () => ({
+      projectRoot: '/tmp/project',
+      config: {
+        entryPoint: 'index.js',
+        appRegistryComponentName: 'App',
+        runners: [
+          {
+            name: 'ios-sim',
+            config: {},
+            runner: '/virtual/ios-sim-runner.js',
+            cli: moduleUrl,
+            platformId: 'ios',
+          },
+          {
+            name: 'ios-device',
+            config: {},
+            runner: '/virtual/ios-device-runner.js',
+            cli: moduleUrl,
+            platformId: 'ios',
+          },
+        ],
+        plugins: [],
+        metroPort: 8081,
+        webSocketPort: undefined,
+        bridgeTimeout: 60000,
+        platformReadyTimeout: 300000,
+        bundleStartTimeout: 60000,
+        maxAppRestarts: 2,
+        resetEnvironmentBetweenTestFiles: true,
+        unstable__skipAlreadyIncludedModules: false,
+        unstable__enableMetroCache: false,
+        permissions: false,
+        detectNativeCrashes: true,
+        crashDetectionInterval: 500,
+        disableViewFlattening: false,
+        forwardClientLogs: false,
+      } satisfies Config,
+    }));
+
+    const discoveredCommands = await discoverPlatformCommands({
+      cwd: '/tmp/project',
+      loadConfig,
+    });
+
+    expect(discoveredCommands?.commands).toHaveLength(1);
+  });
+
+  it('returns false when no platform command matches', async () => {
+    const loadConfig = vi.fn(async () => ({
+      projectRoot: '/tmp/project',
+      config: {
+        entryPoint: 'index.js',
+        appRegistryComponentName: 'App',
+        runners: [
+          {
+            name: 'android',
+            config: {},
+            runner: '/virtual/android-runner.js',
+            platformId: 'android',
+          },
+        ],
+        plugins: [],
+        metroPort: 8081,
+        webSocketPort: undefined,
+        bridgeTimeout: 60000,
+        platformReadyTimeout: 300000,
+        bundleStartTimeout: 60000,
+        maxAppRestarts: 2,
+        resetEnvironmentBetweenTestFiles: true,
+        unstable__skipAlreadyIncludedModules: false,
+        unstable__enableMetroCache: false,
+        permissions: false,
+        detectNativeCrashes: true,
+        crashDetectionInterval: 500,
+        disableViewFlattening: false,
+        forwardClientLogs: false,
+      } satisfies Config,
+    }));
+
+    await expect(
+      runPlatformCommand({
+        argv: ['xctest', 'build'],
+        cwd: '/tmp/project',
+        loadConfig,
+      })
+    ).resolves.toBe(false);
+  });
+
+  it('throws when two platform modules define the same command', async () => {
+    const firstModuleUrl = createCommandModuleUrl(`
+      export const commands = [{
+        name: 'xctest',
+        async run() {}
+      }];
+    `);
+    const secondModuleUrl = createCommandModuleUrl(`
+      // second module
+      export const commands = [{
+        name: 'xctest',
+        async run() {}
+      }];
+    `);
+    const loadConfig = vi.fn(async () => ({
+      projectRoot: '/tmp/project',
+      config: {
+        entryPoint: 'index.js',
+        appRegistryComponentName: 'App',
+        runners: [
+          {
+            name: 'ios',
+            config: {},
+            runner: '/virtual/ios-runner.js',
+            cli: firstModuleUrl,
+            platformId: 'ios',
+          },
+          {
+            name: 'android',
+            config: {},
+            runner: '/virtual/android-runner.js',
+            cli: secondModuleUrl,
+            platformId: 'android',
+          },
+        ],
+        plugins: [],
+        metroPort: 8081,
+        webSocketPort: undefined,
+        bridgeTimeout: 60000,
+        platformReadyTimeout: 300000,
+        bundleStartTimeout: 60000,
+        maxAppRestarts: 2,
+        resetEnvironmentBetweenTestFiles: true,
+        unstable__skipAlreadyIncludedModules: false,
+        unstable__enableMetroCache: false,
+        permissions: false,
+        detectNativeCrashes: true,
+        crashDetectionInterval: 500,
+        disableViewFlattening: false,
+        forwardClientLogs: false,
+      } satisfies Config,
+    }));
+
+    await expect(
+      discoverPlatformCommands({
+        cwd: '/tmp/project',
+        loadConfig,
+      })
+    ).rejects.toThrow("Duplicate platform CLI command 'xctest'");
+  });
+});

package/src/index.ts

@@ -1,11 +1,135 @@
 import { run, yargsOptions } from 'jest-cli';
 import { getConfig } from '@react-native-harness/config';
 import { runInitWizard } from './wizard/index.js';
+import { runPlatformCommand } from './platform-commands.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const JEST_CONFIG_EXTENSIONS = ['.mjs', '.js', '.cjs'];
 const JEST_HARNESS_CONFIG_BASE = 'jest.harness.config';
+const SKILLS_DIRECTORY = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../skills'
+);
+
+type SkillMetadata = {
+  fileName: string;
+  name: string;
+  description: string;
+};
+
+const readSkillMetadata = (fileName: string): SkillMetadata => {
+  const filePath = path.join(SKILLS_DIRECTORY, fileName);
+  const content = fs.readFileSync(filePath, 'utf8');
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+
+  const metadata = {
+    name: fileName.replace(/\.md$/, ''),
+    description: '',
+  };
+
+  if (frontmatterMatch) {
+    for (const line of frontmatterMatch[1].split('\n')) {
+      const separatorIndex = line.indexOf(':');
+
+      if (separatorIndex === -1) {
+        continue;
+      }
+
+      const key = line.slice(0, separatorIndex).trim();
+      const value = line.slice(separatorIndex + 1).trim().replace(/^['"]|['"]$/g, '');
+
+      if (key === 'name') {
+        metadata.name = value;
+      }
+
+      if (key === 'description') {
+        metadata.description = value;
+      }
+    }
+  }
+
+  return {
+    fileName,
+    name: metadata.name,
+    description: metadata.description,
+  };
+};
+
+const listSkills = () =>
+  fs
+    .readdirSync(SKILLS_DIRECTORY)
+    .filter((file) => file.endsWith('.md'))
+    .map(readSkillMetadata)
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+const printSkillList = () => {
+  for (const skill of listSkills()) {
+    console.log(`${skill.name}: ${skill.description}`);
+  }
+};
+
+const printSkillUsage = () => {
+  console.log(`Usage: harness skill <command>
+
+Commands:
+  list                 List bundled skills
+  get <name>           Print a bundled skill file
+
+Examples:
+  harness skill list
+  harness skill get core`);
+};
+
+const getErrorMessage = (error: unknown): string => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+};
+
+const runSkillCommand = () => {
+  const [, , commandName, subcommand, skillName] = process.argv;
+
+  if (subcommand === undefined || subcommand === 'list') {
+    printSkillList();
+    return;
+  }
+
+  if (subcommand === '--help' || subcommand === '-h') {
+    printSkillUsage();
+    return;
+  }
+
+  if (subcommand === 'get') {
+    if (!skillName) {
+      console.error('Missing skill name.');
+      printSkillUsage();
+      process.exit(1);
+    }
+
+    const skillPath = path.join(SKILLS_DIRECTORY, `${skillName}.md`);
+
+    if (!fs.existsSync(skillPath)) {
+      console.error(`Unknown skill '${skillName}'.`);
+      console.error(
+        `Available skills: ${listSkills()
+          .map((skill) => skill.name)
+          .join(', ')}`
+      );
+      process.exit(1);
+    }
+
+    console.log(fs.readFileSync(skillPath, 'utf8'));
+    return;
+  }
+
+  console.error(`Unknown ${commandName} subcommand '${subcommand}'.`);
+  printSkillUsage();
+  process.exit(1);
+};
 
 const checkForOldConfig = async () => {
   try {
@@ -73,9 +197,26 @@ const patchYargsOptions = () => {
   delete yargsOptions.logHeapUsage;
 };
 
-if (process.argv.includes('init')) {
-  runInitWizard();
-} else {
+const main = async () => {
+  if (process.argv[2] === 'skill' || process.argv[2] === 'skills') {
+    runSkillCommand();
+    return;
+  }
+
+  if (process.argv.includes('init')) {
+    runInitWizard();
+    return;
+  }
+
+  if (
+    await runPlatformCommand({
+      argv: process.argv.slice(2),
+      cwd: process.cwd(),
+    })
+  ) {
+    return;
+  }
+
   patchYargsOptions();
 
   const hasConfigArg =
@@ -96,5 +237,11 @@ if (process.argv.includes('init')) {
     }
   }
 
-  checkForOldConfig().then(() => run());
-}
+  await checkForOldConfig();
+  run();
+};
+
+main().catch((error) => {
+  console.error(getErrorMessage(error));
+  process.exit(1);
+});