Prerequisites

Java 17+
Maven 3.8+
brXM 16.x project
JUnit 5 (typically from brXM parent pom)

Step 1: Add Dependencies

Parent pom.xml


<properties>
    <brut.version>5.1.0</brut.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.bloomreach.forge.brut</groupId>
            <artifactId>brut-components</artifactId>
            <version>${brut.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.bloomreach.forge.brut</groupId>
            <artifactId>brut-resources</artifactId>
            <version>${brut.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

site/components/pom.xml


<!-- BRUT Component Testing -->
<dependency>
    <groupId>org.bloomreach.forge.brut</groupId>
    <artifactId>brut-components</artifactId>
    <scope>test</scope>
</dependency>

<!-- BRUT PageModel/JAX-RS Testing -->
<dependency>
    <groupId>org.bloomreach.forge.brut</groupId>
    <artifactId>brut-resources</artifactId>
    <scope>test</scope>
</dependency>

Warning: <scope>test</scope> is required. BRUT replaces core HST beans (pipelines, component manager, link creator, etc.) with test-oriented implementations. If BRUT is on the runtime classpath without test scope, its mock beans will shadow production beans and real HST endpoints will stop working.

Note: JUnit 5, Mockito, AssertJ are managed by the brXM parent pom.

Step 2: Write Your First Test


package com.example.components;

import org.bloomreach.forge.brut.components.annotation.BrxmComponentTest;
import org.bloomreach.forge.brut.components.annotation.DynamicComponentTest;
import org.junit.jupiter.api.Test;

import static org.assertj.core.api.Assertions.assertThat;

@BrxmComponentTest  // Zero-config! Bean packages auto-detected
class MyFirstTest {

    @Test
    void infrastructure_testIsProperlyInitialized(DynamicComponentTest brxm) {
        // Parameter injection - no IDE warnings
        assertThat(brxm.getHstRequest()).isNotNull();
        assertThat(brxm.getHstResponse()).isNotNull();
    }

    @Test
    void doBeforeRender_setsExpectedAttribute(DynamicComponentTest brxm) {
        MyComponent component = new MyComponent();
        component.init(null, brxm.getComponentConfiguration());
        component.doBeforeRender(brxm.getHstRequest(), brxm.getHstResponse());

        String result = brxm.getRequestAttributeValue("myAttribute");
        assertThat(result).isEqualTo("expected value");
    }
}

Alternative: Field Injection

Use when you need the instance in @BeforeEach:


@BrxmComponentTest
class MyFirstTest {

    @SuppressWarnings("unused")  // Injected by extension
    private DynamicComponentTest brxm;
    private MyComponent component;

    @BeforeEach
    void setUp() {
        component = new MyComponent();
        component.init(null, brxm.getComponentConfiguration());
    }

    @Test
    void doBeforeRender_setsExpectedAttribute() {
        component.doBeforeRender(brxm.getHstRequest(), brxm.getHstResponse());
        String result = brxm.getRequestAttributeValue("myAttribute");
        assertThat(result).isEqualTo("expected value");
    }
}

Tip: If auto-detection fails, add explicit packages: @BrxmComponentTest(beanPackages = {"com.example.beans"})

Step 3: Run Your Test


cd site/components
mvn test -Dtest=MyFirstTest

What Just Happened?

Element	Purpose
`@BrxmComponentTest`	JUnit 5 extension that bootstraps in-memory JCR, initializes HST mocks
`DynamicComponentTest brxm`	Test harness with `getHstRequest()`, `getHstResponse()`, `getRequestAttributeValue()`
Parameter injection	Standard JUnit 5 pattern - no IDE "field never assigned" warnings
beanPackages	Auto-detected from `project-settings.xml` or explicit configuration

Next Steps

I want to...	Go to...
Test JAX-RS REST endpoints	JAX-RS Testing Guide
Test PageModel API responses	Page Model Testing Guide
Add test content from YAML	Stubbing Test Data
Test authenticated users	Authentication Patterns
Fix a failing test	Troubleshooting Guide
Understand BRUT architecture	Architecture

Bloomreach Unit Testing Library