In Detox, when do you use device.setURLBlacklist() or the detoxURLBlacklistRegex launch argument, and how do the patterns have to be written?

## The problem: requests that never finish **Detox** treats every in-flight network request as a reason to wait. That is what lets a test tap "Buy ticket" and immediately assert the confirmation: Detox waits for the purchase request to return. But some requests are **not part of the flow under test** and may never complete while the screen is open: - a **long-poll** that asks the lottery server for live draw results and stays open until a result arrives; - a persistent streaming connection to a real-time endpoint; - **background telemetry** or log uploads that retry; - requests to a local development service on the test machine. While any of these is pending, the app is never network-idle and every step blocks. Detox's answer is a **URL blacklist**: requests whose URL matches a pattern are ignored by network synchronization. ## Two ways to set it | API | When it applies | Typical use | |---|---|---| | `device.setURLBlacklist(patterns)` | from the call onwards, in the running app | a screen that starts polling mid-test | | `detoxURLBlacklistRegex` launch argument | from app launch | requests fired during startup | Mid-test: ```js await device.setURLBlacklist([/draws\/live/, /telemetry\.example\.com/]); // ... steps on the live-draw screen ... await device.setURLBlacklist([]); // reset ``` From launch, because the launch process is itself synchronized and a request that starts before the test can call `setURLBlacklist` can block it: ```js await device.launchApp({ newInstance: true, launchArgs: { detoxURLBlacklistRegex: [/draws\/live/, /telemetry\.example\.com/] }, }); ``` ## How patterns must be written Both APIs accept an **array** whose entries are either strings, interpreted as regular-expression sources, or `RegExp` objects, and a mix of both is allowed. The rules that trip people up: 1. **Flags.** Only `i`, `m` and `s` are portable across iOS and Android. A `RegExp` with `g`, `y`, `d`, `u` or `v` throws a `TypeError` at launch or when `setURLBlacklist` is called. 2. **Escaping.** A string is a regex source, so `.` matches any character. `'.*127.0.0.1.*'` works, but `/.*127\.0\.0\.1.*/` says what you mean. 3. **Array form over the legacy string.** `detoxURLBlacklistRegex` also accepts an older single-string format with escaped quotes and parentheses. It is sensitive to formatting, and its comma splitting used to corrupt patterns containing commas, such as `\d{1,3}`. The array form avoids both problems. 4. **Match the whole URL you mean.** A pattern like `/live/` also excludes an unrelated `/api/livestream-config` request that the test may need to wait for. ## Finding the right URL to exclude Do not guess. When a step blocks for longer than `session.debugSynchronization` (10 seconds by default), Detox's busy log lists the in-flight requests by URL, for example "1 network requests with URLs: URL #1: https://draws.example.com/live?since=…". Build the narrowest pattern that matches exactly those URLs, anchor the host and path, and leave query strings out of the pattern when they vary. If the log shows no network entries at all, the blocker is something else, such as an animation or a short timer, and a URL blacklist will not help. ## What the blacklist does not do - It does **not** block or mock the request; the app still sends it and receives the response. It only tells Detox not to wait for it. - It does **not** exclude animations or timers. An endless loader stays a blocker; Detox has no animation blacklist. - It does **not** fix a request that should have completed. If the draw-results endpoint hangs because the test server is down, excluding it hides a broken dependency and the test may assert against a screen that never received its data. ## Deciding whether to blacklist Ask whether the user flow under test **depends** on the request's answer: - If it does, keep it synchronized and fix the slowness or the server. - If it does not, and the request is long-lived or background by design, exclude it, as narrowly as possible, and ideally as a named constant shared by the suite so reviewers see the list in one place. ## Summary The URL blacklist is the fine-grained alternative to switching synchronization off: every other resource stays synchronized, and only named noisy endpoints are ignored. Use the launch argument for startup traffic, `setURLBlacklist` for traffic that begins mid-test, portable regex flags, and the array form.