> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qawolf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up PR testing

> Run QA Wolf tests against preview environments on pull requests and report results as GitHub status checks.

<Info>
  This guide is for QA Wolf full service customers. If you're unsure whether this applies to you, contact your QA Wolf team.
</Info>

## Configure basic PR testing

<Steps>
  <Step title="Configure GitHub integration">
    Go to Workspace Settings -> Integrations to enable and authorize the GitHub integration.
  </Step>

  <Step title="Notify QA Wolf of preview deployments">
    Choose one of the following methods to tell QA Wolf when a new preview environment is ready to be tested.

    **GitHub Deployments**

    If your team uses a hosting platform that integrates with GitHub — like Vercel — your deployments are already being reported to GitHub via the [GitHub Deployments API](https://docs.github.com/en/rest/deployments/deployments). QA Wolf listens for those deployment records and automatically acts when one is marked as successful. No additional configuration is required.

    **GitHub Action**

    Configure the [Notify QA Wolf on Deploy](https://github.com/marketplace/actions/notify-qa-wolf-on-deploy) GitHub Action to tell us when a new preview environment is ready to be tested.

    **SDK**

    If GitHub Actions aren't an option, the `@qawolf/ci-sdk` npm package offers a flexible alternative. See the [npm package documentation](https://www.npmjs.com/package/@qawolf/ci-sdk) for setup details.
  </Step>

  <Step title="Ask your QA Wolf team to set up triggers">
    QA Wolf will configure a trigger that matches your preview deployments. Reach out to your QA Wolf team to get this set up.
  </Step>
</Steps>

***

## Advanced: Merge queue setup

<Info>
  This section covers an optional flow for teams using GitHub's merge queue. Some customers run QA Wolf in the merge queue as a required final gate; others avoid it when the latency or complexity outweighs the confidence gain.
</Info>

### Add a default passing PR check

Add a GitHub Actions workflow that creates a passing **QA Wolf Test Results** check when a PR is opened or updated. This prevents pull requests from being blocked before the merge queue run happens.

```yaml Create .github/workflows/qawolf-pr-check.yml: expandable theme={null}
name: Create QA Wolf PR check

on:
  pull_request:
    types: [opened, reopened, synchronize]

jobs:
  qawolf_check_creation:
    runs-on: ubuntu-latest
    permissions:
      checks: write
      pull-requests: read
    steps:
      - name: Create passing QA Wolf check
        uses: actions/github-script@v6
        with:
          script: |
            await github.rest.checks.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              name: 'QA Wolf Test Results',
              head_sha: context.payload.pull_request.head.sha,
              status: 'completed',
              conclusion: 'success',
              output: {
                title: 'QA Wolf Test Results',
                summary: 'QA Wolf tests will run in the merge queue.'
              }
            });
```

### Trigger QA Wolf tests in the merge queue

Add a GitHub Actions workflow that notifies QA Wolf only during merge queue execution.

```yaml Create .github/workflows/qawolf-merge-queue.yml: expandable theme={null}
name: Test preview environment

on:
  merge_group:

jobs:
  test-preview-environment:
    name: Trigger QA Wolf tests
    runs-on: ubuntu-latest
    needs:
      - wait-for-preview-environment
    steps:
      - name: Notify QA Wolf of deployment
        uses: qawolf/notify-qawolf-on-deploy-action@v1
        with:
          qawolf-api-key: "${{ secrets.QAWOLF_API_KEY }}"
          deployment-url: "${{ env.PREVIEW_URL }}"
          deployment-type: "provided-by-qawolf"
          deduplication-key: "${{ github.ref }}"
```

### What this workflow assumes

* Your CI pipeline already creates a preview environment per pull request.
* The preview environment URL is available as `PREVIEW_URL` when this job runs.
* A prior job (such as `wait-for-preview-environment`) ensures the preview environment is fully deployed and reachable before QA Wolf is notified.

### Require QA Wolf tests before merge

<Steps>
  <Step>
    In the left sidebar, do one of the following:

    * Click **Rules** (if your repo uses GitHub's new rulesets), or
    * Click **Branches** (for classic branch protection rules).
  </Step>
</Steps>

## Verify your PR testing setup

<Steps>
  <Step title="Open a pull request in GitHub.">
    On the pull request page, confirm that a check named **QA Wolf Test Results** appears in the checks section and initially shows as passing.
  </Step>

  <Step title="Add the pull request to the merge queue.">
    When the PR enters the merge queue, GitHub will trigger the merge-queue workflow.
  </Step>

  <Step title="Confirm QA Wolf starts a test run.">
    In the **QA Wolf app**, go to the **Runs** tab and verify that a new run starts for the preview environment associated with the pull request.
  </Step>

  <Step title="Confirm the check updates before merge.">
    Back in **GitHub**, watch the **QA Wolf Test Results** check update from its placeholder state to the final pass or fail result. The merge completes only after this check finishes successfully.
  </Step>
</Steps>