> For the complete documentation index, see [llms.txt](https://burp-ai-agent.six2dez.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://burp-ai-agent.six2dez.com/developer/testing.md).

# Testing & Debugging

## Running Tests

The project uses JUnit 5 for testing.

### Fast suite (default in CI PR gate)

```bash
./gradlew test -PexcludeHeavyTests=true
```

Excludes `*IntegrationTest`, `*ConcurrencyTest`, `*BackpressureTest`, `*RestartPolicyTest`. Fast enough to run on every PR across Linux, macOS, and Windows in the matrix defined in `.github/workflows/build.yml`.

### Full suite (nightly + on release tag)

```bash
./gradlew test nightlyRegressionTest
```

Adds the integration, concurrency, backpressure, and supervisor restart-policy suites. Automatically executed by `.github/workflows/nightly-regression.yml` at 03:30 UTC and by `.github/workflows/release.yml` on every version tag.

### Integration / concurrency tests

Some tests require a local Ollama instance or mock server. Ensure your environment is set up before running the heavy suite locally.

## Lint

```bash
./gradlew ktlintFormat   # auto-fix style
./gradlew ktlintCheck    # verify style
```

`ktlintCheck` runs in CI as its own job. Until the baseline is clean it is configured as non-blocking (`continue-on-error: true` in the workflow, `ignoreFailures = true` in `build.gradle.kts`). Flip both off with `-PktlintStrict=true` once the repository passes cleanly.

## Coverage

JaCoCo is wired into the default `test` task:

```bash
./gradlew test jacocoTestReport
```

Reports land at `build/reports/jacoco/test/html/index.html` and `build/reports/jacoco/test/jacocoTestReport.xml`. The Linux leg of the PR-gate matrix uploads the XML report as a CI artifact for later aggregation.

## Building from Source

The build produces two artifacts (see [issue #231](https://github.com/six2dez/burp-ai-agent/issues/231)):

```bash
./gradlew clean shadowJar                  # full build (default, GitHub releases)
./gradlew clean shadowJar -PstoreBuild=true # BApp Store build
```

* **Full build** → `build/libs/Custom-AI-Agent-full-<version>.jar` — registers all 59 MCP tools.
* **Store build** → `build/libs/Custom-AI-Agent-<version>.jar` — registers only the 8 extension-native AI MCP tools (BApp Store compliance).

The `-PstoreBuild` flag sets the generated `BuildFlags.STORE_BUILD` constant that gates which tools register. Use the resulting JAR to install the extension in Burp, where it appears as **Custom AI Agent**.

## SBOM

```bash
./gradlew cyclonedxBom
```

Produces `build/reports/sbom/bom.json` (CycloneDX 1.5). The release workflow attaches it to the GitHub Release alongside the JAR and its SHA-256 checksum.

## Debugging

If the extension is behaving unexpectedly, check the logs.

### 1. Burp Extension Output

In Burp Suite:

1. Go to **Extensions** → **Installed**.
2. Select **Custom AI Agent**.
3. Click the **Output** tab.
   * **Standard Output**: Shows general info and initialization messages.
   * **Errors**: Shows Java stack traces if the extension crashes.

### 2. Java Logs

The extension uses SLF4J. Logs are typically printed to the Burp stdout. If you launched Burp from a terminal, check the terminal window for detailed logs.

### 3. Agent Debugging

If a backend is failing:

1. Check the **Status** indicator in the top bar.
2. If it says **Crashed**, check **Extensions → Installed → Custom AI Agent → Output/Errors** for the exit code.
3. Check the `audit.jsonl` file (if Audit Logging is enabled) to see exactly what was sent to the model.

## Manual UI Checks

Before a release, perform these sanity checks:

* [ ] Load extension in Burp Community and Pro.
* [ ] Verify tab appearance on macOS (Retina), Linux, and Windows (HiDPI).
* [ ] Check context menus appear on Request/Response and Issues.
* [ ] Verify scrolling in the Chat interface.

## Recommended Local Test Command

To reduce flakiness and keep CI-like behavior locally, use:

```bash
JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home ./gradlew test --no-daemon -Dorg.gradle.workers.max=1
```

Additional focus areas covered by the test suite:

* Passive scanner JSON parsing with nested/escaped content.
* Injection point extraction for escaped strings, booleans, and nulls.
* Active payload generation paths (numeric/string/UUID).
* Response analyzer diff and time-based detection boundaries.
* Shared HTTP conversation history trimming and concurrent writes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://burp-ai-agent.six2dez.com/developer/testing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.