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

# PR Testing

> Get better PR reviews by giving the QA.tech agent the context it needs.

The review agent prioritizes context signals in this order:

1. **PR description** — what does the author say this PR does?
2. **Linked issues/tickets** — Jira or Linear tickets referenced in the description, branch name, or commits
3. **Changed files** — which files and routes were modified
4. **Commit messages** — incremental changes

An empty or vague PR description forces the agent to infer intent from the diff alone — less focused test selection, more guesswork about which user flows are affected. The same applies to the `context` input when triggering reviews via the [Change Review Action](https://docs.qa.tech/pr-testing/github#change-review-action) or [API](https://docs.qa.tech/api-reference/chat/start-change-review-chat.md).

## Recommended Workflow for New Features

Instead of creating tests before the feature exists, document what should be tested in your ticket or PR description:

**1. Add Acceptance Criteria to Your Ticket**

When creating a Linear, Jira, or other ticket for a new feature, include
acceptance criteria that describe what should be tested. For example: "User
can navigate to Admin page and add a new user", "New user receives
invitation email", "Admin can see the new user in the user list".

**2. Include Test Requirements in PR Description**

When you open the PR, include testing requirements in the description. The
review agent reads your PR and uses this context to select and create
appropriate tests.

**3. Tests Are Created When the PR Is Ready**

When the PR is published and your preview environment is ready, the agent
analyzes the changes and acceptance criteria, then creates and runs tests
for the new functionality. See [PR Testing overview](https://docs.qa.tech/pr-testing/overview.md)
and [GitHub](https://docs.qa.tech/configuration/github-app.md).

> [!TIP]
>
> You spend time describing *what* to test (which you would do for acceptance
> criteria anyway), and the agent handles *how* to test it once the feature is
> ready. That is how the suite stays current as features ship.

## What makes a good PR description

A useful PR description should answer:

| Section | What to include |
| :- | :- |
| **What changed** | User-facing behavior changes, not implementation details |
| **Why** | The purpose — a user story, bug report, or product goal |
| **What to test** | Affected user flows, pages, edge cases |
| **Out of scope** | What this PR intentionally does *not* change |

### Example

A PR that adds Apple Pay to the checkout flow:

```markdown theme={null}
## What changed

Added Apple Pay as a payment method on the checkout page. Users on
supported devices see an Apple Pay button alongside the existing
credit card form.

## Why

Requested by enterprise customers to reduce checkout friction on
Safari/iOS (PROJ-1234).

## What to test

- Apple Pay button visibility on supported vs. unsupported devices
- Completing a purchase with Apple Pay
- Falling back to credit card when Apple Pay is declined
- Existing credit card checkout still works

## Out of scope

- Subscription payments (separate PR)
- Mobile app (web only)
```

Compare this to a PR titled *"Add payment stuff"* with no description — the agent won't know to focus on device compatibility or the fallback flow.

## Link your tickets

If PRs reference issue identifiers — like `PROJ-1234` in the description, branch name (`feature/PROJ-1234-apple-pay`), or commits — the agent fetches the full ticket details including acceptance criteria. Works with Jira and Linear when the integration is configured in project settings. Acceptance criteria from the ticket stack with the PR description, so you don't need to duplicate them.

## Automate PR descriptions with an AI agent

AI coding agents can read the diff, inspect surrounding code for context, and generate a structured description in seconds. You can run this as a GitHub Action so every PR gets a description automatically.

### GitHub Action example

This example uses [OpenCode](https://opencode.ai), but the same idea works with any coding agent or LLM CLI tool. Bring your own API key.

```yaml theme={null}
name: Enrich PR description

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  enrich-description:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install OpenCode
        run: curl -fsSL https://opencode.ai/install | bash

      - name: Generate PR description
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode run --auto "
            Look at the diff between this branch and origin/${{ github.event.pull_request.base.ref }}.
            Read relevant source files for context.

            Write a PR description with these sections:
            ## What changed — user-facing behavior changes
            ## Why — purpose of the change
            ## What to test — affected user flows, pages, edge cases
            ## Out of scope — what this PR does not change

            Be specific and concise. Write the output to pr_description.md.
          "

      - name: Update PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          if [ -f pr_description.md ]; then
            gh pr edit ${{ github.event.number }} --body-file pr_description.md
          fi
```

> [!NOTE]
>
> This is illustrative — adapt the prompt and tooling to your stack.

### Run it locally

You can do the same thing locally before opening a PR:

```bash theme={null}
opencode run "Write a PR description for my current changes"
```

Most coding agents support custom commands — reusable prompts you invoke with a shortcut. You can create a `/create-pr` command that diffs against main, generates a description with test steps, and creates the PR:

```bash theme={null}
opencode run --command create-pr
```

The command would instruct the agent to run `git diff main...HEAD`, draft a concise description, and create or update the PR with `gh pr create` or `gh pr edit --body-file`. See [OpenCode custom commands](https://opencode.ai/docs/commands/) or your agent's equivalent. Claude Code also has a built-in `/pr` command.

CI gives you consistency — every PR gets a description regardless of who opens it.

When you start a review from CI, you can also pass extra testing guidance in the `context` field (ticket text or a generated summary). See [API pull request testing](https://docs.qa.tech/pr-testing/api.md#pass-extra-context).

## Summary

| Approach | Effort | Best for |
| :- | :- | :- |
| Write good PR descriptions manually | Low | Small teams with strong PR culture |
| Link Jira/Linear tickets | None (automatic) | Teams already using issue trackers |
| Auto-generate descriptions in CI | One-time setup | Teams where PRs consistently lack context |
| Pass `context` on the API or Action | Per-workflow | Custom testing guidance per PR type |

These approaches stack.

## Related documentation

* **[GitHub pull request testing](https://docs.qa.tech/pr-testing/github)** — Change Review Action reference and examples
* **[GitHub](https://docs.qa.tech/configuration/github-app.md)** — Install the App and repository settings
* **[PR Testing overview](https://docs.qa.tech/pr-testing/overview.md)** — When a review runs and which CI to use
* **[API pull request testing](https://docs.qa.tech/pr-testing/api.md)** — Start a review from any CI and pass `context`
* **[PR Testing for Mobile Apps](https://docs.qa.tech/pr-testing/agents/mobile.md)** - Pin native iOS and Android PR builds instead of preview URLs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.