> Meticulous records real user sessions from a web app and replays them against each commit to catch visual regressions.
>
> Full AI-readable docs index (complete project setup journey + every page as markdown): https://app.meticulous.ai/llms.txt

# Filter Sessions by Start URL

Meticulous automatically replays the set of sessions that will exhaustively test your change. However, when triggering a
run with [`ci run-with-uploaded-asset-chunks`](/docs/how-to/incremental-asset-upload), you can pass a session filter
to restrict the set of sessions executed beyond that, by filtering to only sessions that start on specific routes — for
example to only test the part of your app affected by a change. This can be useful in extremely large applications,
where your build system may be able to more tightly isolate the blast radius of a change than Meticulous can via static
analysis.

## Usage

Write a JSON file with a `session-start-url-matches-any-regex` key listing one or more regexes:

```bash
cat > session-filter.json <<'EOF'
{
  "session-start-url-matches-any-regex": [
    "/checkout/",
    "^https://app\\.example\\.com/settings"
  ]
}
EOF

npx @alwaysmeticulous/cli ci run-with-uploaded-asset-chunks \
  --apiToken="$METICULOUS_API_TOKEN" \
  --commitSha="$CI_COMMIT_SHA" \
  --assetReferencesManifest="./assets-manifest.json" \
  --sessionFilter="./session-filter.json"
```

A session is replayed if its **start URL** — the URL the session started recording on — matches **at least one** of the
regexes. The same filtered set of sessions is used for both the head run and any base run created to compare against, so
comparisons stay consistent.

## When the filter matches no sessions

No test run is triggered, and the CLI exits with code `4` (every other failure exits with `1`). The distinct code lets
a pipeline treat "this change touches no recorded flow" as a skip rather than a build failure:

```bash
set +e
npx @alwaysmeticulous/cli ci run-with-uploaded-asset-chunks ... --sessionFilter="./session-filter.json"
exit_code=$?
set -e
if [ "$exit_code" -eq 4 ]; then
  echo "No sessions matched the filter — skipping Meticulous for this change."
  exit 0
fi
exit "$exit_code"
```

## Regex syntax

Regexes use [Google's RE2 syntax](https://github.com/google/re2/wiki/Syntax). They are validated before the run is
triggered, so a regex that doesn't compile fails fast in the CLI with a clear error.

> **info: Filtering only affects which sessions run**
> The session filter narrows a single test run down from the project's selected sessions; it doesn't change which sessions
> Meticulous records or selects. Runs triggered without `--sessionFilter` still replay the full selected set.