@react-native-harness/cli 1.1.0 → 1.2.0

package/dist/utils/status-formatter.d.ts

@@ -0,0 +1,27 @@
+import type { BridgeEvents } from '@react-native-harness/bridge';
+/**
+ * Type-safe status line formatter for bridge events.
+ * This ensures every event type has a corresponding status message.
+ *
+ * When adding new events to BridgeEvents:
+ * 1. Add the event type to the appropriate events file in packages/bridge/src/shared/
+ * 2. Add a formatter function to the statusFormatter object below
+ * 3. TypeScript will enforce that all event types are covered
+ * 4. The formatter function receives the full event data for type safety
+ */
+export type StatusFormatter = {
+    [K in BridgeEvents['type']]: (event: Extract<BridgeEvents, {
+        type: K;
+    }>) => string;
+};
+/**
+ * Maps every bridge event to a concise, informative status line.
+ * Each formatter receives the full event data for type safety.
+ */
+export declare const statusFormatter: StatusFormatter;
+/**
+ * Formats a bridge event into a status line.
+ * This function is type-safe and ensures all event types are handled.
+ */
+export declare const formatEventStatus: (event: BridgeEvents) => string;
+//# sourceMappingURL=status-formatter.d.ts.map

package/dist/utils/status-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/status-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG;KAC3B,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,GAAG,CAC3B,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KACtC,MAAM;CACZ,CAAC;AAcF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,eAkD7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,YAAY,KAAG,MAGvD,CAAC"}

package/dist/utils/status-formatter.js

@@ -0,0 +1,54 @@
+const formatDuration = (duration) => {
+    if (duration < 1000) {
+        return `${duration}ms`;
+    }
+    return `${(duration / 1000).toFixed(2)}s`;
+};
+const formatFileName = (file) => {
+    // Extract just the filename from the path for cleaner display
+    return file.split('/').pop() || file;
+};
+/**
+ * Maps every bridge event to a concise, informative status line.
+ * Each formatter receives the full event data for type safety.
+ */
+export const statusFormatter = {
+    // Test Collection Events
+    'collection-started': (event) => `📋 Collecting tests from ${formatFileName(event.file)}`,
+    'collection-finished': (event) => `✅ Collected tests from ${formatFileName(event.file)} (${formatDuration(event.duration)})`,
+    // Test Runner Events
+    'file-started': (event) => `🧪 Running tests in ${formatFileName(event.file)}`,
+    'file-finished': (event) => `✅ Finished ${formatFileName(event.file)} (${formatDuration(event.duration)})`,
+    'suite-started': (event) => `📦 ${event.name}`,
+    'suite-finished': (event) => {
+        const icon = event.status === 'failed'
+            ? '❌'
+            : event.status === 'skipped'
+                ? '⏭️'
+                : '✅';
+        return `${icon} ${event.name} (${formatDuration(event.duration)})`;
+    },
+    'test-started': (event) => `  🔄 ${event.name}`,
+    'test-finished': (event) => {
+        const icon = event.status === 'failed'
+            ? '❌'
+            : event.status === 'skipped'
+                ? '⏭️'
+                : event.status === 'todo'
+                    ? '📝'
+                    : '✅';
+        return `  ${icon} ${event.name} (${formatDuration(event.duration)})`;
+    },
+    // Bundler Events
+    'module-bundling-started': (event) => `📦 Bundling ${formatFileName(event.file)}`,
+    'module-bundling-finished': (event) => `✅ Bundled ${formatFileName(event.file)} (${formatDuration(event.duration)})`,
+    'module-bundling-failed': (event) => `❌ Failed to bundle ${formatFileName(event.file)} (${formatDuration(event.duration)})`,
+};
+/**
+ * Formats a bridge event into a status line.
+ * This function is type-safe and ensures all event types are handled.
+ */
+export const formatEventStatus = (event) => {
+    // TypeScript ensures this covers all event types
+    return statusFormatter[event.type](event);
+};

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+export declare function assert(condition: boolean, message: string): asserts condition;
+export declare class AssertionError extends Error {
+    constructor(message: string);
+}
+export declare const isPortAvailable: (port: number) => Promise<boolean>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAI7E;AAED,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAAO,CAAC,OAAO,CAa7D,CAAC"}

package/dist/utils.js

@@ -0,0 +1,26 @@
+import net from 'node:net';
+export function assert(condition, message) {
+    if (!condition) {
+        throw new AssertionError(message);
+    }
+}
+export class AssertionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AssertionError';
+    }
+}
+export const isPortAvailable = (port) => {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => {
+            server.close();
+            resolve(false);
+        });
+        server.once('listening', () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port);
+    });
+};

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/dist/wizard/jestIntegration.d.ts

@@ -0,0 +1,2 @@
+export declare const showJestIntegrationNotes: () => void;
+//# sourceMappingURL=jestIntegration.d.ts.map

package/dist/wizard/jestIntegration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jestIntegration.d.ts","sourceRoot":"","sources":["../../src/wizard/jestIntegration.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,YAgBpC,CAAC"}

package/dist/wizard/jestIntegration.js

@@ -0,0 +1,15 @@
+import { note } from '@react-native-harness/tools';
+export const showJestIntegrationNotes = () => {
+    note(`Update your jest.config.js to include the Harness project:
+
+module.exports = {
+  projects: [
+    {
+      displayName: 'Harness',
+      preset: 'react-native-harness',
+      testMatch: ['<rootDir>/**/__tests__/**/*.harness.[jt]s?(x)'],
+    },
+    // ...your other projects
+  ],
+};`, 'Next Steps');
+};

package/dist/wizard/packageManager.d.ts

@@ -0,0 +1,2 @@
+export declare const detectPackageManager: () => "pnpm" | "yarn" | "npm";
+//# sourceMappingURL=packageManager.d.ts.map

package/dist/wizard/packageManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageManager.d.ts","sourceRoot":"","sources":["../../src/wizard/packageManager.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB,+BAKhC,CAAC"}

package/dist/wizard/packageManager.js

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const detectPackageManager = () => {
+    const cwd = process.cwd();
+    if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs.existsSync(path.join(cwd, 'yarn.lock')))
+        return 'yarn';
+    return 'npm';
+};

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.1.0",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,16 +22,16 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@react-native-harness/bridge": "1.1.0",
-    "@react-native-harness/tools": "1.1.0",
-    "@react-native-harness/config": "1.1.0",
-    "@react-native-harness/platforms": "1.1.0"
+    "@react-native-harness/platforms": "1.2.0",
+    "@react-native-harness/tools": "1.2.0",
+    "@react-native-harness/config": "1.2.0",
+    "@react-native-harness/bridge": "1.2.0"
   },
   "devDependencies": {
     "jest-cli": "^30.2.0",
-    "@react-native-harness/platform-android": "1.1.0",
-    "@react-native-harness/platform-apple": "1.1.0",
-    "@react-native-harness/platform-web": "1.1.0"
+    "@react-native-harness/platform-android": "1.2.0",
+    "@react-native-harness/platform-apple": "1.2.0",
+    "@react-native-harness/platform-web": "1.2.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');
+  });
+});
+```