Read Module

RECORDO

The Recordo Read module is designed to enhance the testing experience in JUnit. This module introduces flexible and convenient ways to create test objects by seamlessly integrating external JSON data.

If the specified JSON file is missing, Recordo will automatically create a new file with an object structure and populate it with random values. This feature streamlines test preparation, allowing developers to focus on establishing anticipated values without the need for manual file creation.

The module provides three convenient approaches for reading objects:

Interface-based Object Factory

Parameterized Object Factory

Direct Object Creation

Annotation Parameters

The @Read annotation has two parameters:

Name	Type	Description
value	String	Path to JSON file
objectMapper	String	Name of ObjectMapper bean or test class field

Interface-based Object Factory

Developers can define interfaces with the @RecordoObjectFactory annotation to instruct Recordo on how to create objects. Here's an example interface:

The Interface-based Object Factories feature is built upon the Cariochi Objecto library, inheriting all the capabilities of Objecto while expanding its functionality. Additionally, it introduces the usage of the @Read annotation for factory methods, altering the behavior of the method by transforming it from generating a random object on each invocation to generating it only upon the first usage and subsequently persisting it to a file.

For detailed information and documentation regarding the Objecto library, please refer to the Objecto documentation.

Declaration

@RecordoObjectFactory
public interface LogRecordObjectFactory {

    // Factory methods with @Read annotation
    @Read("/messages/log.json") 
    LogRecord getLogRecord();
    
    @Read("/messages/log.json") 
    LogRecord getLogRecord(@Modifier("id") Long id);
    
    @Read("/messages/logs.json") 
    List<LogRecord> getLogRecords();
    
    @Read("/files/output.zip")
    byte[] getOutputFile();
  
    // Modification methods without @Read annotation
    @Modifier("id")
    LogRecordObjectFactory withId(Long id);
    
    @Modifier("responses[0].status")
    LogRecordObjectFactory withFirstResponseStatus(ResponseStatus status);
    
    @Modifier("responses[*].status")
    LogRecordObjectFactory withAllResponseStatuses(ResponseStatus status);
    
}

Factory Methods:

Methods annotated with @Read represent factory methods for creating objects, specifying the JSON file paths and parameters.

• Return Type: The factory method's return type should be the object you want to create.

• @Read Annotation: Apply the @Read annotation to specify the path to the JSON file containing the object's data.

• Parameters: If the object creation involves parameters, use method parameters annotated with @Modifier to specify the paths within the object that need to be modified.

Modification Methods:

Methods annotated with @Modifier serve as modification methods, allowing developers to alter the factory object with specific parameters.

• Return Type: The return type should be the same factory interface (LogRecordObjectFactory in this case).

• @Modifier Annotation: Use the @Modifier annotation on methods to specify the paths within the object that need to be modified.

Usage

@ExtendWith(RecordoExtension.class)
class MyTest {

    private TestDtoObjectFactory objectFactory = Recordo.create(TestDtoObjectFactory.class);
    
    @Test
    void createLogRecord() {
    
        // Use factory methods to create LogRecord objects
        LogRecord log = factory.getLogRecord();
        
        // ...

        // Create a new LogRecord using the modification methods
        LogRecord modifiedLog = factory
                .withId(123)
                .withFirstResponseStatus(ResponseStatus.SUCCESS)
                .getLogRecord()
        
        // ...
        
        // Use factory methods to read file content
        byte[] fileContent = factory.getOutputFile();
        
        // ...
        
    }
}

Parameterized Object Factory

Developers can use the ObjectFactory class along with the @Read annotation to create objects with specified parameters.

Usage example

@Read("/messages/log.json") 
private ObjectFactory<LogRecord> logFactory;

@Test
void shouldGetLogStats() {
    // Given
    List<LogRecord> logs = List.of(
    
        // creates a LogRecord object with default values
        logFactory.create(),
        
        // creates a LogRecord object with the "id" field set to "TEST-100"
        logFactory.with("id", "TEST-100").create(),
        
        // creates a LogRecord object with the status of the second response set to FAILED
        logFactory.with("responses[1].status", ResponseStatus.FAILED).create(),
        
        // creates a LogRecord object with an empty list for the "responses" field
        logFactory.with("responses", emptyList()).create()
        
    );
    
    // Perform additional test logic with the created LogRecord objects
    // ...
}

How it Works

1. @Read Annotation: Annotate a field of type ObjectFactory<T> with the @Read annotation, where T is the type of object to be created.

2. ObjectFactory Methods:

   • create(): Create an object using the default values specified in the associated JSON file.

   • with(String key, Object value): Specify a key-value pair to modify the object being created. The key uses a JSONPath-like syntax.

Direct Object Creation

Among its features, the module offers a straightforward method for creating objects directly within test methods using the @Read annotation.

Developers can use the @Read annotation on test methods to effortlessly create objects with default values, simplifying the testing process. This method is suitable for scenarios where customization or modification of object values is not required.

Usage Examples

In the given examples, the test methods effortlessly create objects using the data from the JSON file. Developers can focus on writing test logic without additional setup or object instantiation.

Single object

@Test
void should_create_book(
    @Read("/books/book.json") Book book
) {
    ...
}

List of objects

@Test
void should_read_books(
    @Read("/books/books.json") List<Book> books
) {
    ...
}

Strings

@Test
void should_parse_string(
    @Read("/books/text.txt") String string
) {
    ...
}

Bytes

@Test
void should_upload_zip_archive(
    @Read("/books/books.zip") byte[] content
) {
    ...
}

How it Works

• @Read Annotation: Apply the @Read annotation to a method parameter to signify that the associated JSON file should be used to create an object.

• Default Object Creation: The @Read annotation, when applied directly to a test method parameter, signals Recordo to create an object with default values specified in the associated JSON file.