# 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