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

# Developer Experience

> Ideal workflows for using Tusk as a developer

<img src="https://mintcdn.com/tusk/g9ARE0f2IAwondFu/images/developer-experience-docs-banner.png?fit=max&auto=format&n=g9ARE0f2IAwondFu&q=85&s=dc97cecf3ed7afbc58f904409d2ccf38" alt="Banner image showing Tusk and GitHub UI with a title that says 'Developer Experience'" width="2240" height="1260" data-path="images/developer-experience-docs-banner.png" />

## Overview

Tusk generates unit tests for your code in 3 main ways:

1. **PR/MR check**, which is triggered when a PR/MR (draft or otherwise) is raised or a new commit is pushed to the PR/MR's branch. This is a non-blocking check by default, akin to AI code review but with the added benefit of scaling your testing infra. [Read more](https://docs.usetusk.ai/automated-tests/overview).

2. **Manual trigger**, which requires you to add the `Tusk - Generate Tests` GitHub/GitLab label to the PR/MR. This label is automatically created when you connect Tusk to your GitHub organization or GitLab group/project.

3. **CoverBot**, a scheduled pipeline that runs daily or weekly and automatically raises a PR/MR with unit tests that help backfill coverage for untested parts of your repo. This is an async workflow that occurs at a fixed interval. [Read more](https://docs.usetusk.ai/automated-tests/coverbot).

<Info>For brevity, any mention of "PR" henceforth refers to both GitHub pull requests and GitLab merge requests.</Info>

***

## PR Check

### Committing to PR Branch

<Steps>
  <Step title="Create a PR">
    Software engineer creates a PR with their code changes. Here's an [example PR](https://github.com/marcel-tan/tusk-posthog-demo/pull/13) on a public repo.

    <img src="https://mintcdn.com/tusk/rkXbiuoXWBg0y75D/images/tusk-failing-test-mode-demo-client-pr.png?fit=max&auto=format&n=rkXbiuoXWBg0y75D&q=85&s=ee6a99863946390f4b870cda232e6a6c" alt="Example Tusk PR on a real world repo" width="3454" height="1900" data-path="images/tusk-failing-test-mode-demo-client-pr.png" />
  </Step>

  <Step title="Tusk generates tests">
    On PR creation, Tusk takes 8-15 mins to generate, run, and iterate on its unit tests (latency varies depending on PR size and repo complexity). By default, Tusk only surfaces failing tests that are indicative of a potential bug in the code changes.

    <img src="https://mintcdn.com/tusk/rkXbiuoXWBg0y75D/images/tusk-failing-test-mode-demo-client-pr-comment.png?fit=max&auto=format&n=rkXbiuoXWBg0y75D&q=85&s=97dfa407d8e7c55f6562f828de2e23b2" alt="Example Tusk PR comment on a real world repo" width="3452" height="1896" data-path="images/tusk-failing-test-mode-demo-client-pr-comment.png" />
  </Step>

  <Step title="Review Tusk's tests">
    On Tusk's completion, engineer clicks on Tusk's PR comment and reviews the test generation output in the Tusk web app.

    <img src="https://mintcdn.com/tusk/rkXbiuoXWBg0y75D/images/tusk-failing-test-demo-client-tccr-page-scenario.png?fit=max&auto=format&n=rkXbiuoXWBg0y75D&q=85&s=d9e768b28da0e7c0140cd4a3ef0fa527" alt="Failing test scenario output in Tusk web app" width="3452" height="1900" data-path="images/tusk-failing-test-demo-client-tccr-page-scenario.png" />
  </Step>

  <Step title="Commit Tusk's tests">
    Engineer selects which unit tests they want to commit and clicks **Commit tests** in the Tusk web app.

    <img src="https://mintcdn.com/tusk/rkXbiuoXWBg0y75D/images/tusk-failing-test-demo-client-tccr-page-commit-tests.png?fit=max&auto=format&n=rkXbiuoXWBg0y75D&q=85&s=62ff5529dd7e4caa98589d706cfc59ea" alt="Failing test scenario output in Tusk web app" width="3454" height="1900" data-path="images/tusk-failing-test-demo-client-tccr-page-commit-tests.png" />

    <Note>Once you commit Tusk's tests, the agent stops re-running test generation to avoid a loop. If you want Tusk to generate more tests (e.g., after adding new changes), add the **Tusk - Generate Tests** GitHub/GitLab label to the PR/MR.</Note>
  </Step>

  <Step title="Fix failing tests">
    If there are failing tests, engineer checks out the branch from within their IDE and fixes the bug in their code causing the failing test. Tusk labels failing tests with a `[Tusk] FAILING TEST` comment in the test file for ease of reference.

    Engineer re-runs the test file to make sure the failing test now passes, removes the `[Tusk] FAILING TEST` comment, and pushes the fix.
  </Step>

  <Step title="Merge the PR">
    Engineer goes through typical PR review and approval workflow and then merges the PR.
  </Step>
</Steps>

### Creating a Separate PR

<Steps>
  <Step title="Create a PR">
    Software engineer creates a PR ready for review. Here's an [example PR](https://github.com/marcel-tan/tusk-posthog-demo/pull/6) on a public repo.
  </Step>

  <Step title="Merge the PR with the hotfix">
    On PR creation, Tusk will start its test generation run. Engineer is free to get the PR approved and merged regardless of whether Tusk has completed its run.
  </Step>

  <Step title="Tusk generates tests">
    Tusk continues generating tests despite the PR being merged. Once completed, Tusk leaves a comment on the PR linking to the test generation output.

    <img src="https://mintcdn.com/tusk/rkXbiuoXWBg0y75D/images/tusk-create-separate-pr-pr-comment.png?fit=max&auto=format&n=rkXbiuoXWBg0y75D&q=85&s=cd76a1b6e660aa690c9c04baed45fe43" alt="PR comment for newly created Tusk PR on original PR" width="3452" height="1896" data-path="images/tusk-create-separate-pr-pr-comment.png" />
  </Step>

  <Step title="Create separate Tusk PR">
    Engineer selects which unit tests they want and clicks **Create PR** in the test generation output page in the Tusk web app. Tusk creates a separate PR containing the selected tests off of the original PR's base branch.

    <img src="https://mintcdn.com/tusk/rkXbiuoXWBg0y75D/images/tusk-create-separate-pr-new-pr-view.png?fit=max&auto=format&n=rkXbiuoXWBg0y75D&q=85&s=beba2a9e244a929e4a414d6a69a115f6" alt="Separate Tusk PR showing the generated unit tests for the original PR" width="3452" height="1898" data-path="images/tusk-create-separate-pr-new-pr-view.png" />
  </Step>

  <Step title="Fix failing tests">
    If there are failing tests, engineer goes to the new Tusk PR, pulls down the branch, and fixes the bug causing the failing test locally. Tusk labels failing tests with a `[Tusk] FAILING TEST` comment in the test file for ease of reference.

    Engineer re-runs the test file to make sure the failing test now passes, removes the `[Tusk] FAILING TEST` comment, and pushes the fix.
  </Step>

  <Step title="Approve and merge the Tusk PR">
    <img src="https://mintcdn.com/tusk/rkXbiuoXWBg0y75D/images/tusk-create-separate-pr-original-pr-view.png?fit=max&auto=format&n=rkXbiuoXWBg0y75D&q=85&s=e1b84940e782ab614f2d060ad6fa4911" alt="PR activity for newly created Tusk PR based off of the original PR's branch" width="2126" height="1256" data-path="images/tusk-create-separate-pr-original-pr-view.png" />

    Engineer goes through typical PR review workflow before approving and merging the Tusk PR with the tests.

    If the original PR is *not yet merged*, merging the Tusk PR adds a new commit to the original PR's branch. Otherwise, the Tusk PR is merged into the default branch that the original PR was based off of.
  </Step>
</Steps>

***

## Manual Trigger

### Testing an Open PR

<Steps>
  <Step title="Edit preferences">
    Go to **Settings > Seats > Edit preferences** in the Tusk web app.
  </Step>

  <Step title="Disable automatic test runs">
    Toggle on "User preferences" and uncheck the "Run on new commits" setting under Test Check Configuration.
  </Step>

  <Step title="Create a PR">
    Write code and create a PR once at a good stopping point.
  </Step>

  <Step title="Trigger test generation">
    Add the `Tusk - Generate Tests` GitHub/GitLab label to the PR/MR to generate unit tests for your changes.

    <img src="https://mintcdn.com/tusk/rkXbiuoXWBg0y75D/images/tusk-failing-test-mode-demo-client-pr-label.png?fit=max&auto=format&n=rkXbiuoXWBg0y75D&q=85&s=fb6eab4fdef7a9b28498a6e7f62e3f1f" alt="`Tusk - Generate Tests` label in GitHub PR page for manually triggering test generation" width="2454" height="1683" data-path="images/tusk-failing-test-mode-demo-client-pr-label.png" />
  </Step>

  <Step title="Tusk generates tests">
    Tusk takes 8-15 mins to generate, run, and iterate on its unit tests (latency varies depending on PR size and repo complexity). On completion, Tusk leaves a comment with the test summary and removes the label on the PR.
  </Step>

  <Step title="Commit Tusk's tests">
    Engineer selects which unit tests they want to commit and clicks **Commit tests** in the Tusk web app.
  </Step>

  <Step title="Fix failing tests">
    If there are failing tests, engineer pulls down the branch and fixes the bug causing the failing test locally. Tusk labels failing tests with a `[Tusk] FAILING TEST` comment in the test file for ease of reference.

    Engineer re-runs the test file to make sure the failing test now passes, removes the `[Tusk] FAILING TEST` comment, and pushes the fix.
  </Step>

  <Step title="Merge the PR">
    Engineer goes through typical PR review and approval workflow and then merges the PR.
  </Step>
</Steps>

### Backfill for Past PR

<Steps>
  <Step title="Find a past PR">
    Engineer goes to a past merged or closed PR to backfill unit tests for. They make sure the changes are **not** outdated.
  </Step>

  <Step title="Trigger test generation">
    Engineer adds the `Tusk - Generate Tests` GitHub/GitLab label to the PR/MR to generate unit tests for the code changes.
  </Step>

  <Step title="Tusk generates tests">
    Tusk takes 8-15 mins to generate, run, and iterate on its unit tests (latency varies depending on PR size and repo complexity). Once completed, Tusk leaves a comment on the merged/closed PR linking to the test generation output and removes the label.
  </Step>

  <Step title="Create separate Tusk PR">
    From the test generation output page, engineer selects which unit tests they want and clicks **Create PR**. Tusk creates a separate PR containing the selected tests off of the original PR's base branch.
  </Step>

  <Step title="Fix failing tests">
    If there are failing tests, engineer goes to the new PR, pulls down the branch, and fixes the bug causing the failing test locally. Tusk labels failing tests with a `[Tusk] FAILING TEST` comment in the test file for ease of reference.

    Engineer re-runs the test file to make sure the failing test now passes, removes the `[Tusk] FAILING TEST` comment, and pushes the fix.
  </Step>

  <Step title="Approve and merge the Tusk PR">
    Engineer goes through typical PR review workflow before approving and merging the Tusk PR with the selected tests.
  </Step>
</Steps>

***

## CoverBot

<Steps>
  <Step title="CoverBot runs on schedule">
    CoverBot runs at its scheduled interval, typically weekly on a Mon or Tue at 9:00am local time.
  </Step>

  <Step title="CoverBot creates a PR">
    CoverBot generates unit tests and creates a PR with passing tests for recently modified files with low coverage. Note that chosen files are batched according to similarity. Here's an [example PR](https://github.com/marcel-tan/tusk-posthog-demo/pull/11) on a public repo.
  </Step>

  <Step title="Review CoverBot's tests">
    The code owner or default assigned reviewer for CoverBot PRs reviews CoverBot's unit tests to make sure they are valid.
  </Step>

  <Step title="Modify tests (optional)">
    If modifications are needed, reviewer checks out the branch from within their IDE and modifies or removes unit tests as needed. Reviewer re-runs the test file to make sure it executes properly, then pushes the changes to the same branch.
  </Step>

  <Step title="Handle detected bugs (optional)">
    If any potential bugs are detected, reviewer copies Tusk's output from the PR description, creates a ticket, and assigns it to the code owner or themself to resolve.
  </Step>

  <Step title="Merge the CoverBot PR">
    Reviewer approves and merges the CoverBot PR to increase project coverage.
  </Step>
</Steps>

<Note>CoverBot will **not** generate a new PR until the previous PR (for the same test execution environment) is either merged or closed, so being timely about merging the PR helps you avoid missing a scheduled run.</Note>