Skip to content

Getting Started

Jump to bottom
github-actions[bot] edited this page Jun 1, 2026 · 5 revisions

Getting Started with Canary

This guide takes you from zero to your first generated test. It should take about five minutes.

Prerequisites

You'll need:

  • Python 3.11 or later (python --version to check)
  • Node.js 18 or later (node --version to check)
  • Claude Code (Canary runs as a plugin — no separate API key needed)
  • Git

Step 1: Install Canary

git clone https://github.com/bop-clocktower/canary.git
cd canary
pip install -e .

Verify the install worked:

canary version

You should see the Canary banner with the current version number.

Step 2: Open Canary in Claude Code

Canary runs as a Claude Code plugin — no API key setup required. Install the plugin once:

claude plugin install .

Claude Code's own session provides the LLM. Your first /canary:generate will analyse the target file and write tests automatically.

Step 3: Generate Your First Test

In Claude Code, invoke the test-author persona:

/canary-write-test  Test that GET /api/health returns 200

Canary will:

  1. Classify the intent (API test)
  2. Pick the best framework (pytest)
  3. Generate a test file
  4. Print the path to the file

The output looks something like:

Canary Processing Request...

Test Type: api
Framework: pytest

Reasoning:
 - HTTP endpoint test maps to API category
 - Python ecosystem detected, pytest preferred

Output File:
tests/generated/api/test_api_health_get_200.py

Step 5: Look at the Generated File

cat tests/generated/api/test_api_health_get_200.py

Read through it. Check that:

  • The endpoint matches what you intended
  • The assertion matches the expected behavior
  • There are no placeholder values you need to fill in

Step 6: Run the Test

Once the file is written, run it with the CLI executor (deterministic, no key):

canary run tests/generated/api/test_api_health_get_200.py pytest

Or invoke the framework directly:

pytest tests/generated/api/test_api_health_get_200.py

What Happens to Generated Tests

Generated tests live in tests/generated/ — a scratch space that is not committed to git. They're yours to review and run freely.

Once a test passes review, you can promote it into the committed test suite. See the canary-promote-test skill for the full promotion checklist.

Want a Preview Without Generating?

Use canary recommend to see what framework Canary would pick, with its reasoning — a deterministic CLI command that makes no LLM call:

canary recommend "load test the search endpoint"

Next Steps

Clone this wiki locally