Fluent Commerce Logo
Docs

Test Utilities Overview

Essential knowledgeCore knowledge to understand Fluent Commerce

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
In a workflow test, the context collects the events of every rule. To check a rule only against the events it produced, pass the number of events that existed before the rule ran:

Executors

Executors handle the:
  • Setup 
  • Execution 
  • And validation of tests
Particularly, when working with complex systems like Rule-based engines or Workflows. Executors help to make testing more efficient, reliable, and maintainable by:
  • Managing the flow of test execution
  • Ensuring isolation
  • And handling dependencies