Java Build Tools Plugins

This page explains shared concepts used across SeaLights Java build tool plugins (Maven, Gradle, SBT). Understanding these is key for integrating SeaLights into your builds and CI pipelines.

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:

"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.

Mode	Description	Use Case
Full Run	Build Scanner + Test Listener	Standard integration, collects coverage and test results
Scan Only	Build Scanner only	Reuse previous test data, or prepare scan metadata without running tests
Tests Only	Test Listener only	Reuse an existing Build Session ID, collect new test results only
Disabled	No SeaLights tasks	Temporarily skip integration without removing configuration

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