stepper_motor 0.1.18 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b4b58accbed9841696bb2d0296335863b71b26b9a33a457028cc4c834ec1fec
-  data.tar.gz: c0f6e6fda44e9d8c7808743e425a059e2a8c1196fc4fcd1fcb6240521d8b5bbf
+  metadata.gz: b27839f0ee5621c5da6e694e2ee3e790f9f4b96383d05bf5ebbfc0a7ddf99928
+  data.tar.gz: 60bf0af4da25cf6f6c7ef2d835bcbd717ec662215da2bf14aea50da6949dc316
 SHA512:
-  metadata.gz: 2b3aa12d9c21cf9f5e8246bce6fa8d88bfaeea046ad434ada641c7c0e1ce62cba173584fd4c836c6e70d98468f1ebc70ce93ea0246fb40ed3992ea45a97328f2
-  data.tar.gz: ae3fb23fc0f81f3a92e63abf6a6b444a801421c388ed3ef3a7e6ff23562a74bca218d3b257cb7a6dfa896e383d4e093bd990f67209f4ca41936598db91e680a9
+  metadata.gz: 275d2ba0cc4ff6710f3d87189853f9836a767bfea6e56ac6a635135f7aa8e8043038f3cff1b28fd3b548ea06dd65392b37adb4f6d5aa4a310e7e7d95f53cb444
+  data.tar.gz: dd3f67919bf6daca240b6eb32d4c83ca720fc8ae9f2b7e9c571a7913e2e640840c7f1dc4c497f5114f14694b0a413ccdba758330c418844a3adc77b5312289ce

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.1.19] - 2025-06-25
+
+- With `speedrun_journey`, allow configuring the maximum number of steps - for testing journeys
+  that iterate or reattempt a lot.
+- With `speedrun_journey`, use time travel by default
+- Allow steps to be placed relative to other steps using `before_step:` and `after_step:` keyword arguments
+- Use just-in-time index lookup instead of `Step#seq`
+
 ## [0.1.18] - 2025-06-20
 
 - Add `cancel_if` at Journey class level for blanket journey cancellation conditions. This makes it very easy to abort journeys across multiple steps.

data/lib/stepper_motor/journey/flow_control.rb

@@ -58,8 +58,7 @@ module StepperMotor::Journey::FlowControl
           return
         end
 
-        current_step_seq = current_step_definition.seq
-        next_step_definition = step_definitions[current_step_seq + 1]
+        next_step_definition = self.class.step_definitions_following(current_step_definition).first
 
         if next_step_definition
           # There are more steps after this one - schedule the next step

data/lib/stepper_motor/journey.rb

@@ -79,7 +79,13 @@ module StepperMotor
     #    as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to
     #    be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at`
     #    attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition.
-    #    Mutually exclusive with `wait:`
+    #    Mutually exclusive with `wait:`.
+    # @param before_step[String,Symbol,nil] the name of the step before which this step should be inserted.
+    #    This allows you to control the order of steps by inserting a step before a specific existing step.
+    #    The step name can be provided as a string or symbol. Mutually exclusive with `after_step:`.
+    # @param after_step[String,Symbol,nil] the name of the step after which this step should be inserted.
+    #    This allows you to control the order of steps by inserting a step after a specific existing step.
+    #    The step name can be provided as a string or symbol. Mutually exclusive with `before_step:`.
     # @param on_exception[Symbol] See {StepperMotor::Step#on_exception}
     # @param skip_if[TrueClass,FalseClass,Symbol,Proc] condition to check before performing the step. If a symbol is provided,
     #    it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context.
@@ -89,7 +95,7 @@ module StepperMotor
     #    The step will be performed if the condition returns a truthy value. and skipped otherwise. Inverse of `skip_if`.
     # @param additional_step_definition_options[Hash] Any remaining options get passed to `StepperMotor::Step.new` as keyword arguments.
     # @return [StepperMotor::Step] the step definition that has been created
-    def self.step(name = nil, wait: nil, after: nil, **additional_step_definition_options, &blk)
+    def self.step(name = nil, wait: nil, after: nil, before_step: nil, after_step: nil, **additional_step_definition_options, &blk)
       # Handle the if: alias for backward compatibility
       if additional_step_definition_options.key?(:if) && additional_step_definition_options.key?(:skip_if)
         raise StepConfigurationError, "Either skip_if: or if: can be specified, but not both"
@@ -99,11 +105,31 @@ module StepperMotor
         additional_step_definition_options[:skip_if] = StepperMotor::Conditional.new(additional_step_definition_options.delete(:if), negate: true)
       end
 
-      wait = if wait && after
+      # Validate before_step and after_step parameters
+      if before_step && after_step
+        raise StepConfigurationError, "Either before_step: or after_step: can be specified, but not both"
+      end
+
+      # Validate that referenced steps exist
+      if before_step
+        referenced_step = lookup_step_definition(before_step)
+        unless referenced_step
+          raise StepConfigurationError, "Step named #{before_step.inspect} not found for before_step: parameter"
+        end
+      end
+
+      if after_step
+        referenced_step = lookup_step_definition(after_step)
+        unless referenced_step
+          raise StepConfigurationError, "Step named #{after_step.inspect} not found for after_step: parameter"
+        end
+      end
+
+      wait = if wait && after&.respond_to?(:to_f)
         raise StepConfigurationError, "Either wait: or after: can be specified, but not both"
-      elsif !wait && !after
+      elsif !wait && (!after || !after.respond_to?(:to_f))
         0
-      elsif after
+      elsif after&.respond_to?(:to_f)
         accumulated = step_definitions.map(&:wait).sum
         after - accumulated
       else
@@ -127,12 +153,27 @@ module StepperMotor
       raise StepConfigurationError, "Step named #{name.inspect} already defined" if known_step_names.include?(name)
 
       # Create the step definition
-      StepperMotor::Step.new(name: name, wait: wait, seq: step_definitions.length, **additional_step_definition_options, &blk).tap do |step_definition|
-        # As per Rails docs: you need to be aware when using class_attribute with mutable structures
-        # as Array or Hash. In such cases, you don't want to do changes in place. Instead use setters.
-        # See https://apidock.com/rails/v7.1.3.2/Class/class_attribute
+      step_definition = StepperMotor::Step.new(name: name, wait: wait, **additional_step_definition_options, &blk)
+
+      # Determine insertion position based on before_step or after_step parameters
+      if before_step
+        target_step = lookup_step_definition(before_step)
+        target_index = step_definitions.index(target_step)
+        new_step_definitions = step_definitions.dup
+        new_step_definitions.insert(target_index, step_definition)
+        self.step_definitions = new_step_definitions
+      elsif after_step
+        target_step = lookup_step_definition(after_step)
+        target_index = step_definitions.index(target_step)
+        new_step_definitions = step_definitions.dup
+        new_step_definitions.insert(target_index + 1, step_definition)
+        self.step_definitions = new_step_definitions
+      else
+        # Default behavior: append to the end
         self.step_definitions = step_definitions + [step_definition]
       end
+
+      step_definition
     end
 
     # Returns the `Step` object for a named step. This is used when performing a step, but can also
@@ -144,6 +185,16 @@ module StepperMotor
       step_definitions.find { |d| d.name.to_s == by_step_name.to_s }
     end
 
+    # Returns all step definitions that follow the given step in the journey
+    #
+    # @param step_definition[StepperMotor::Step] the step to find the following steps for
+    # @return [Array<StepperMotor::Step>] the following steps, or empty array if this is the last step
+    def self.step_definitions_following(step_definition)
+      current_index = step_definitions.index(step_definition)
+      return [] unless current_index
+      step_definitions[(current_index + 1)..]
+    end
+
     # Alias for the class attribute, for brevity
     #
     # @see Journey.step_definitions
@@ -292,8 +343,7 @@ module StepperMotor
         ready!
       elsif @skip_current_step
         # The step asked to be skipped
-        current_step_seq = @current_step_definition.seq
-        next_step_definition = step_definitions[current_step_seq + 1]
+        next_step_definition = self.class.step_definitions_following(@current_step_definition).first
 
         if next_step_definition
           # There are more steps after this one - schedule the next step
@@ -309,7 +359,7 @@ module StepperMotor
       elsif finished?
         logger.info { "was marked finished inside the step" }
         update!(previous_step_name: current_step_name, next_step_name: nil)
-      elsif (next_step_definition = step_definitions[@current_step_definition.seq + 1])
+      elsif (next_step_definition = self.class.step_definitions_following(@current_step_definition).first)
         logger.info { "will continue to #{next_step_definition.name}" }
         set_next_step_and_enqueue(next_step_definition)
         ready!
@@ -337,8 +387,7 @@ module StepperMotor
 
     # @return [ActiveSupport::Duration]
     def time_remaining_until_final_step
-      current_step_seq = @current_step_definition&.seq || -1
-      subsequent_steps = step_definitions.select { |definition| definition.seq > current_step_seq }
+      subsequent_steps = @current_step_definition ? self.class.step_definitions_following(@current_step_definition) : step_definitions
       seconds_remaining = subsequent_steps.map { |definition| definition.wait.to_f }.sum
       seconds_remaining.seconds # Convert to ActiveSupport::Duration
     end

data/lib/stepper_motor/step.rb

@@ -13,9 +13,6 @@ class StepperMotor::Step
   # @return [Numeric,ActiveSupport::Duration] how long to wait before performing the step
   attr_reader :wait
 
-  # @private
-  attr_reader :seq
-
   # Creates a new step definition
   #
   # @param name[String,Symbol] the name of the Step
@@ -30,11 +27,10 @@ class StepperMotor::Step
   #   it will be used directly. If nil is provided, it will be treated as false. If a symbol is provided,
   #   it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context.
   #   The step will only be performed if the condition returns a truthy value.
-  def initialize(name:, seq:, on_exception: :pause!, wait: 0, skip_if: false, &step_block)
+  def initialize(name:, on_exception: :pause!, wait: 0, skip_if: false, &step_block)
     @step_block = step_block
     @name = name.to_s
     @wait = wait
-    @seq = seq
     @on_exception = on_exception # TODO: Validate?
     @skip_if_condition = StepperMotor::Conditional.new(skip_if)
   end

data/lib/stepper_motor/test_helper.rb

@@ -8,14 +8,39 @@ module StepperMotor::TestHelper
   # has neither canceled nor finished, an exception will be raised.
   #
   # @param journey[StepperMotor::Journey] the journey to speedrun
+  # @param time_travel[Boolean] whether to use ActiveSupport time travel (default: true)
+  #   Note: When time_travel is true, this method will permanently travel time forward
+  #   and will not reset it back to the original time when the method exits.
+  # @param maximum_steps[Symbol,Integer] how many steps can we take until we assume the
+  #   journey has hung and fail the test. Default value is :reasonable, which is 10x the
+  #   number of steps. :unlimited allows "a ton", but can make your test hang if your logic
+  #   lets a step reattempt indefinitely
   # @return void
-  def speedrun_journey(journey)
+  def speedrun_journey(journey, time_travel: true, maximum_steps: :reasonable)
     journey.save!
-    n_steps = journey.step_definitions.length
+    n_steps = case maximum_steps
+    when :reasonable
+      journey.step_definitions.length * 10
+    when :unlimited
+      0xFFFF
+    when Integer
+      maximum_steps
+    else
+      raise ArgumentError, "maximum_steps may be :reasonable, :unlimited or an Integer, was #{maximum_steps.inspect}"
+    end
+
     n_steps.times do
       journey.reload
       break if journey.canceled? || journey.finished?
-      journey.update(next_step_to_be_performed_at: Time.current)
+
+      if time_travel
+        # Use time travel to move slightly ahead of the time when the next step should be performed
+        next_step_time = journey.next_step_to_be_performed_at
+        travel_to(next_step_time + 1.second)
+      else
+        # Update the journey's timestamp to bypass waiting periods
+        journey.update(next_step_to_be_performed_at: Time.current)
+      end
       journey.perform_next_step!
     end
     journey.reload

data/lib/stepper_motor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StepperMotor
-  VERSION = "0.1.18"
+  VERSION = "0.1.19"
 end

data/manual/MANUAL.md

@@ -27,7 +27,9 @@ So, stepper_motor aims to give you "just enough of Temporal-like functionality"
 
 ## A brief introduction to stepper_motor
 
-stepper_motor is built around the concept of a `Journey`. A `Journey` [is a sequence of steps happening to a `hero`](https://en.wikipedia.org/wiki/Hero%27s_journey) - once launched, the journey will run until it either finishes or cancels. A `Journey` is just an `ActiveRecord` model, with all the persistence methods you already know and use.
+stepper_motor is built around the concept of a `Journey`. A `Journey` [is a sequence of steps happening to a `hero`](https://en.wikipedia.org/wiki/Hero%27s_journey) - once launched, the journey will run until it either finishes or cancels. But also - a `Journey` is an `ActiveRecord` model, with all the persistence methods you already know and use. Every `Journey` has a speficic identity - its primary key, just like any other database row, and carries state information.
+
+A `Journey` changes states during asynchronous invocations, and can lay dormant for months until the time comes to take the next step.
 
 Steps are defined inside the Journey subclasses as blocks, and they run in the context of that subclass' instance. The following constraints apply:
 
@@ -40,7 +42,7 @@ The `step` blocks get executed in the context of the `Journey` model instance. T
 
 The steps are performed asynchronously, via ActiveJob. When a Journey is created, it gets scheduled for its initial step. The job then gets picked up by the ActiveJob queue worker (whichever you are using) and triggers the step on the `Journey`. If the journey decides to continue to the next step, it schedules another ActiveJob for itself with the step name and other details necessary.
 
-No state is carried inside the job.
+No state is carried inside the job - both the state transition management and the steps are handled by the `Journey` itself.
 
 ## Installation
 
@@ -70,7 +72,7 @@ class SignupJourney < StepperMotor::Journey
   end
 end
 
-class SignupController
+class SignupController < ApplicationController
   def create
     # ...your other business actions
     SignupJourney.create!(hero: current_user)
@@ -371,23 +373,54 @@ step :two do
 end
 ```
 
-You have a `Journey` which is about to start step `one`. When the step gets performed, stepper_motor will do a lookup to find _the next step in order of definition._ In this case the step will be step `two`, so the name of that step will be saved with the `Journey`. Imagine you then edit the code to add an extra step between those:
+Your existing `Journey` is already primed to perform step `two`. However, a `Journey` which is about to perform step `one` will now set `one_bis` as the next step to perform. This allows limited reordering and editing of `Journey` definitions after they have already begun.
+
+### Step ordering with `before_step:` and `after_step:`
+
+You can control the order of steps by inserting them before or after specific existing steps using the `before_step:` and `after_step:` parameters. This is useful when you want to add steps in the middle of a sequence without manually reordering all the steps.
+
+The step names can be provided as strings or symbols, and only one of `before_step:` or `after_step:` can be specified:
 
 ```ruby
-step :one do
-  # perform some action
-end
+class UserOnboardingJourney < StepperMotor::Journey
+  step :send_welcome_email do
+    WelcomeMailer.welcome(hero).deliver_later
+  end
 
-step :one_bis do
-  # some compliance action
-end
+  step :send_premium_offer, after: 2.days do
+    PremiumOfferMailer.exclusive_offer(hero).deliver_later
+  end
 
-step :two do
-  # perform some other action
+  # Insert a compliance check before the premium offer
+  step :compliance_check, before_step: "send_premium_offer" do
+    ComplianceService.verify_eligibility(hero)
+  end
+
+  # Insert a reminder after the welcome email
+  step :send_reminder, after_step: "send_welcome_email", wait: 1.day do
+    ReminderMailer.follow_up(hero).deliver_later
+  end
+
+  step :complete_onboarding, after: 7.days do
+    hero.update!(onboarding_completed_at: Time.current)
+  end
 end
 ```
+This approach is particularly useful when extending journey classes through inheritance, as you can insert steps relative to steps defined in the parent class.
+Should you ever get confused and find yourself in need to retrace your steps, call `UserOnboardingJourney.step_definitions.map(&:name)`:
 
-Your existing `Journey` is already primed to perform step `two`. However, a `Journey` which is about to perform step `one` will now set `one_bis` as the next step to perform. This allows limited reordering and editing of `Journey` definitions after they have already begun.
+```ruby
+UserOnboardingJourney.step_definitions.map(&:name)
+# => ["send_welcome_email", "send_reminder", "compliance_check", "send_premium_offer", "complete_onboarding"]
+```
+
+This will show you the exact order in which steps will be executed. In this case:
+
+1. `send_welcome_email`
+2. `send_reminder` (inserted after `send_welcome_email`)
+3. `compliance_check` (inserted before `send_premium_offer`)
+4. `send_premium_offer`
+5. `complete_onboarding`
 
 ### Using instance methods as steps
 
@@ -648,6 +681,25 @@ end
 
 The `wait:` parameter defines the amount of time computed **from the moment the Journey gets created or the previous step is completed.**
 
+## Execution model: assume that everything is async
+
+stepper_motor is built on the assumption that steps should be able to execute asynchronously. This is a **very important** design trait which has a number of implications:
+
+* You will almost never have the same `self` for a Journey between multiple steps
+* Any instance variables you set inside a step will get discarded and will not be available in a subsequent step
+* Any step may want to reattempt itself at an arbitrary point in the future. Any stack variables or local state will be discarded.
+
+This is deliberate and intentional. At the moment, stepper_motor does not have any built-in primitives for executing multiple steps inline. The `speedrun_journey`
+helper used in tests is going to `reload` your Journey between step entries, to allow for any state changes to be blown away - but it is not going to reset any instance variables.
+
+A good way to think about it is: every step execution happens:
+
+* On a different machine
+* In a different thread
+* In a different database transaction
+* In the context of a different Journey instance
+* Potentially - after a long time has passed since the previous attempt or previous step
+
 ## Journey states
 
 The Journeys are managed using a state machine, which stepper_motor completely coordinates for you. The states are as follows:

data/rbi/stepper_motor.rbi

@@ -2,7 +2,7 @@
 # StepperMotor is a module for building multi-step flows where steps are sequential and only
 # ever progress forward. The building block of StepperMotor is StepperMotor::Journey
 module StepperMotor
-  VERSION = T.let("0.1.18", T.untyped)
+  VERSION = T.let("0.1.19", T.untyped)
   PerformStepJobV2 = T.let(StepperMotor::PerformStepJob, T.untyped)
   RecoverStuckJourneysJobV1 = T.let(StepperMotor::RecoverStuckJourneysJob, T.untyped)
 
@@ -24,7 +24,6 @@ module StepperMotor
   # array of the Journey subclass. When the step gets performed, the block passed to the
   # constructor will be instance_exec'd with the Journey model being the context
   class Step
-    # sord omit - no YARD type given for "seq:", using untyped
     # sord warn - ActiveSupport::Duration wasn't able to be resolved to a constant in this project
     # Creates a new step definition
     # 
@@ -38,14 +37,13 @@ module StepperMotor
     sig do
       params(
         name: T.any(String, Symbol),
-        seq: T.untyped,
         on_exception: Symbol,
         wait: T.any(Numeric, ActiveSupport::Duration),
         skip_if: T.any(TrueClass, FalseClass, NilClass, Symbol, Proc),
         step_block: T.untyped
       ).void
     end
-    def initialize(name:, seq:, on_exception: :pause!, wait: 0, skip_if: false, &step_block); end
+    def initialize(name:, on_exception: :pause!, wait: 0, skip_if: false, &step_block); end
 
     # Checks if the step should be skipped based on the skip_if condition
     # 
@@ -72,10 +70,6 @@ module StepperMotor
     sig { returns(T.any(Numeric, ActiveSupport::Duration)) }
     attr_reader :wait
 
-    # sord omit - no YARD type given for :seq, using untyped
-    sig { returns(T.untyped) }
-    attr_reader :seq
-
     class MissingDefinition < NoMethodError
     end
   end
@@ -139,7 +133,11 @@ module StepperMotor
     # 
     # _@param_ `wait` — the amount of time this step should wait before getting performed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time, and the `next_step_to_be_performed_at` attribute will be set to the current time plus the wait duration. Mutually exclusive with `after:`
     # 
-    # _@param_ `after` — the amount of time this step should wait before getting performed including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition. Mutually exclusive with `wait:`
+    # _@param_ `after` — the amount of time this step should wait before getting performed including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition. Mutually exclusive with `wait:`.
+    # 
+    # _@param_ `before_step` — the name of the step before which this step should be inserted. This allows you to control the order of steps by inserting a step before a specific existing step. The step name can be provided as a string or symbol. Mutually exclusive with `after_step:`.
+    # 
+    # _@param_ `after_step` — the name of the step after which this step should be inserted. This allows you to control the order of steps by inserting a step after a specific existing step. The step name can be provided as a string or symbol. Mutually exclusive with `before_step:`.
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
@@ -155,11 +153,13 @@ module StepperMotor
         name: T.nilable(String),
         wait: T.nilable(T.any(Float, T.untyped, ActiveSupport::Duration)),
         after: T.nilable(T.any(Float, T.untyped, ActiveSupport::Duration)),
+        before_step: T.nilable(T.any(String, Symbol)),
+        after_step: T.nilable(T.any(String, Symbol)),
         additional_step_definition_options: T::Hash[T.untyped, T.untyped],
         blk: T.untyped
       ).returns(StepperMotor::Step)
     end
-    def self.step(name = nil, wait: nil, after: nil, **additional_step_definition_options, &blk); end
+    def self.step(name = nil, wait: nil, after: nil, before_step: nil, after_step: nil, **additional_step_definition_options, &blk); end
 
     # sord warn - "StepperMotor::Step?" does not appear to be a type
     # Returns the `Step` object for a named step. This is used when performing a step, but can also
@@ -169,6 +169,14 @@ module StepperMotor
     sig { params(by_step_name: T.any(Symbol, String)).returns(SORD_ERROR_StepperMotorStep) }
     def self.lookup_step_definition(by_step_name); end
 
+    # Returns all step definitions that follow the given step in the journey
+    # 
+    # _@param_ `step_definition` — the step to find the following steps for
+    # 
+    # _@return_ — the following steps, or empty array if this is the last step
+    sig { params(step_definition: StepperMotor::Step).returns(T::Array[StepperMotor::Step]) }
+    def self.step_definitions_following(step_definition); end
+
     # sord omit - no YARD type given for "by_step_name", using untyped
     # sord omit - no YARD return type given, using untyped
     # Alias for the class method, for brevity
@@ -403,9 +411,13 @@ module StepperMotor
     # 
     # _@param_ `journey` — the journey to speedrun
     # 
+    # _@param_ `time_travel` — whether to use ActiveSupport time travel (default: true) Note: When time_travel is true, this method will permanently travel time forward and will not reset it back to the original time when the method exits.
+    # 
+    # _@param_ `maximum_steps` — how many steps can we take until we assume the journey has hung and fail the test. Default value is :reasonable, which is 10x the number of steps. :unlimited allows "a ton", but can make your test hang if your logic lets a step reattempt indefinitely
+    # 
     # _@return_ — void
-    sig { params(journey: StepperMotor::Journey).returns(T.untyped) }
-    def speedrun_journey(journey); end
+    sig { params(journey: StepperMotor::Journey, time_travel: T::Boolean, maximum_steps: T.any(Symbol, Integer)).returns(T.untyped) }
+    def speedrun_journey(journey, time_travel: true, maximum_steps: :reasonable); end
 
     # Performs the named step of the journey without waiting for the time to perform the step.
     # 

data/sig/stepper_motor.rbs

@@ -22,7 +22,6 @@ module StepperMotor
   # array of the Journey subclass. When the step gets performed, the block passed to the
   # constructor will be instance_exec'd with the Journey model being the context
   class Step
-    # sord omit - no YARD type given for "seq:", using untyped
     # sord warn - ActiveSupport::Duration wasn't able to be resolved to a constant in this project
     # Creates a new step definition
     # 
@@ -35,7 +34,6 @@ module StepperMotor
     # _@param_ `skip_if` — condition to check before performing the step. If a boolean is provided, it will be used directly. If nil is provided, it will be treated as false. If a symbol is provided, it will call the method on the Journey. If a block is provided, it will be executed with the Journey as context. The step will only be performed if the condition returns a truthy value.
     def initialize: (
                       name: (String | Symbol),
-                      seq: untyped,
                       ?on_exception: Symbol,
                       ?wait: (Numeric | ActiveSupport::Duration),
                       ?skip_if: (TrueClass | FalseClass | NilClass | Symbol | Proc)
@@ -62,9 +60,6 @@ module StepperMotor
     # _@return_ — how long to wait before performing the step
     attr_reader wait: (Numeric | ActiveSupport::Duration)
 
-    # sord omit - no YARD type given for :seq, using untyped
-    attr_reader seq: untyped
-
     class MissingDefinition < NoMethodError
     end
   end
@@ -126,7 +121,11 @@ module StepperMotor
     # 
     # _@param_ `wait` — the amount of time this step should wait before getting performed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time, and the `next_step_to_be_performed_at` attribute will be set to the current time plus the wait duration. Mutually exclusive with `after:`
     # 
-    # _@param_ `after` — the amount of time this step should wait before getting performed including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition. Mutually exclusive with `wait:`
+    # _@param_ `after` — the amount of time this step should wait before getting performed including all the previous waits. This allows you to set the wait time based on the time after the journey started, as opposed to when the previous step has completed. When the journey gets scheduled, the triggering job is going to be delayed by this amount of time _minus the `wait` values of the preceding steps, and the `next_step_to_be_performed_at` attribute will be set to the current time. The `after` value gets converted into the `wait` value and passed to the step definition. Mutually exclusive with `wait:`.
+    # 
+    # _@param_ `before_step` — the name of the step before which this step should be inserted. This allows you to control the order of steps by inserting a step before a specific existing step. The step name can be provided as a string or symbol. Mutually exclusive with `after_step:`.
+    # 
+    # _@param_ `after_step` — the name of the step after which this step should be inserted. This allows you to control the order of steps by inserting a step after a specific existing step. The step name can be provided as a string or symbol. Mutually exclusive with `before_step:`.
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
@@ -141,6 +140,8 @@ module StepperMotor
                      ?String? name,
                      ?wait: (Float | untyped | ActiveSupport::Duration)?,
                      ?after: (Float | untyped | ActiveSupport::Duration)?,
+                     ?before_step: (String | Symbol)?,
+                     ?after_step: (String | Symbol)?,
                      **::Hash[untyped, untyped] additional_step_definition_options
                    ) -> StepperMotor::Step
 
@@ -151,6 +152,13 @@ module StepperMotor
     # _@param_ `by_step_name` — the name of the step to find
     def self.lookup_step_definition: ((Symbol | String) by_step_name) -> SORD_ERROR_StepperMotorStep
 
+    # Returns all step definitions that follow the given step in the journey
+    # 
+    # _@param_ `step_definition` — the step to find the following steps for
+    # 
+    # _@return_ — the following steps, or empty array if this is the last step
+    def self.step_definitions_following: (StepperMotor::Step step_definition) -> ::Array[StepperMotor::Step]
+
     # sord omit - no YARD type given for "by_step_name", using untyped
     # sord omit - no YARD return type given, using untyped
     # Alias for the class method, for brevity
@@ -359,8 +367,12 @@ module StepperMotor
     # 
     # _@param_ `journey` — the journey to speedrun
     # 
+    # _@param_ `time_travel` — whether to use ActiveSupport time travel (default: true) Note: When time_travel is true, this method will permanently travel time forward and will not reset it back to the original time when the method exits.
+    # 
+    # _@param_ `maximum_steps` — how many steps can we take until we assume the journey has hung and fail the test. Default value is :reasonable, which is 10x the number of steps. :unlimited allows "a ton", but can make your test hang if your logic lets a step reattempt indefinitely
+    # 
     # _@return_ — void
-    def speedrun_journey: (StepperMotor::Journey journey) -> untyped
+    def speedrun_journey: (StepperMotor::Journey journey, ?time_travel: bool, ?maximum_steps: (Symbol | Integer)) -> untyped
 
     # Performs the named step of the journey without waiting for the time to perform the step.
     # 

data/test/stepper_motor/journey/if_condition_test.rb

@@ -255,7 +255,7 @@ class IfConditionTest < ActiveSupport::TestCase
   end
 
   test "passes skip_if: parameter to step definition" do
-    step_def = StepperMotor::Step.new(name: "a_step", seq: 1, on_exception: :reattempt!)
+    step_def = StepperMotor::Step.new(name: "a_step", on_exception: :reattempt!)
     assert_skip_if_parameter = ->(**options) {
       assert options.key?(:skip_if)
       assert_equal :test_condition, options[:skip_if]

data/test/stepper_motor/journey/step_definition_test.rb

@@ -17,7 +17,7 @@ class StepDefinitionTest < ActiveSupport::TestCase
   end
 
   test "passes any additional options to the step definition" do
-    step_def = StepperMotor::Step.new(name: "a_step", seq: 1, on_exception: :reattempt!)
+    step_def = StepperMotor::Step.new(name: "a_step", on_exception: :reattempt!)
     assert_extra_arguments = ->(**options) {
       assert options.key?(:extra)
       # Return the original definition

data/test/stepper_motor/journey/step_ordering_test.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class StepOrderingTest < ActiveSupport::TestCase
+  include ActiveJob::TestHelper
+  include SideEffects::TestHelper
+  include StepperMotor::TestHelper
+
+  test "allows inserting step before another step using string" do
+    journey_class = create_journey_subclass do
+      step :first do
+        # noop
+      end
+      step :third do
+        # noop
+      end
+      step :second, before_step: "first" do
+        # noop
+      end
+    end
+
+    assert_equal ["second", "first", "third"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "allows inserting step before another step using symbol" do
+    journey_class = create_journey_subclass do
+      step :first do
+        # noop
+      end
+      step :third do
+        # noop
+      end
+      step :second, before_step: :first do
+        # noop
+      end
+    end
+
+    assert_equal ["second", "first", "third"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "allows inserting step after another step using string" do
+    journey_class = create_journey_subclass do
+      step :first do
+        # noop
+      end
+      step :third do
+        # noop
+      end
+      step :second, after_step: "first" do
+        # noop
+      end
+    end
+
+    assert_equal ["first", "second", "third"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "allows inserting step after another step using symbol" do
+    journey_class = create_journey_subclass do
+      step :first do
+        # noop
+      end
+      step :third do
+        # noop
+      end
+      step :second, after_step: :first do
+        # noop
+      end
+    end
+
+    assert_equal ["first", "second", "third"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "allows inserting step at the beginning using before_step" do
+    journey_class = create_journey_subclass do
+      step :second do
+        # noop
+      end
+      step :third do
+        # noop
+      end
+      step :first, before_step: "second" do
+        # noop
+      end
+    end
+
+    assert_equal ["first", "second", "third"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "allows inserting step at the end using after_step" do
+    journey_class = create_journey_subclass do
+      step :first do
+        # noop
+      end
+      step :second do
+        # noop
+      end
+      step :third, after_step: "second" do
+        # noop
+      end
+    end
+
+    assert_equal ["first", "second", "third"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "allows complex step ordering with multiple insertions" do
+    journey_class = create_journey_subclass do
+      step :step_1 do
+        # noop
+      end
+      step :step_4 do
+        # noop
+      end
+      step :step_2, after_step: "step_1" do
+        # noop
+      end
+      step :step_3, before_step: "step_4" do
+        # noop
+      end
+    end
+
+    assert_equal ["step_1", "step_2", "step_3", "step_4"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "raises error when both before_step and after_step are specified" do
+    assert_raises(StepperMotor::StepConfigurationError, "Either before_step: or after_step: can be specified, but not both") do
+      create_journey_subclass do
+        step :first do
+          # noop
+        end
+        step :second, before_step: "first", after_step: "first" do
+          # noop
+        end
+      end
+    end
+  end
+
+  test "raises error when before_step references non-existent step" do
+    assert_raises(StepperMotor::StepConfigurationError, "Step named \"nonexistent\" not found for before_step: parameter") do
+      create_journey_subclass do
+        step :first, before_step: "nonexistent" do
+          # noop
+        end
+      end
+    end
+  end
+
+  test "raises error when after_step references non-existent step" do
+    assert_raises(StepperMotor::StepConfigurationError, "Step named \"nonexistent\" not found for after_step: parameter") do
+      create_journey_subclass do
+        step :first, after_step: "nonexistent" do
+          # noop
+        end
+      end
+    end
+  end
+
+  test "maintains existing after: timing functionality" do
+    journey_class = create_journey_subclass do
+      step :first, after: 5.minutes do
+        # noop
+      end
+      step :second, after: 10.minutes do
+        # noop
+      end
+    end
+
+    assert_equal ["first", "second"], journey_class.step_definitions.map(&:name)
+    assert_equal 5.minutes, journey_class.step_definitions[0].wait
+    assert_equal 5.minutes, journey_class.step_definitions[1].wait
+  end
+
+  test "allows mixing step ordering with timing" do
+    journey_class = create_journey_subclass do
+      step :first, wait: 1.minute do
+        # noop
+      end
+      step :third, after_step: "first" do
+        # noop
+      end
+      step :second, before_step: "third", wait: 2.minutes do
+        # noop
+      end
+    end
+
+    assert_equal ["first", "second", "third"], journey_class.step_definitions.map(&:name)
+    assert_equal 1.minute, journey_class.step_definitions[0].wait
+    assert_equal 2.minutes, journey_class.step_definitions[1].wait
+    assert_equal 0, journey_class.step_definitions[2].wait
+  end
+
+  test "allows inserting step with method name" do
+    journey_class = create_journey_subclass do
+      step :first do
+        # noop
+      end
+      step :third do
+        # noop
+      end
+      step :second, after_step: "first"
+
+      def second
+        # noop
+      end
+    end
+
+    assert_equal ["first", "second", "third"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "allows inserting step with automatic name generation" do
+    journey_class = create_journey_subclass do
+      step :first do
+        # noop
+      end
+      step :third do
+        # noop
+      end
+      step before_step: "third" do
+        # noop
+      end
+    end
+
+    assert_equal ["first", "step_3", "third"], journey_class.step_definitions.map(&:name)
+  end
+
+  test "allows inserting step with additional options" do
+    journey_class = create_journey_subclass do
+      step :first do
+        # noop
+      end
+      step :third do
+        # noop
+      end
+      step :second, after_step: "first", on_exception: :skip! do
+        # noop
+      end
+    end
+
+    assert_equal ["first", "second", "third"], journey_class.step_definitions.map(&:name)
+    assert_equal :skip!, journey_class.step_definitions[1].instance_variable_get(:@on_exception)
+  end
+
+  test "allows inserting steps before or after steps defined in superclass" do
+    parent_class = create_journey_subclass do
+      step :parent_first do
+        # noop
+      end
+      step :parent_last do
+        # noop
+      end
+    end
+
+    child_class = create_journey_subclass(parent_class) do
+      step :child_before, before_step: "parent_first" do
+        # noop
+      end
+      step :child_after, after_step: "parent_last" do
+        # noop
+      end
+      step :child_middle, after_step: "parent_first" do
+        # noop
+      end
+    end
+
+    assert_equal ["child_before", "parent_first", "child_middle", "parent_last", "child_after"], child_class.step_definitions.map(&:name)
+  end
+end

data/test/stepper_motor/test_helper_test.rb

@@ -22,6 +22,16 @@ class TestHelperTest < ActiveSupport::TestCase
     end
   end
 
+  def infinite_journey_class
+    create_journey_subclass do
+      step :step_1 do
+        SideEffects.touch!("step_1")
+        # This step never finishes, causing infinite loop
+        reattempt!
+      end
+    end
+  end
+
   test "speedruns the journey despite waits being configured" do
     journey = speedy_journey_class.create!
     assert journey.ready?
@@ -33,6 +43,36 @@ class TestHelperTest < ActiveSupport::TestCase
     assert SideEffects.produced?("step_3")
   end
 
+  test "speedruns the journey with time travel by default" do
+    journey = speedy_journey_class.create!
+    assert journey.ready?
+
+    original_time = Time.current
+    SideEffects.clear!
+    speedrun_journey(journey)
+    assert SideEffects.produced?("step_1")
+    assert SideEffects.produced?("step_2")
+    assert SideEffects.produced?("step_3")
+
+    # Calculate expected time difference: 40 minutes + 2 days + 1 second buffer per step
+    expected_time_difference = 40.minutes + 2.days + 3.seconds
+
+    # Verify that time has traveled forward by approximately the expected amount
+    # (allowing for small execution time differences)
+    assert_in_delta expected_time_difference, Time.current - original_time, 1.second
+  end
+
+  test "speedruns the journey without time travel when specified" do
+    journey = speedy_journey_class.create!
+    assert journey.ready?
+
+    SideEffects.clear!
+    speedrun_journey(journey, time_travel: false)
+    assert SideEffects.produced?("step_1")
+    assert SideEffects.produced?("step_2")
+    assert SideEffects.produced?("step_3")
+  end
+
   test "is able to perform a single step forcibly" do
     journey = speedy_journey_class.create!
     assert journey.ready?
@@ -41,4 +81,23 @@ class TestHelperTest < ActiveSupport::TestCase
     immediately_perform_single_step(journey, :step_2)
     assert SideEffects.produced?("step_2")
   end
+
+  test "fails when maximum_steps limit is exceeded" do
+    journey = infinite_journey_class.create!
+    assert journey.ready?
+
+    SideEffects.clear!
+
+    # This should raise an exception because the journey will try to perform more than 2 steps
+    # but the infinite loop in step_1 will never finish
+    error = assert_raises(RuntimeError) do
+      speedrun_journey(journey, maximum_steps: 2)
+    end
+
+    # Verify the error message indicates the journey didn't finish after the maximum steps
+    assert_match(/did not finish or cancel after performing 2 steps/, error.message)
+
+    # Verify that the step was executed (at least once)
+    assert SideEffects.produced?("step_1")
+  end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stepper_motor
 version: !ruby/object:Gem::Version
-  version: 0.1.18
+  version: 0.1.19
 platform: ruby
 authors:
 - Julik Tarkhanov
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-20 00:00:00.000000000 Z
+date: 2025-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -316,6 +317,7 @@ files:
 - test/stepper_motor/journey/idempotency_test.rb
 - test/stepper_motor/journey/if_condition_test.rb
 - test/stepper_motor/journey/step_definition_test.rb
+- test/stepper_motor/journey/step_ordering_test.rb
 - test/stepper_motor/journey/uniqueness_test.rb
 - test/stepper_motor/journey_test.rb
 - test/stepper_motor/perform_step_job_test.rb
@@ -333,6 +335,7 @@ metadata:
   homepage_uri: https://steppermotor.dev
   source_code_uri: https://github.com/stepper-motor/stepper_motor
   changelog_uri: https://github.com/stepper-motor/stepper_motor/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -347,7 +350,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
 summary: Effortless step workflows that embed nicely inside Rails
 test_files: []