Package com.opencqrs.framework.command

Interface GivenDsl<C extends Command>

Type Parameters:
C - the command type
All Known Subinterfaces:
GivenDsl.Initial<C>
public interface GivenDsl<C extends Command>
Fluent API for configuring test preconditions before command execution. Methods in this interface allow specifying the initial state of the instance through various means:

Events provided through this interface are processed by the configured StateRebuildingHandlerDefinitions to build the instance state. These events are not included in the captured events that can be asserted in the Expect phase - only events published by the command under test are capturable.

The interface supports method chaining, allowing multiple setup operations to be combined fluently: 

 fixture.given()
     .time(Instant.parse("2024-01-01T10:00:00Z"))
     .usingSubject("/orders/123")
     .event(e -> e.payload(new OrderCreatedEvent(...)))
     .timeDelta(Duration.ofHours(1))
     .event(e -> e.payload(new OrderConfirmedEvent(...)))
     .when(new ShipOrderCommand(...))
     .succeeds();
See Also:

  • Method Details

    • time

      GivenDsl<C> time(Instant time)
      Sets the timestamp for subsequent events added via events(Object...) or event(Consumer). This timestamp is applied to the raw event's time passed to StateRebuildingHandlers.

      If not specified, Instant.now() is used as the default timestamp.

      Parameters:
      time - the timestamp to use for subsequent events
      Returns:
      this for method chaining
      See Also:

    • timeDelta

      GivenDsl<C> timeDelta(Duration delta)
      Advances the current timestamp by the specified duration for subsequent events. This is useful for simulating events that occurred at different points in time relative to each other.

      Example: 

       fixture.given()
     .time(Instant.parse("2024-01-01T10:00:00Z"))
     .event(e -> e.payload(new OrderPlacedEvent(...)))
     .timeDelta(Duration.ofHours(2))
     .event(e -> e.payload(new PaymentReceivedEvent(...)))  // at 12:00:00
     .when(...)
      Parameters:
      delta - the duration to add to the current timestamp
      Returns:
      this for method chaining
      See Also:

    • state

      GivenDsl<C> state(@Nullable Object state)
      Directly sets the instance state without processing any events. This bypasses the StateRebuildingHandlerDefinitions and injects the state directly.

      Use this method when you want to test command behavior against a specific state without setting up the event history that would normally produce that state.

      Note: This only affects preceding stubbings — subsequent events(Object...) or event(Consumer) calls can still be applied. However, if no events are added after this call, no events are present in the instance's history, which may affect precondition checks that rely on event existence (e.g., Command.SubjectCondition.EXISTS).

      Parameters:
      state - the state object to inject
      Returns:
      this for method chaining

    • events

      GivenDsl<C> events(Object... events)
      Adds multiple event payloads to be processed by StateRebuildingHandlerDefinitions. Each event payload is wrapped with default values for subject, time, id, and meta-data.

      The events are processed in the order provided, with each event potentially modifying the instance state through its corresponding StateRebuildingHandler.

      For more control over individual event attributes (subject, time, meta-data), use event(Consumer) instead.

      Parameters:
      events - the event payloads to add
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if no StateRebuildingHandlerDefinition matches an event's type
      See Also:

    • event

      GivenDsl<C> event(Consumer<EventSpecifierDsl> event)
      Adds a single event with full control over its attributes using the EventSpecifierDsl fluent API. This method allows specifying the event payload along with optional attributes like subject, time, id, and meta-data.

      Example: 

       fixture.given()
     .event(e -> e
         .payload(new OrderPlacedEvent(...))
         .subject("/orders/123")
         .time(Instant.parse("2024-01-01T10:00:00Z"))
         .metaData(Map.of("correlationId", "abc-123")))
     .when(...)
      Parameters:
      event - a consumer that configures the event via EventSpecifierDsl
      Returns:
      this for method chaining
      Throws:
      IllegalArgumentException - if EventSpecifierDsl.payload(Object) is not called
      IllegalArgumentException - if no StateRebuildingHandlerDefinition matches the event's payload type
      See Also:

    • command

      <CMD extends Command> GivenDsl<C> command(CommandHandlingTestFixture<CMD> fixture, CMD command)
      Executes another command using the specified fixture and applies its captured events as given events for this test. This is useful for setting up complex preconditions that result from prior command executions.

      The events published by the given command are processed by this fixture's StateRebuildingHandlerDefinitions to build the instance state.

      Note: The subject specified via usingSubject(String) does not apply to events from the given command - they retain their original subjects as published by the command handler.

      Type Parameters:
      CMD - the command type
      Parameters:
      fixture - the fixture to execute the command with
      command - the command to execute
      Returns:
      this for method chaining
      Throws:
      AssertionError - if the given command execution fails

    • command

      <CMD extends Command> GivenDsl<C> command(CommandHandlingTestFixture<CMD> fixture, CMD command, Map<String,?> metaData)
      Executes another command with meta-data using the specified fixture and applies its captured events as given events for this test.
      Type Parameters:
      CMD - the command type
      Parameters:
      fixture - the fixture to execute the command with
      command - the command to execute
      metaData - the meta-data to pass to the command handler
      Returns:
      this for method chaining
      Throws:
      AssertionError - if the given command execution fails
      See Also:

    • usingSubject

      GivenDsl<C> usingSubject(String subject)
      Sets the subject to use for subsequent events added via events(Object...) or event(Consumer). This subject is used unless explicitly overridden per event using EventSpecifierDsl.subject(String).

      Example: 

       fixture.given()
     .usingSubject("/orders/123")
     .events(new OrderPlacedEvent(...), new PaymentReceivedEvent(...))  // both use /orders/123
     .usingSubject("/orders/456")
     .events(new OrderPlacedEvent(...))  // uses /orders/456
     .when(...)
      Parameters:
      subject - the subject to use for subsequent events
      Returns:
      this for method chaining
      See Also:

    • usingCommandSubject

      GivenDsl<C> usingCommandSubject()
      Sets the subject for subsequent events to the command's subject (as returned by Command.getSubject()). This is a convenience method equivalent to usingSubject(command.getSubject()).
      Returns:
      this for method chaining
      See Also:

    • when

      ExpectDsl.Outcome when(C command)
      Completes the Given phase and transitions to the When phase by executing the specified command. The command is executed against the state built from the given events (or injected directly via state(Object)).
      Parameters:
      command - the command to execute
      Returns:
      an ExpectDsl.Outcome to specify expected outcomes

    • when

      ExpectDsl.Outcome when(C command, Map<String,?> metaData)
      Completes the Given phase and transitions to the When phase by executing the specified command with meta-data. The meta-data is passed to the command handler if it accepts meta-data (e.g., CommandHandler.ForInstanceAndCommandAndMetaData).
      Parameters:
      command - the command to execute
      metaData - the meta-data to pass to the command handler
      Returns:
      an ExpectDsl.Outcome to specify expected outcomes