Building Tests5 min read

URL Matching

Choose which pages each test runs on — exact, simple, contains, wildcard, regex.

URL Matching

Every test has a target URL and a match type that decides which pages the test runs on. The SDK evaluates the match on every pageview (including soft navigations in single-page apps), so picking the right mode matters for both targeting and reporting.

URL matching is the single most common source of “why isn't my test running?” questions, and the single most common source of inflated denominators (test counts visitors on pages you didn't mean to target). It's worth two minutes to pick the right mode upfront rather than debugging in production later.

The five modes below trade specificity for flexibility. Simple is the right default for most tests because it ignores the things that don't matter (protocol, www, trailing slash) and respects the things that do (pathname). Reach for the others when you have a specific reason.

Exact match

exact

Strictest mode. The visitor URL must match the test URL exactly, case-insensitively, after stripping the query string and hash. Protocol, subdomain, and trailing slash all matter.

Test URL: https://shop.example.com/pricing
Matches: https://shop.example.com/pricing?ref=email
Does not match: http://shop.example.com/pricing or https://example.com/pricing

Simple match

simple

Forgiving equality. Ignores protocol (http/https), the leading www., and a trailing slash, in addition to query and hash. Best when you want one canonical page regardless of how visitors arrive.

Test URL: example.com/pricing
Matches: https://www.example.com/pricing/, http://example.com/pricing?utm=x
Does not match: example.com/pricing/v2

Contains

contains

Substring match (case-insensitive) against either the full URL or the base URL (without query/hash). Use for groups of pages that share a path fragment, like every page under /blog/.

Test URL: /blog/
Matches: https://example.com/blog/post-1, https://example.com/category/blog/x
Does not match: https://example.com/news

Wildcard

wildcard

Pattern matching where * stands in for any sequence of characters. The match is anchored to the start and end of the base URL (query and hash are ignored). Special regex characters in the rest of the pattern are escaped, so you can paste real URLs safely.

Test URL: https://example.com/products/*/details
Matches: https://example.com/products/123/details, https://example.com/products/anything/details
Does not match: https://example.com/products/123 (no /details)

Regex

regex

Full regular expression evaluated case-insensitively against the visitor URL (including query string and hash). Standard regex syntax — stick to portable constructs (anchors, character classes, quantifiers) and test the pattern before launching. A typo here can silently match too few or too many pages.

Test URL: ^https://example\.com/users/\d+$
Matches: https://example.com/users/42
Does not match: https://example.com/users/profile

Wildcard redirects with relay_params

Redirect tests using Wildcard matching get one extra behavior when relay_params is enabled. If the variant's redirect URL points at the same base path as the wildcard, the SDK preserves the visitor's current pathname and only overlays the variant's query string and hash on top.

Example: test URL https://shop.example.com/* with variant URL https://shop.example.com/?preview_theme_id=123 sends a visitor on /products/jacket to https://shop.example.com/products/jacket?preview_theme_id=123. This is the pattern used for Shopify theme previews and similar site-wide query-string overlays. Exact redirects (/pricing → /pricing-v2) and wildcards with a different destination path always honor the configured destination instead.

URL matching tips

Default to Simple match when you can. Exact match requires a perfect string equality (protocol, host, path, query, hash) — small differences like a trailing slash or appended UTM parameters will fail. Simple ignores query and hash, which is usually what you want for marketing pages.

Use Wildcard sparingly. Wildcards are powerful but make it easy to target more pages than you intended. Reach for them when you genuinely want a path family (a /blog/* archive, a /products/* catalog) — not as a workaround for forgetting which exact URL you mean.

Watch the wizard's URL preview. Below the URL field, the wizard shows a friendly summary of what your pattern will match (“All pages on your website” / “Only this URL” / “Pages matching this pattern”) plus a warning if you picked Wildcard without a * character. If the summary doesn't describe what you want, adjust the match type before launching.

Frequently asked questions

Quick answers to the questions teams ask most about this part of Otter A/B.