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, 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.

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

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.

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:

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"

Regexes use Google's RE2 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.

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.