# Java Build Tools Plugins

The core concepts form the foundation of SeaLights integration across all Java build tools:

1. **Build Scanner** – collects project metadata, generates Build Session ID
2. **Test Listener** – streams test execution to SeaLights
3. **Build Session ID** – uniquely identifies a build scan
4. **Test Stages** – logical grouping of tests for reporting
5. **Execution Modes** – control which phases run (full, scan-only, tests-only, disabled)

> By understanding these shared concepts, developers can onboard quickly and troubleshoot integration issues across Maven, Gradle, or SBT.

### 1. Build Scanner

The **Build Scanner** is the central SeaLights component that:

* Collects information about your project’s build and source code
* Generates a Build Session ID
* Prepares test instrumentation for your test tasks
* Collects JVM arguments, system properties, and environment info

**Key points:**

* Each plugin (Maven, Gradle, SBT) uses the Build Scanner to analyze the project structure before running tests.
* The scanner can run independently of tests (scan-only mode).
* Output is used to map tests to code changes and to track coverage in SeaLights.

> Example: `sl-build-scanner.jar` runs the scanner in SBT via the `-sbt` flag or in Maven/Gradle via plugin execution.

### 2. Test Listener

The **Test Listener** collects runtime test execution data and streams it to SeaLights.

**Responsibilities:**

* Hooks into test tasks (JUnit, TestNG, ScalaTest, etc.)
* Sends test results to SeaLights in real time
* Tracks which lines of code were executed by which tests
* Works with multiple test stages (unit, integration, functional)

**Key points:**

* Tests must be executed in a forked JVM to allow the listener to attach reliably
* Each plugin wires the listener according to its build tool’s lifecycle

> Example: SBT injects `sl-test-listener.jar` parameters into configured test tasks via `sealightsTestTasksAndStages`.

### 3. Build Session ID

The **Build Session ID** is a unique identifier for a single build scan.

**Purpose:**

* Links test execution to a specific build scan
* Allows multiple test stages (unit, integration, functional) to share the same scan metadata
* Enables incremental test coverage tracking

**Key points:**

* Generated by the Build Scanner at the start of a build
* Stored in the workspace or sent to SeaLights server for reporting
* Can be reused across multiple test runs (e.g., in tests-only mode)

### 4. Test Stages

**Test Stages** represent logical groups of tests within a build.

**Examples:**

* Unit Tests
* Integration Tests
* Functional Tests

**Purpose:**

* Organize test execution results in SeaLights UI
* Map each SBT/Maven/Gradle test task to a stage name
* Allow reporting per stage, enabling detailed insights on coverage and quality

**Example:**

```json
"testTasksAndStages": {
    "Test/test": "Unit Tests",
    "IntegrationTest/test": "Integration Tests"
}
```

**Key points:**

* Stage names appear in the SeaLights dashboard
* Plugins default to two listener stages; additional stages may require custom wiring

### 5. Execution Modes

**Execution Modes** control which phases of SeaLights integration run during a build.

<table><thead><tr><th width="117.68359375">Mode</th><th width="249.38671875">Description</th><th>Use Case</th></tr></thead><tbody><tr><td>Full Run</td><td>Build Scanner + Test Listener</td><td>Standard integration, collects coverage and test results</td></tr><tr><td>Scan Only</td><td>Build Scanner only</td><td>Reuse previous test data, or prepare scan metadata without running tests</td></tr><tr><td>Tests Only</td><td>Test Listener only</td><td>Reuse an existing Build Session ID, collect new test results only</td></tr><tr><td>Disabled</td><td>No SeaLights tasks</td><td>Temporarily skip integration without removing configuration</td></tr></tbody></table>

**Key points:**

* Execution mode can be set via plugin flags, JSON configuration, or JVM properties
* Helps optimize CI runs and avoid redundant scans
* All plugins (Maven, Gradle, SBT) respect these modes consistently


---

# Agent Instructions: 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:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-build-tools-plugins.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.