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

# Testing your project with dotbot verify hooks

> Configure verify hooks so dotbot automatically runs your test suite after every task, catches regressions before merging, and enforces code quality gates.

dotbot integrates testing directly into the task lifecycle through verify hooks - numbered PowerShell scripts that run automatically after each AI task completes. Before marking a task as `done` and squash-merging it to your main branch, dotbot runs every verify hook in ascending filename order. If any hook exits with a non-zero code, the task is flagged and the merge is blocked.

## How verify hooks work

When a task transitions to `done`, dotbot builds a merged hook chain from two directories:

* **Framework hooks** at `<DOTBOT_HOME>/src/hooks/verify/` - shipped with dotbot and managed by the framework.
* **Project hooks** at `.bot/hooks/verify/` - added by installed stacks or written by your team.

Scripts from both directories are merged by filename. When a project hook has the same filename as a framework hook, the project hook runs instead. Scripts with unique filenames from both directories all run. The final chain is sorted by filename, so the numeric prefix convention (`00-`, `01-`, ...) determines execution order.

The five framework hooks included with every dotbot installation are:

| Script                       | What it checks                                                      |
| ---------------------------- | ------------------------------------------------------------------- |
| `00-privacy-scan.ps1`        | Scans staged files for secrets or sensitive data                    |
| `01-git-clean.ps1`           | Confirms the working tree has no uncommitted changes                |
| `02-git-pushed.ps1`          | Verifies the task branch has been pushed to the remote              |
| `03-check-md-refs.ps1`       | Validates path references in markdown and data files                |
| `04-framework-integrity.ps1` | Verifies framework-owned files under `.bot/` have not been modified |

When you install the `dotnet` stack, it adds two additional scripts to `.bot/hooks/verify/`. Because their filenames differ from the framework scripts, all seven scripts run in order:

| Stack    | Additional hook        | What it runs    |
| -------- | ---------------------- | --------------- |
| `dotnet` | `03-dotnet-build.ps1`  | `dotnet build`  |
| `dotnet` | `04-dotnet-format.ps1` | `dotnet format` |

Hooks from all installed stacks run together in a single ordered sequence, giving you a composable quality gate pipeline.

## Adding a custom verify hook

To add your own test step, create a numbered PowerShell script in `.bot/hooks/verify/`. Choose a number higher than the built-in hooks to ensure your tests run after the standard checks:

```powershell theme={null}
# .bot/hooks/verify/10-run-my-tests.ps1
#!/usr/bin/env pwsh

Write-Output "Running integration tests..."

$result = & npx jest --ci 2>&1
if ($LASTEXITCODE -ne 0) {
    Write-Error "Integration tests failed."
    exit 1
}

Write-Output "All tests passed."
```

<Tip>
  Use a prefix between `10` and `99` for custom hooks so there is room to add more standard hooks later without renumbering your scripts.
</Tip>

## Viewing hook results

Verify hook output is captured in the task's session log and shown in the dashboard. When a hook fails:

1. The task stays in `in-progress` - it is not marked `done`
2. The failure reason and hook output appear in the session log under `.bot/workspace/sessions/`
3. The Workflow tab in the dashboard shows the task as blocked with the hook's exit code

To investigate, open the session log for the failed task and look for the hook name and the error output it produced.

## Skipping verify hooks

`script`, `mcp`, `task_gen`, `barrier`, and `interview` task types skip verify hooks automatically. These task types are dispatched directly by the runtime executor without going through the `task_set_status` MCP path that fires the verify chain. Verify hooks always run for `prompt` and `prompt_template` tasks before the task is considered complete.

<Note>
  Run `dotbot doctor` to check whether verify hooks in your project have any syntax issues or reference missing commands. Doctor scans hook scripts and reports problems before you start a workflow run.
</Note>

## Running the dev environment for tests

Some verify hooks require a running development server. dotbot provides two MCP tools - `dev_start` and `dev_stop` - that the AI agent calls at the start and end of task execution when a running dev environment is needed. See [Plans & Steering](/reference/mcp-tools/plans-and-steering) for details on these tools.