Test Utilities Overview
Intended Audience:
Technical User
Author:
Kirill Gaiduk
Changed on:
6 Nov 2026
Overview
The`util-test` library is a comprehensive collection of utility functions, mock objects, and executors designed to minimize the overhead and complexity of testing your Fluent Commerce rules.PrerequisitesThese articles assumes you're familiar with:- Java
- Maven
- JUnit
Key points
`RuleExecutor`: The primary tool for unit testing a single rule in isolation.`WorkflowExecutor`: An advanced executor for integration testing an entire workflow from a JSON definition.`RuleContextGenerator`: The underlying builder for creating the mock`Context`, allowing you to define the event, entity, properties, and mock API responses for your test.`MockApiClient`: A critical component for providing predefined GraphQL responses, enabling you to test how your rule handles different API outcomes without making live calls.`TestActions`: A helper object that captures all actions your rule performs and provides fluent assertions (e.g.,`sendEvent().assertCount(1)`) to easily verify the results.
Value Proposition
- Test Logic, Not the Platform: The utilities allow you to focus your tests on your rule's specific business logic, rather than on the intricacies of the platform's execution environment.
- Fast and Isolated Tests: Because the tests run entirely in-memory with a mock environment, they are extremely fast and can be run as part of any standard CI/CD pipeline without needing a live Fluent instance.
- Readable and Maintainable Tests: The builder-style pattern (e.g.,
`RuleExecutor.of(...).withProp(...).withEvent(...)`) leads to tests that are easy to read and understand, following the popular Arrange-Act-Assert pattern. - Full Coverage: With tools to mock events, entities, rule properties, and API calls, you can create test cases for both success and failure scenarios, helping ensure your rules behave correctly under various conditions.
Explanation through an Example
The following Rule was written to send an Event with a specified name when a Property of a`RubixEntity` is less than a given value.Features
Here is a collection of common scenarios for the Test Utility methods usage:Retrieving a single variable from an Apollo mutation as a POJO
To retrieve a single variable from an Apollo mutation as a POJO for test assertions, use the`ApolloUtils.getMutationVariable` method:This is particularly useful in executor-based tests, as it’s often the only variable in the mutation, making it easy to assert outcomes.Retrieving multiple variables from an Apollo mutation as a POJO
To retrieve variables from an Apollo mutation as a POJO for test assertions, use the`ApolloUtils.getMutationVariables` method:Retrieving variables from an Apollo mutation as a JsonNode
Alternatively, you can retrieve the variables from an Apollo mutation as a`JsonNode` for test assertions, using the `ApolloUtils.getMutationVariables` method:Getting the Class object for all the Rules of the project
To build the`RuleRepository` before test executions or check rule metadata (such as enforcing naming standards), use the `TestUtils.gatherRules` method:Creating an Event with default values
To create an event with default values for unit tests, use the`TestUtils.eventWithDefaults` method:Creating an Event with some sensible default values
To create an event with sensible default values for unit tests, use the`TestUtils.eventWithDefaults` method.Creating a RubixEntity to match the Event
To create a`RubixEntity` with all the necessary fields for testing Orchestration and matching the event, use the `TestUtils.entityFromEvent` method:Loading a Workflow from a JSON file
To load a workflow from a JSON file, use the`TestUtils.loadWorkflowFromFile` method:Getting a Rule name from a full namespace name
To retrieve a rule name from a full namespace name, use the`TestUtils.getRuleName` method:Validating Events against @RuleInfo.produces annotation
To validate events against the`@RuleInfo.produces` annotation, use the `TestUtils.validateEventAgainstProduces` method:Each produced event is checked against the rule's `@EventInfo` declarations the way the platform reads them:- A blank
`entityType`or`entitySubtype`matches any value, including none. Rules that send events to another entity can leave the subtype blank `EVENT_TYPE`,`EVENT_SUBTYPE`and the`{event.entityType}`,`{event.entitySubtype}`and`{event.status}`templates resolve against the event that triggered the rule. In a workflow, that's the event of the current step. If that event has no value, the produced event must have none either- Any other value is rendered against the rule's props, for example
`{eventName}` - A blank status or
`EVENT_STATUS`matches any status
Executors
Executors handle the:- Setup
- Execution
- And validation of tests
- Managing the flow of test execution
- Ensuring isolation
- And handling dependencies
