> 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

# Running tests against existing deployment URLs

> **info: Preferred: Upload static assets or a container image**
> If possible, we recommend [running tests via your CI pipeline](/docs/github-actions-v2) by uploading static assets or a container image. These approaches are simpler and more reliable. Use deployment URL testing only if those options are not possible for your app.

### GitHub

If you use Vercel, Netlify, Cloudflare Pages or a similar system to generate PR preview URLs you can use the Meticulous GitHub app to test your PRs for you:

#### **Step 1: Install the Meticulous GitHub app**

Begin by [installing the Meticulous GitHub app](https://github.com/apps/alwaysmeticulous/installations/new).

#### **Step 2: Integrate with your preview URL provider**

Once the GitHub app is installed, select the system you use to generate PR preview links:

### Vercel

Install the [Meticulous Vercel integration](https://vercel.com/integrations/meticulous) and link your Vercel project in Meticulous.

If you have multiple Vercel projects for your GitHub repo, or multiple environments that you deploy the same branches/commits to, then you'll
need to let Meticulous know which environments it should run the tests against. You can do so by navigating to your project page and clicking on the *'Settings'* tab.
### Netlify

If you use Netlify you can configure a Netlify webhook so tests are triggered when new preview deploys are ready. Contact
[support@meticulous.ai](mailto:support@meticulous.ai) for help setting this up.
### Cloudflare

If you use Cloudflare pages you can configure a Cloudflare webhook so tests are triggered when new preview deploys are ready. Contact
[support@meticulous.ai](mailto:support@meticulous.ai) for help setting this up.
### Other/Home-Grown

If you use another preview URL system, or a home grown system you can generate
a GitHub deployment (environment) whenever a commit is pushed to a branch. This can then in turn be used to trigger a Meticulous test run
against the new deployment.

You can view instructions for how to do this [here](/docs/alternative-ci-setups/create-deployments-on-github), however it can be
fragile to set up correctly, and requires your PR preview system to have immutable, long-lived preview URLs and use identical
build settings across PR branches and main branch commits (to avoid false screenshot diffs). For this reason we recommend
[triggering Meticulous from your CI pipeline instead](/docs/github-actions-v2), if possible.

#### **Step 3 (optional): Make the Meticulous check blocking**

Whenever you open a new pull request Meticulous will now simulate a set of sessions against the preview URL before and after the PR, and post
a comment to the PR notifying of any changes spotted.

If you wish, you can make this check blocking by following the instructions [here](/docs/make-check-blocking). Doing so will prevent developers
from merging a PR which has visual differences until they have clicked the button to acknowledge the differences.
### GitLab

## Initial setup

If you use Vercel, Netlify or a similar system to generate PR preview URLs, you can use Meticulous to test your PRs.
To set this up:

1. Create a **legacy** GitLab personal access token (not a fine-grained token):
    - Go to your avatar → **Edit profile** → **Personal access tokens**
    - Choose **Add legacy token** (or **Create legacy token**), not **Generate fine-grained token**
    - Under **Scopes**, enable **api** and **read_repository**
    ([guide](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token))
    - Your GitLab user must have **Maintainer** or **Owner** on the project
    - Alternatively, a **project access token** (Premium/Ultimate on GitLab.com) with the same scopes and **Maintainer** role works
    ([project token guide](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token))
2. In Meticulous, link the repository and paste the token:
    - When creating a GitLab project, or from **Project settings → CI settings → Linked repository**
    - Enter your GitLab **project ID** (from **Settings → General** in GitLab), paste the access token, and configure the webhook shown after linking
3. Add the Meticulous webhook in GitLab (**Settings → Webhooks**):
    - Use the **Webhook URL** and **Secret token** from Meticulous
    - Enable **Merge request events**

## Further steps

### Vercel

Please let us know that you are using Vercel preview URLs in the email you sent us when setting up GitLab.
After some setup on our side Meticulous will automatically run tests against Vercel preview URLs whenever a new deployment is ready.
### Other preview URL providers

Call the */test-runs/trigger* endpoint from your GitLab CI pipeline whenever a new commit is pushed to a branch with an open MR.
The endpoint will trigger a test run, and Meticulous will handle setting commit statuses and posting notes to the merge request as
the test run progresses.

```http
POST https://app.meticulous.ai/api/test-runs/trigger

Headers: {
  authorization: "<API_TOKEN>"
  Content-Type: "application/json"
}

Body: {
  headSha: string, // the SHA of the commit you want to test
  headDeploymentUrl: string, // preview URL of headSha
  baseSha: string, // the SHA of the commit which the new test run will be compared against
  baseDeploymentUrl: string // preview URL of baseSha
}
```

There are two different types of pipelines that GitLab can trigger when a new commit is pushed to a branch with an open MR: *merge request
pipelines* and *merged results pipelines* ([GitLab docs](https://docs.gitlab.com/ee/ci/pipelines/merged_results_pipelines.html)). Your
pipeline should call the */test-runs/trigger* endpoint with different values for `headSha` and `baseSha` depending on which type of
pipeline you use.

If you use merge request pipelines:
- `headSha` should be the SHA of the commit that was just pushed to the branch. This is exposed in the CI pipeline as
`$CI_COMMIT_SHA`.
- `baseSha` should be the SHA of the commit from which the branch was created. This is exposed in the CI pipeline as
`$CI_MERGE_REQUEST_DIFF_BASE_SHA`.

If you use merged results pipelines:
- `headSha` should be the SHA of the merge commit. This is exposed in the CI pipeline as `$CI_COMMIT_SHA`.
- `baseSha` should be the SHA of the HEAD commit on the target branch. This is exposed in the CI pipeline as
`$CI_MERGE_REQUEST_TARGET_BRANCH_SHA`.