Skip to main content

JUnit 5 Integration

Run your JUnit 5 tests as usual and have results automatically reported to TMS. The SDK provides a JUnit extension that hooks into the test lifecycle and sends results with rich metadata.

Install​

Maven​

The SDK is served from the ProvaLab Maven repository, not Maven Central, so add the repository as well as the dependency:

pom.xml
<repositories>
    <repository>
        <id>provalab</id>
        <url>https://plugins.provalab.io/maven</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.tms</groupId>
        <artifactId>tms-java-sdk</artifactId>
        <version>2.2.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Gradle​

build.gradle
repositories {
    maven { url 'https://plugins.provalab.io/maven' }
}
dependencies {
    testImplementation 'com.tms:tms-java-sdk:2.2.0'
}
build.gradle.kts
repositories {
    maven { url = uri("https://plugins.provalab.io/maven") }
}
dependencies {
    testImplementation("com.tms:tms-java-sdk:2.2.0")
}

Requirements: Java 17+, JUnit 5.10+

Configure​

1. Set environment variables​

export TMS_API_KEY=your-api-key
export TMS_API_URL=https://tms.yourcompany.com
export TMS_ORGANIZATION_ID=1
export TMS_PROJECT_ID=12

2. Add the TMS extension to your test class​

src/test/java/com/example/LoginTest.java
import com.tms.junit.TMSJUnitExtension;
import com.tms.junit.TMSTestCase;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import static org.junit.jupiter.api.Assertions.*;

@ExtendWith(TMSJUnitExtension.class)
class LoginTest {

    @Test
    @TMSTestCase(id = 101)
    void shouldLoginWithValidCredentials() {
        boolean result = AuthService.login("[email protected]", "password123");
        assertTrue(result, "Login should succeed with valid credentials");
    }

    @Test
    @TMSTestCase(id = 102, priority = "high", testType = "regression")
    void shouldRejectInvalidPassword() {
        assertThrows(AuthException.class, () -> {
            AuthService.login("[email protected]", "wrong-password");
        });
    }

    @Test
    @TMSTestCase(id = 103, priority = "medium", tags = {"auth", "edge-case"})
    void shouldHandleExpiredAccount() {
        assertThrows(AccountExpiredException.class, () -> {
            AuthService.login("[email protected]", "password123");
        });
    }
}

3. (Alternative) Register globally via ServiceLoader​

Instead of adding @ExtendWith to every class, register the extension globally:

Create src/test/resources/META-INF/services/org.junit.jupiter.api.extension.Extension:

src/test/resources/META-INF/services/org.junit.jupiter.api.extension.Extension
com.tms.junit.TMSJUnitExtension

Then enable auto-detection in your build:

pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <properties>
            <configurationParameters>
                junit.jupiter.extensions.autodetection.enabled=true
            </configurationParameters>
        </properties>
    </configuration>
</plugin>

Now all test classes automatically report to TMS without @ExtendWith.

Run​

Maven​

mvn test

Gradle​

gradle test

You'll see TMS output in the console:

TMS JUnit Extension
   Test Run Created: ID 855
   Running: LoginTest

   PASS shouldLoginWithValidCredentials (0.12s)
   PASS shouldRejectInvalidPassword (0.08s)
   FAIL shouldHandleExpiredAccount (0.15s)

   TMS Results Summary
   Test Run ID: 855
   Total:   3
   Passed:  2
   Failed:  1
   Skipped: 0

View Results in TMS​

  1. Open TMS and go to your project
  2. Click Test Runs in the sidebar
  3. Find the run named "JUnit: LoginTest"
  4. Click into it to see individual test results with error details and metadata

The @TMSTestCase Annotation​

The annotation supports rich metadata that appears in TMS:

@TMSTestCase(
    id = 456,                              // Required: TMS test case ID
    title = "User Login with SSO",         // Optional: display name
    priority = "critical",                 // Optional: critical, high, medium, low
    testType = "smoke",                    // Optional: smoke, regression, e2e, unit
    tags = {"auth", "sso", "critical"},    // Optional: categorization tags
    description = "Verify SSO login flow", // Optional: test description
    componentId = 5,                       // Optional: TMS component ID
    expectedDurationSeconds = 30,          // Optional: expected runtime
    automated = true                       // Optional: is this automated? (default: true)
)

All metadata is pushed to TMS and appears in the test result detail view.

Advanced Configuration​

Pass environment variables via Maven​

pom.xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <environmentVariables>
            <TMS_API_KEY>${env.TMS_API_KEY}</TMS_API_KEY>
            <TMS_API_URL>https://tms.yourcompany.com</TMS_API_URL>
            <TMS_ORGANIZATION_ID>1</TMS_ORGANIZATION_ID>
            <TMS_PROJECT_ID>12</TMS_PROJECT_ID>
        </environmentVariables>
    </configuration>
</plugin>

Pass environment variables via Gradle​

build.gradle
test {
    environment 'TMS_API_KEY', System.getenv('TMS_API_KEY')
    environment 'TMS_API_URL', 'https://tms.yourcompany.com'
    environment 'TMS_ORGANIZATION_ID', '1'
    environment 'TMS_PROJECT_ID', '12'
}

Disable TMS for local development​

export TMS_DISABLED=true
mvn test

Custom test run name​

export TMS_TEST_RUN_NAME="Nightly Regression - JUnit"

Test case ID in test name​

If you prefer not to use annotations, you can include [TMS-123] in the display name:

@Test
@DisplayName("[TMS-101] Should login with valid credentials")
void testLogin() {
    // The extension extracts TMS-101 from the display name
}

Verify It Works​

  1. Add the dependency to your project
  2. Set your environment variables
  3. Create a simple test:
src/test/java/com/example/TMSVerifyTest.java
import com.tms.junit.TMSJUnitExtension;
import com.tms.junit.TMSTestCase;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import static org.junit.jupiter.api.Assertions.*;

@ExtendWith(TMSJUnitExtension.class)
class TMSVerifyTest {

    @Test
    @TMSTestCase(id = 1)
    void verifyTmsIntegration() {
        assertEquals(2, 1 + 1, "TMS integration working");
    }
}
  1. Run: mvn test -Dtest=TMSVerifyTest or gradle test --tests TMSVerifyTest
  2. Check the console for the TMS summary
  3. Open TMS and confirm the test run appears
Common issues
  • "Not configured" message: Make sure TMS_API_KEY, TMS_ORGANIZATION_ID, and TMS_PROJECT_ID are all set as environment variables
  • Extension not running: Check that @ExtendWith(TMSJUnitExtension.class) is on the class or global auto-detection is enabled
  • Java version error: The SDK requires Java 17+. Check with java -version