Review pull requests with Test Companion

Ask Test Companion whether a pull request is ready to test, and review its test code for tests that flake, assert nothing, or ignore your repository.

Before a pull request moves to testing, you want to know that the intended behavior is written down. You also want the required checks to pass, and the new tests to check a real outcome. Test Companion reads the pull request with the GitHub CLI and reports all of that in one verdict card. A developer can run the review before a handover. A tester can run it on a pull request that they receive.

Test Companion always returns a readiness verdict. When the pull request changes test files, it also reviews the test code.

The review reads the pull request but does not change it. Test Companion does not comment on, approve, or merge the pull request, and it does not update the linked ticket.

Prerequisites

You need the following before you start:

• The GitHub CLI, gh, installed and signed in. Test Companion reads the pull request, its diff, and its checks through gh.
• A connected project management tool, when you want the review to read the acceptance criteria of the linked ticket. See Project management tools.
• A version of Test Companion that supports the review in your IDE. See Availability.

Review a pull request

In the chat box, give the pull request URL, its number such as #42, or the branch you checked out. Then ask whether it is ready to test.

Example prompt

Is this PR ready to test? https://github.com/org/repo/pull/42

When you name more than one pull request, Test Companion reviews them as one change. A merged pull request stays in the review and is marked as merged on the card. A closed pull request is dropped from the review.

If you paste only a pull request link, Test Companion asks what you want to do with it. Choose the readiness check.

The readiness verdict

Test Companion computes the verdict from the signals on the card. The AI does not write the verdict.

Merge conflicts, requested changes, and force pushes appear on the card but do not change the verdict.

The verdict card shows the verdict at the top and lists the pull requests under it. When the change depends on another pull request, the card names it under Blocked by. The entry shows the state of that pull request and where Test Companion found the dependency. The card has the following tabs:

Intent

Test Companion takes the intended behavior from the first source that it can read, in this order:

1. The acceptance criteria of a ticket whose key appears in the pull request or the branch name, such as feat/ABC-123-login.
2. A requirements page that the ticket links to.
3. The pull request description.
4. The diff.

If it finds no description of the intended behavior, Test Companion asks you for one. The Intent tab names the source it used.

What to test

The tab marks each user flow with one of the following states:

• ✓ tested
• ⚠ test flagged in review
• test missing
• can’t be automated yet
• not addressed in this change

Only a test that this pull request adds or changes counts as coverage. An older test in the repository does not. A flow shows ⚠ test flagged in review when its test has a Critical finding in the test code review.

Test Companion also checks testability. It reports a new interactive element that has no stable hook, such as a data-testid attribute. It also reports a hook that the change removes.

Impact

Test Companion reports the environment and the feature flags as unconfirmed unless the diff sets them. A flag shows its state: unconfirmed, on by default, off by default, or removed.

To fix

The tab appears only for a Not ready verdict. Under To make it ready, it lists one line for each blocker. For example, a draft pull request produces the line Mark #42 ready for review — it is still a draft.

Test code review

When the pull request changes test files, Test Companion reviews the test code. It reports problems that change what a test does. It does not report formatting or naming. Each finding has one of four types:

Test Companion grades the test code from the diff. When the pull request belongs to the open workspace, it also checks the code against your enabled rules. It does not run the tests during a pull request review.

The findings appear under Test issues to fix, below the verdict card. Each finding has a severity: Critical, Important, Low, or Nit. It shows the reason in plain words, the file and line, and a Proposed fix or the Evidence.

Test Companion then asks how to handle the findings. Choose one of these options:

• Fix all N issues, where N is the number of findings, or Fix this issue when there is one finding.
• Fix Critical + Important only. This option appears when the findings mix those severities with lower ones.
• Something else, to describe what you want in your own words.

Test Companion applies the fixes in the same chat.

Automatic test review in the IDE

In Visual Studio Code and JetBrains IDEs, Test Companion also reviews the tests that it writes. It does so at two points in a task.

After Test Companion writes a new test file, it reviews the uncommitted changes once before it finishes the task. If it finds issues, it asks what to do. Choose Fix these first, Raise a GitHub PR, Not now, or Something else. Test Companion reviews once per task, so a fix does not start a second review.

Before Test Companion raises a pull request, it reviews the test files that this task has not reviewed. If it finds issues, choose Raise the PR anyway, Fix these first, or Something else. Any choice other than Raise the PR anyway holds the pull request. Fix the issues, then click Raise a GitHub PR again.

The findings appear in a Test review card, in the same form as in a pull request review. The card shows up to 10 findings and reports how many lower-severity findings it left out. Before it grades the change, Test Companion also does the following:

• It runs the first changed test file with the test command of your project. The run stops after 5 minutes.
• It reads the errors that your IDE reports for the changed files, such as lint and type errors.
• When a Test Reporting & Analytics project is selected, it reads the run history of the changed tests. A test that is already flaky is then named as flaky.

The automatic review treats the following files as test files:

• JavaScript and TypeScript files named *.spec.*, *.test.*, *.cy.*, or *.e2e.*.
• Any file in a __tests__ folder.
• Python files named test_*.py or *_test.py.
• Python files in a tests or test folder.

It compares your files with the last commit. A new file that Git does not track yet is not part of the review. To include such a file, stage it with git add.

If the review cannot complete, Test Companion reports that and continues the task.

Review test changes from the CLI

Run tc review in a terminal or a CI pipeline:

# Review the uncommitted changes in your working tree
tc review

# Review the changes on the current branch against main
tc review --branch main

# Review the test changes in a pull request, with JSON output
tc review --pr https://github.com/org/repo/pull/42 --json

The command only reports findings. It does not run tests, apply fixes, or open a pull request. You cannot combine --branch and --pr, and --pr needs the GitHub CLI signed in. The command exits with code 0 whether or not it finds issues. A non-zero exit code means that the review itself could not run. To fail a CI step on findings, read the --json output. The review stops after 5 minutes.

tc review reviews test code. To review generated test cases in Test Management, run tc tm review. See the CLI command reference.

Availability

Pull request review is not available in Test Companion Cloud.

Next steps

• Generate test cases: Write test cases for the flows that the pull request changes.
• Automate tests: Convert test cases into automation scripts.
• Rules: Record the conventions that the test code review checks against.