Skip to content

Commit 8a7c26f

Browse files
V3RONV3RON
committed
docs: explain Metro port fallback
1 parent da04e92 commit 8a7c26f

3 files changed

Lines changed: 38 additions & 25 deletions

File tree

‎website/src/docs/api/cli.mdx‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ npx react-native-harness init
1313
```
1414

1515
The wizard will help you:
16+
1617
- Detect your project type (Expo or React Native CLI).
1718
- Install required platform packages.
1819
- Configure Android, iOS, or Web runners.
@@ -30,10 +31,11 @@ npx react-native-harness [test-file-pattern] [options]
3031

3132
### Harness Specific Flags
3233

33-
| Flag | Description |
34-
| :--- | :--- |
35-
| `--harnessRunner <name>` | Specify which runner from your `rn-harness.config.mjs` to use. **Note:** Only one runner can be specified per command execution. |
36-
| `--config, -c <path>` | Path to your Harness Jest configuration (defaults to `jest.harness.config.mjs`). |
34+
| Flag | Description |
35+
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
36+
| `--harnessRunner <name>` | Specify which runner from your `rn-harness.config.mjs` to use. **Note:** Only one runner can be specified per command execution. |
37+
| `--config, -c <path>` | Path to your Harness Jest configuration (defaults to `jest.harness.config.mjs`). |
38+
| `--metroPort <port>` | Set the preferred Metro port for this run. If the selected runner supports it and the port is busy, Harness will try the next available ports automatically. |
3739

3840
### Running on Multiple Platforms
3941

@@ -66,6 +68,7 @@ To ensure stability and compatibility with real native devices, React Native Har
6668
Harness executes tests **serially** (one at a time) on the target device to prevent native resource conflicts (like multiple tests trying to access the camera or filesystem simultaneously).
6769

6870
The following Jest flags are **ignored or disabled**:
71+
6972
- `--maxWorkers`
7073
- `--runInBand` (Implicitly always true)
7174
- `--maxConcurrency`
@@ -76,6 +79,7 @@ The following Jest flags are **ignored or disabled**:
7679
Harness manages the test environment, transformation, and module resolution internally to ensure tests can be bundled by Metro and run on-device.
7780

7881
The following Jest configuration flags are **disabled**:
82+
7983
- `--runner` / `--testRunner`
8084
- `--testEnvironment`
8185
- `--preset`

‎website/src/docs/getting-started/configuration.mdx‎

Lines changed: 25 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -86,28 +86,34 @@ For Expo projects, the `entryPoint` should be set to the path specified in the `
8686

8787
## All Configuration Options
8888

89-
| Option | Description |
90-
| :--------------------------------- | :--------------------------------------------------------------------------------------------------------- |
91-
| `entryPoint` | **Required.** Path to your React Native app's entry point file. |
92-
| `appRegistryComponentName` | **Required.** Name of the component registered with AppRegistry. |
93-
| `runners` | **Required.** Array of test runners (at least one required). |
94-
| `defaultRunner` | Default runner to use when none specified. |
95-
| `host` | Hostname or IP address to bind the Metro server to (default: Metro default). |
96-
| `metroPort` | Port used by Metro and Harness bridge traffic (default: `8081`). |
97-
| `platformReadyTimeout` | Platform-ready timeout in milliseconds (default: `300000`). |
98-
| `bridgeTimeout` | Bridge timeout in milliseconds (default: `60000`). |
99-
| `bundleStartTimeout` | Bundle start timeout in milliseconds (default: `60000`). |
100-
| `resetEnvironmentBetweenTestFiles` | Reset environment between test files (default: `true`). |
101-
| `detectNativeCrashes` | Detect native app crashes during startup and test execution (default: `true`). |
102-
| `crashDetectionInterval` | Interval in milliseconds to check for native crashes (default: `500`). |
103-
| `disableViewFlattening` | Disable view flattening in React Native (default: `false`). |
104-
| `coverage` | Coverage configuration object. |
105-
| `coverage.root` | Root directory for coverage instrumentation (default: `process.cwd()`). |
106-
| `forwardClientLogs` | Forward console logs from the app to the terminal (default: `false`). |
107-
| `unstable__enableMetroCache` | Enable Metro transformation cache under `.harness/metro-cache` and log when reusing it (default: `false`). |
89+
| Option | Description |
90+
| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
91+
| `entryPoint` | **Required.** Path to your React Native app's entry point file. |
92+
| `appRegistryComponentName` | **Required.** Name of the component registered with AppRegistry. |
93+
| `runners` | **Required.** Array of test runners (at least one required). |
94+
| `defaultRunner` | Default runner to use when none specified. |
95+
| `host` | Hostname or IP address to bind the Metro server to (default: Metro default). |
96+
| `metroPort` | Preferred port used by Metro and Harness bridge traffic (default: `8081`). Harness falls back to the next available port when this one is already in use. |
97+
| `platformReadyTimeout` | Platform-ready timeout in milliseconds (default: `300000`). |
98+
| `bridgeTimeout` | Bridge timeout in milliseconds (default: `60000`). |
99+
| `bundleStartTimeout` | Bundle start timeout in milliseconds (default: `60000`). |
100+
| `resetEnvironmentBetweenTestFiles` | Reset environment between test files (default: `true`). |
101+
| `detectNativeCrashes` | Detect native app crashes during startup and test execution (default: `true`). |
102+
| `crashDetectionInterval` | Interval in milliseconds to check for native crashes (default: `500`). |
103+
| `disableViewFlattening` | Disable view flattening in React Native (default: `false`). |
104+
| `coverage` | Coverage configuration object. |
105+
| `coverage.root` | Root directory for coverage instrumentation (default: `process.cwd()`). |
106+
| `forwardClientLogs` | Forward console logs from the app to the terminal (default: `false`). |
107+
| `unstable__enableMetroCache` | Enable Metro transformation cache under `.harness/metro-cache` and log when reusing it (default: `false`). |
108108

109109
## Test Runners
110110

111+
:::info Metro Port Fallback
112+
Harness treats `metroPort` as the preferred starting port. If that port is already in use, Harness tries the next available ports automatically and logs the port it selected for the run.
113+
114+
Physical iOS devices are the exception: they always use the default Metro port and do not support custom or fallback ports.
115+
:::
116+
111117
A test runner defines how tests are executed on a specific platform. React Native Harness uses platform-specific packages to create runners with type-safe configurations.
112118

113119
Runner-specific launch options belong inside each runner config via `appLaunchOptions`.

‎website/src/docs/platforms/ios.mdx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,11 @@ applePlatform({
4343
FEATURE_X: '1',
4444
},
4545
},
46-
})
46+
});
4747
```
4848

4949
#### Finding Simulator Details
50+
5051
You can list all available simulators using `xcrun`:
5152

5253
```bash
@@ -72,9 +73,11 @@ applePlatform({
7273
FEATURE_X: '1',
7374
},
7475
},
75-
})
76+
});
7677
```
7778

79+
Physical iOS devices always connect to the default Metro port (`8081`). Custom `metroPort` values and automatic port fallback are supported on simulators, but not on physical iOS devices.
80+
7881
## Requirements
7982

8083
- **Xcode**: Xcode must be installed on your system.

0 commit comments

Comments
 (0)