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

# Bring your own tests

> Connect your existing test repository, test management system, or CI pipeline results — and let Bugzy contribute to and extend what you already have.

Bugzy can work with your existing test suite, external repositories, and test management systems. If your team already has tests, a TMS, or CI pipelines that produce test results, Bugzy contributes to and extends what you already have. This is the Bring Your Own Tests (BYOT) model.

## Three independent concerns

BYOT has three dimensions that can be mixed and matched per project.

### 1. Test case management — where do test cases live?

| Mode              | Storage                                                      | How Bugzy interacts             |
| ----------------- | ------------------------------------------------------------ | ------------------------------- |
| Managed (default) | Markdown files in `test-cases/*.md`                          | Reads and writes files directly |
| External TMS      | [Zephyr Scale](/docs/integrations/zephyr), TestRail, or other TMS | Calls TMS API via MCP tools     |

When using an external TMS, Bugzy's workflow doesn't change — only the interface for creating and reading test cases switches from files to API calls.

### 2. Test automation — where does test code live?

| Mode                   | Location                                    | Git management                                        |
| ---------------------- | ------------------------------------------- | ----------------------------------------------------- |
| Managed (default)      | `tests/` in the project repo                | Container commits to same repo                        |
| External repo (GitHub) | Your GitHub test repo, cloned into `tests/` | Container creates branch + pull request on your repo  |
| External repo (GitLab) | Your GitLab test repo, cloned into `tests/` | Container creates branch + merge request on your repo |

Both GitHub and GitLab are supported as external repo providers, including self-hosted GitLab instances. The provider is detected automatically from your connected integration.

### 3. Test results — how does Bugzy get test outcomes?

| Mode              | Source                             | Interface                                   |
| ----------------- | ---------------------------------- | ------------------------------------------- |
| Managed (default) | Bugzy runs tests and parses output | Direct (agent sees stdout + artifacts)      |
| External push     | Your CI pushes results to Bugzy    | Webhook/API with results payload            |
| External pointer  | Your CI sends reference to results | Webhook/API with TMS run ID or artifact URL |

## The "Just a Folder" principle

From the agent's perspective, tests always live at `./tests/`. It reads `./tests/CLAUDE.md` to understand the framework and structure. It creates, edits, and runs files in `./tests/`. The agent never knows — or needs to know — whether it's working with a managed repo or an external one.

The container handles the complexity: before execution, it clones the external repo into `./tests/`. After execution, it creates a branch, commits changes, and opens a PR on the external repo.

## BYOT onboarding

When you connect an external test repo, Bugzy runs the `explore-test-codebase` task:

<Steps>
  <Step title="Read conventions">
    Reads the repo's `CLAUDE.md` for framework conventions.
  </Step>

  <Step title="Scan structure">
    Scans the test directory structure — specs, pages, fixtures.
  </Step>

  <Step title="Identify patterns">
    Identifies test patterns and coding conventions.
  </Step>

  <Step title="Map coverage">
    Builds a map of existing test coverage.
  </Step>

  <Step title="Record findings">
    Records findings in the knowledge base.
  </Step>
</Steps>

This gives Bugzy the context to write tests that match your existing patterns.

## The CLAUDE.md convention

Every test repo (managed or external) has a `CLAUDE.md` describing:

* Framework and language
* Directory layout
* How to run tests
* Coding conventions
* Project-specific knowledge

This is Bugzy's onboarding document for any test repo.

## External repo event handling

When your external test repo has PR/MR activity:

**GitHub:**

* **PR opened** — Bugzy can review test changes
* **PR reviewed** — Bugzy incorporates feedback
* **PR merged** — Tests become part of the active suite

**GitLab:**

* **MR opened** — Bugzy can review test changes
* **MR note (comment)** — Bugzy incorporates feedback
* **MR merged** — Tests become part of the active suite

## Results parser generation

When you push external CI results, Bugzy generates a parser that understands your result format (JUnit XML, custom JSON, etc.) and feeds parsed results into the triage pipeline.