Proposal for adding Bean-Centric testing.

[jamesbognar]

Proposal: Add Bean-Centric Testing to JUnit's Assertions API

Summary

Hi all, long-time fan of JUnit here!

Over the years I've been writing custom assertions for my open source projects.
I've finally gotten around to capturing what I feel are the most useful ones and formalizing the API.
I feel this could be an extremely useful addition to the existing Assertions API in JUnit.

I propose adding Bean-Centric Testing (BCT) capabilities to JUnit's existing Assertions API.
This would provide developers with powerful, concise methods for testing complex Java objects without the verbosity of traditional property-by-property assertions.

Problem Statement

Current JUnit assertions require verbose, repetitive code when testing complex objects:

// Traditional JUnit - verbose and error-prone
@Test
void testUser() {
    User user = new User(...);
    
    assertEquals("Alice", user.getName());
    assertEquals(25, user.getAge());
    assertTrue(user.isActive());
    assertEquals("123 Main St", user.getAddress().getStreet());
    assertEquals("Springfield", user.getAddress().getCity());
    assertEquals("IL", user.getAddress().getState());
}

This approach has several issues:

• Verbose: Many lines for simple object validation
• Error-prone: Easy to miss properties or make typos
• Hard to maintain: Changes to object structure require updating multiple assertions
• Poor readability: The intent is buried in implementation details

Proposed Solution

Add Bean-Centric Testing methods to JUnit's Assertions API:

// Proposed BCT - concise and readable
@Test
void testUser() {
    User user = new User(...);
    
    // Test multiple properties at once
    assertBean(
        user, 
        "name,age,active,address{street,city,state}", 
        "Alice,25,true,{123 Main St,Springfield,IL}"
    );
}

It's even more powerful when having to assert multiple beans at once.

// Proposed BCT - concise and readable
@Test
void testUser() {
    List<User> users = List.of(new User(...), ...);
    
    // Test multiple beans at once
    assertBeans(
        users, 
        "name,age,active,address{street,city,state}", 
        "Alice,25,true,{123 Main St,Springfield,IL}",
        "Bob,30,false,{10 Evergreen Way,Springfield,IL}"
    );
}

Key Features

1. Concise Assertions

• Replace many lines of manual property extraction with single assertion calls
• 70-80% reduction in test code volume

2. Powerful Property Access

• Nested objects: "address{street,city}"
• Collections and arrays: "items{0{name},1{name}}" or "items{#{name}}"
• Maps: "config{host,port}"
• Universal size properties: "length" and "size"

3. Flexible Comparison

• String conversion with custom formatters
• Predicate-based validation
• Direct object equality
• Custom property extractors

4. Type Safety

• Comprehensive error messages with clear property paths
• Compile-time safety for property names
• Runtime validation with helpful diagnostics

Proposed API

public class Assertions {
    // Core BCT methods
    public static void assertBean(Object actual, String properties, String expected);
    public static void assertBeans(Collection<?> actual, String properties, String... expected);
    public static void assertList(Object actual, Object... expected);
    public static void assertMapped(Object actual, BiFunction<Object, String, Object> mapper, 
                                   String properties, String expected);
    
    // Additional utility methods
    public static void assertContains(String substring, Object actual);
    public static void assertContainsAll(Object actual, String... substrings);
    public static void assertEmpty(Object actual);
    public static void assertNotEmpty(Object actual);
    public static void assertSize(int expected, Object actual);
    public static void assertString(String expected, Object actual);
    public static void assertMatchesGlob(String pattern, Object actual);
}

Real-World Impact

BCT has been successfully deployed in the Apache Juneau project:

• Adoption Rate: 342 out of 658 test files (52%) now use BCT assertions
• Usage Statistics: Over 1,700 BCT assertion calls across the codebase
  • 859 assertBean() calls across 127 files
  • 663 assertList() calls across 69 files
  • 192 assertBeans() calls across 10 files
• Code Reduction: Thousands of lines of verbose property extraction replaced with concise assertions
• Test Clarity: Complex object validation simplified to single-line assertions

Implementation Considerations

1. Backward Compatibility

• All new methods would be additions to the existing Assertions class
• No changes to existing JUnit APIs
• Optional dependency on reflection (already used by JUnit)

2. Performance

• Minimal overhead compared to traditional assertions
• Property extraction is cached for repeated access
• Early termination on first failure

3. Extensibility

• Plugin architecture for custom property extractors
• Configurable string converters
• Support for custom comparison logic

4. Error Messages

• Clear, actionable error messages
• Property path highlighting
• Expected vs actual value comparison

Benefits to JUnit Community

1. Improved Developer Experience: Less verbose, more readable tests
2. Reduced Maintenance: Fewer lines of code to maintain
3. Better Test Coverage: Easier to test complex objects thoroughly
4. Consistent API: Follows JUnit's existing assertion patterns
5. Proven Technology: Already battle-tested in production codebases

---

Check out the README.MD file on my GitHub repo jamesbognar/bean-centric-testing for more examples, complete javadocs, and documentation.

I'd be thrilled to discuss this proposal further and provide additional details or examples as needed.

[mpkorstanje]

I propose adding Bean-Centric Testing (BCT) capabilities to JUnit's existing Assertions API.

Hi, I'm not part of the JUnit team, but if you look through the issues you'll see that JUnit team intends for the Assertions class to provide a basic set of assertions. And as stated in the User Guide, they recommend that users use a more powerful assertion library if Assertions doesn't meet their specific needs.

With that in mind, I don't think your proposal will be accepted.

[scordio]

AssertJ with value extraction is already very close to this proposal.

For example, the two solution examples can be written as:

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

@Test
void testUser() {
    User user = new User(...);
    
    // Test multiple properties at once
    assertThat(user)
        .extracting("name", "age", "active", "address.street", "address.city", "address.state")
        .containsExactly("Alice", 25, true, "123 Main St", "Springfield", "IL");
}

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

@Test
void testUser() {
    List<User> users = List.of(new User(...), ...);
    
    // Test multiple beans at once
    assertThat(users)
        .extracting("name", "age", "active", "address.street", "address.city", "address.state")
        .containsExactly(
            tuple("Alice", 25, true, "123 Main St", "Springfield", "IL"),
            tuple("Bob", 30, false, "10 Evergreen Way", "Springfield", "IL"));
}