stepper_motor 0.1.12 → 0.1.15

data/manual/MANUAL.md

@@ -230,6 +230,322 @@ end
 
 Here, we first initiate a payment using an idempotency key, and then poll for its completion or failure repeatedly. When a payment fails or succeeds, we notify the sender and finish the `Journey`. Note that this `Journey` is of a _payment,_ not of the user. A user may have multiple Payments in flight, each with their own `Journey` being tracket transactionally and correctly.
 
+### Polling with anonymous steps
+
+Here's an example of a Journey that polls an external API for a status update, using anonymous steps with increasing intervals:
+
+```ruby
+class OrderStatusPollingJourney < StepperMotor::Journey
+  alias_method :order, :hero
+
+  # Initial check
+  step do
+    check_status!
+  end
+
+  # Check after 30 seconds
+  step(wait: 30.seconds) do
+    check_status!
+  end
+
+  # Check every minute for 5 minutes
+  5.times do
+    step(wait: 1.minute) do
+      check_status!
+    end
+  end
+
+  # Check every 5 minutes for 30 minutes
+  6.times do
+    step(wait: 5.minutes) do
+      check_status!
+    end
+  end
+
+  # Final check after 1 hour
+  step(wait: 1.hour) do
+    check_status!
+  end
+
+  private
+
+  def check_status!
+    status = ExternalOrderAPI.fetch_status(order.external_id)
+    
+    case status
+    when :completed
+      order.complete!
+      finished!
+    when :failed
+      order.fail!
+      cancel!
+    when :processing
+      # Do nothing, will continue to next step
+    else
+      # Unexpected status, pause for manual investigation
+      pause!
+    end
+  end
+end
+```
+
+## Defining steps
+
+Steps are key building blocks in stepper_motor and can be defined in a number of ways. Rules of thumb:
+
+* When steps are recalled to be performed, they get recalled _by name._
+* When preparing for the next step or skipping to the next step, _the next step from the current in order of definition_ is going to be used.
+* Step names within a Journey subclass must be unique.
+
+stepper_motor will help you follow these rules, so don't worry too much about them just yet.
+
+The step definition is some form of callable block, which is then going to run in the context of this Journey instance (or the Journey subclass' instance)
+
+> [!TIP]
+> Regardless whether the step definition is a method or a block - the step will be `instance_exec`-ed in the context of the Journey instance.
+> Inside the step code you have access to all the methods of the Journey, including instance variables.
+
+### Anonymous steps
+
+The simplest is using anonymous steps and blocks (stepper_motor will generate you step names):
+
+```ruby
+class EraseAccountJourney < StepperMotor::Journey
+  step { hero.datapoints.in_batches.each(&:delete_all) }
+  step { hero.update!(email: "#{Digest::SHA1.hexdigest(hero.email)}@example.com") }
+end
+```
+
+Anonymous steps have a very good use for polling, when you want to define the repeats of the step programmatically. For example:
+
+```ruby
+class PollStatusJourney < StepperMotor::Journey
+  alias_method :payment, :hero
+
+  step { verify_status! }
+
+  # Then after 5 minutes
+  step(wait: 5.minutes) { verify_status! }
+
+  # Check every 2 hours after
+  12.times do
+    step(wait: 2.hours) { verify_status! }
+  end
+
+  # Check once a day after that
+  7.times do
+    step(wait: 1.day) { verify_status! }
+  end
+
+  step :terminate do
+    payment.failed!
+  end
+
+  def verify_status!
+    status = payment.current_status
+    finished! if status.complete?
+  end
+end
+```
+
+### Named steps
+
+You can give the steps names. Step names must be unique and stepper_motor will raise an exception if you reuse a step name:
+
+```ruby
+class EraseAccountJourney < StepperMotor::Journey
+  step :delete_datapoints { hero.datapoints.in_batches.each(&:delete_all) }
+  step :pseudonymize_email { hero.update!(email: "#{Digest::SHA1.hexdigest(hero.email)}@example.com") }
+end
+```
+
+The name of the step is what stepper_motor is going to persist to resume the Journey later. Naming your steps is useful because you then can then update your code and insert steps between the existing ones, and have your `Journey` correctly identify the right step. Steps are performed in the order they are defined. Imagine you start with this step sequence:
+
+```ruby
+step :one do
+  # perform some action
+end
+
+step :two do
+  # perform some other action
+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:
+
+```ruby
+step :one do
+  # perform some action
+end
+
+step :one_bis do
+  # some compliance action
+end
+
+step :two do
+  # perform some other action
+end
+```
+
+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.
+
+### Using instance methods as steps
+
+You can use instance methods of your Journey as steps by passing their name as a symbol to the `step` method:
+
+```ruby
+class Erasure < StepperMotor::Journey
+  step :erase_attachments
+  step :erase_emails
+
+  def erase_attachments
+    hero.uploaded_attachments.find_each(&:destroy)
+  end
+
+  def erase_emails
+    while hero.emails.count > 0
+      hero.emails.limit(5000).delete_all
+    end
+  end
+end
+```
+
+Since a method definition in Ruby returns a Symbol, you can use the return value of the `def` expression
+to define a `step` immediately:
+
+```ruby
+class Erasure < StepperMotor::Journey
+  step def erase_attachments
+    hero.uploaded_attachments.find_each(&:destroy)
+  end
+
+  step def erase_emails
+    while hero.emails.count > 0
+      hero.emails.limit(5000).delete_all
+    end
+  end
+end
+```
+
+### Conditional steps with `if:`
+
+You can make steps conditional by using the `if:` parameter. This allows you to skip steps based on runtime conditions. The `if:` parameter accepts:
+
+* A symbol (method name) that returns a boolean.
+* A callable (lambda or proc) that returns a boolean. It will be `instance_exec`d in the context of the Journey.
+* A literal boolean value (`true` or `false`) or a `nil` (treated as `false`)
+
+When a step's condition evaluates to `false`, the step is skipped and the journey continues to the next step. If there are no more steps, the journey finishes.
+
+#### Using method names as conditions
+
+```ruby
+class UserOnboardingJourney < StepperMotor::Journey
+  step :send_welcome_email, if: :should_send_welcome? do
+    WelcomeMailer.welcome(hero).deliver_later
+  end
+
+  step :send_premium_offer, if: :is_premium_user? do
+    PremiumOfferMailer.exclusive_offer(hero).deliver_later
+  end
+
+  step :complete_onboarding do
+    hero.update!(onboarding_completed_at: Time.current)
+  end
+
+  private
+
+  def should_send_welcome?
+    hero.email.present? && !hero.welcome_email_sent?
+  end
+
+  def is_premium_user?
+    hero.subscription&.premium?
+  end
+end
+```
+
+#### Using callable conditions
+
+You can use lambdas or procs for more dynamic conditions. They will be `instance_exec`d in the context of the Journey.:
+
+```ruby
+class OrderProcessingJourney < StepperMotor::Journey
+  step :send_confirmation, if: -> { hero.email.present? } do
+    OrderConfirmationMailer.confirm(hero).deliver_later
+  end
+
+  step :process_payment
+    PaymentProcessor.charge(hero)
+  end
+end
+```
+
+#### Skipping steps with literal conditions
+
+You can use literal boolean values to conditionally include or exclude steps:
+
+```ruby
+class FeatureFlagJourney < StepperMotor::Journey
+  step :new_feature_step, if: Rails.application.config.new_feature_enabled do
+    NewFeatureService.process(hero)
+  end
+
+  step :legacy_step, if: ENV["PERFORM_LEGACY_STEP"] do  # This step will never execute
+    LegacyService.process(hero)
+  end
+
+  step :always_execute do
+    # This step always runs
+  end
+end
+```
+
+When a step is skipped due to a false condition, the journey seamlessly continues to the next step without any interruption - or finishes if that step was the last one.
+
+#### Accessing Journey state in conditions
+
+It is possible to store instance variables on the `Journey` instance, but they do not persist between steps. This is very important to remember:
+
+> [!WARNING]
+> Because conditions are `instance_exec`d they can access instance variables of the `Journey`. It will also break majestically, because
+> the `Journey` is getting persisted and then loaded from the database on a different matchine, and it is always consumed fresh.
+> This means that the volatile state such as instance variables is not going to be available between steps. Always assume that
+> the `Journey` you are inside of does not have any instance variables set by previous steps and has just been freshly loaded from the database.
+
+
+### Waiting for the start of the step
+
+You configure how long a step should wait before starting using the `wait:` parameter. The `wait:` can be arbirarily long - but must be finite:
+
+```ruby
+class DraconianPasswordResetJourney < StepperMotor::Journey
+  step :ask_for_password_reset, wait: 6.months do
+    PasswordExpiredMailer.expired(hero).deliver_later
+    reattempt!
+  emd
+end
+```
+
+The `wait:` parameter defines the amount of time computed **from the moment the Journey gets created or the previous step is completed.**
+
+## Journey states
+
+The Journeys are managed using a state machine, which stepper_motor completely coordinates for you. The states are as follows:
+
+```mermaid
+stateDiagram-v2
+    [*] --> ready: create
+    ready --> performing: perform_next_step!
+    performing --> ready: reattempt!
+    performing --> finished: step completes
+    performing --> canceled: cancel!
+    performing --> paused: pause! or exception
+    paused --> ready: resume!
+    finished --> [*]
+    canceled --> [*]
+```
+
 ## Flow control within steps
 
 Inside a step, you currently can use the following flow control methods:
@@ -250,7 +566,6 @@ Inside a step, you currently can use the following flow control methods:
 
 You can't call those methods outside of the context of a performing step, and an exception is going to be raised if you do.
 
-
 ## Transactional semantics within steps
 
 Getting the transactional semantics _right_ with a system like stepper_motor is crucial. We strike a decent balance between reliability/durability and performance, namely:
@@ -273,16 +588,12 @@ We recommend using a "co-committing" ActiveJob adapter with stepper_motor (an ad
 * [good_job](https://github.com/bensheldon/good_job)
 * [solid_queue](https://github.com/rails/solid_queue) - with the same database used for the queue as the one used for Journeys
 
-While Rails core admittedly [insists on the stylistic choice of denying the users the option of co-committing their jobs](https://github.com/rails/rails/pull/53375#issuecomment-2555694252) we find this a highly inconsiderate choice, which has highly negative consequences for a system such as stepper_motor - where durability is paramount. Having good defaults is appropriate, but not removing a crucial affordance that a DB-based job queue provides is downright user-hostile.
+While Rails core admittedly [insists on the stylistic choice of denying the users the option of co-committing their jobs](https://github.com/rails/rails/pull/53375#issuecomment-2555694252) we find this a highly inconsiderate choice. It has negative consequences for a system such as stepper_motor - where durability is paramount. Having good defaults is great, but removing a crucial affordance that a DB-based job queue provides is user-hostile.
 
 In the future, stepper_motor _may_ move to a transactional outbox pattern whereby we emit events into a separate table and whichever queue adapter you have installed will be picking those messages up.
+Note that at the moment - if your ActiveJob adapter enqueues after commit - it is possible for your app to crash _between_ the Journey committing and your job enqueueing.
 
-For its own "trigger" job (the `PerformStepJob` and its versions) stepper_motor is configured to commit it with the Journey state changes, within the same transaction.
-
-This is done for the following reasons:
-
-* Not having the Journey with up-to-date state in teh DB when the job performs will lead to the job silently skipping, which is undesirable
-* But having the app crash between the Journey state committing and the trigger job committing is even less desirable. This would lead to jobs hanging in the `ready` state indefinitly, seemingly at random.
+We may address this in the future using a transactional outbox.
 
 ## Saving side-effects of steps
 
@@ -386,102 +697,40 @@ end
 
 If you use in-time scheduling you will need to add the `StepperMotor::ScheduleLoopJob` to your cron jobs, and perform it frequently enough. Note that having just the granularity of your cron jobs (minutes) may not be enough as reattempts of the steps may get scheduled with a smaller delay - of a few seconds, for instance.
 
-## Naming steps
-
-stepper_motor will name steps for you. However, using named steps is useful because you then can insert steps between existing ones, and have your `Journey` correctly identify the right step. Steps are performed in the order they are defined. Imagine you start with this step sequence:
-
-```ruby
-step :one do
-  # perform some action
-end
-
-step :two do
-  # perform some other action
-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:
-
-```ruby
-step :one do
-  # perform some action
-end
-
-step :one_bis do
-  # some compliance action
-end
-
-step :two do
-  # perform some other action
-end
-```
+## Exception handling inside steps
 
-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.
+> [!IMPORTANT]
+> Exception handling in steps is in flux, expect API changes.
 
-So, rules of thumb:
+By default, an exception raised inside a step of a Journey will _pause_ that Journey at that step. This is done for a number of reasons:
 
-* When steps are recalled to be performed, they get recalled _by name._
-* When preparing for the next step, _the next step from the current in order of definition_ is going to be used.
+* An endlessly reattempting step can cause load on your infrastructure and will never stop retrying
+* Since at the moment there is no configuration for backoff, such a step is likely to hit rate limits on the external resource it hits
+* It is likely a condition that was not anticipated when the Journey was written, thus a blind reattempt is unwise.
 
-## Using instance methods as steps
+While we may change this in future versions of `stepper_motor`, the current default is thus to `pause!` the Journey if an unhandled exception occurs.
 
-You can use instance methods as steps by passing their name as a symbol to the `step` method:
+Should that happen, you can query for the paused Journeys in your Rails console:
 
 ```ruby
-class Erasure < StepperMotor::Journey
-  step :erase_attachments
-  step :erase_emails
-
-  def erase_attachments
-    hero.uploaded_attachments.find_each(&:destroy)
-  end
-
-  def erase_emails
-    while hero.emails.count > 0
-      hero.emails.limit(5000).delete_all
-    end
-  end
-end
+my-app(dev)> StepperMotor::Journey.paused
 ```
 
-Since a method definition in Ruby returns a Symbol, you can use the return value of the `def` expression
-to define a `step` immediately:
+If a journey has been paused, you can resume it manually from the Rails console once you have investigated and rectified the error. You do so by calling `resume!` on it:
 
 ```ruby
-class Erasure < StepperMotor::Journey
-  step def erase_attachments
-    hero.uploaded_attachments.find_each(&:destroy)
-  end
-
-  step def erase_emails
-    while hero.emails.count > 0
-      hero.emails.limit(5000).delete_all
-    end
-  end
-end
+my-app(dev)> journey = StepperMotor::Journey.paused.first!
+my-app(dev)> paused_journey.resume!
 ```
-## Exception handling inside steps
-
-> [!IMPORTANT]
-> Exception handling in steps is in flux, expect API changes.
-
-When performing the step, any exceptions raised from within the step will be stored in a local
-variable to allow the Journey to be released as either `ready`, `finished` or `canceled`. The exception
-will be raised from within an `ensure` block after the persistence of the Journey has been taken care of.
-
-By default, an exception raised inside a step of a Journey will _pause_ that Journey. This is done for a number of reasons:
 
-* An endlessly reattempting step can cause load on your infrastructure and will never stop retrying
-* Since at the moment there is no configuration for backoff, such a step is likely to hit rate limits on the external resource it hits
-* It is likely a condition that was not anticipated when the Journey was written, thus a blind reattempt is unwise.
+This action is deliberately manual. You can also set up a job which automatically resumes paused Journeys, but we do not recommend that as things usually fail for a reason.
 
-While we may change this in future versions of `stepper_motor`, the current default is thus to `pause!` the Journey if an unhandled
-exception occurs. You can, however, switch it to `reattempt!` or `cancel!` a Journey should a particular step raise. This is configured per step:
+If you can make a decision to cancel or reattempt the journey - that's possible as well. This is configured per step:
 
 ```ruby
 class Erasure < StepperMotor::Journey
   step :initiate_deletion, on_exception: :reattempt! do
-    # ..Do the requisite work
+    # ..Do the requisite work with aggressive retries
   end
 end
 ```
@@ -524,4 +773,6 @@ class Payment < StepperMotor::Journey
 end
 ```
 
+It can be helpful to understand how exception handling is done by stepper_motor internally: when performing the step, any exceptions raised from within the step will be stored in a local variable to allow the Journey to be released as `ready`, `finished`, `canceled` or `paused`.
 
+That exception will is then going to be raised from within an `ensure` block, but only after the persistence of the Journey has been taken care of. This way the Journey has way more chance to reach a stable persisted state where it can be recovered (provided the database accepts the write, of course).

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.12", T.untyped)
+  VERSION = T.let("0.1.15", T.untyped)
   PerformStepJobV2 = T.let(StepperMotor::PerformStepJob, T.untyped)
   RecoverStuckJourneysJobV1 = T.let(StepperMotor::RecoverStuckJourneysJob, T.untyped)
 
@@ -33,16 +33,27 @@ module StepperMotor
     # _@param_ `wait` — the amount of time to wait before entering the step
     # 
     # _@param_ `on_exception` — the action to take if an exception occurs when performing the step. The possible values are: * `:cancel!` - cancels the Journey and re-raises the exception. The Journey will be persisted before re-raising. * `:reattempt!` - reattempts the Journey and re-raises the exception. The Journey will be persisted before re-raising.
+    # 
+    # _@param_ `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.
     sig do
       params(
         name: T.any(String, Symbol),
         seq: T.untyped,
         on_exception: Symbol,
         wait: T.any(Numeric, ActiveSupport::Duration),
+        if: T.any(TrueClass, FalseClass, NilClass, Symbol, Proc),
         step_block: T.untyped
       ).void
     end
-    def initialize(name:, seq:, on_exception:, wait: 0, &step_block); end
+    def initialize(name:, seq:, on_exception:, wait: 0, if: true, &step_block); end
+
+    # Checks if the step should be performed based on the if condition
+    # 
+    # _@param_ `journey` — the journey to check the condition for
+    # 
+    # _@return_ — true if the step should be performed, false otherwise
+    sig { params(journey: StepperMotor::Journey).returns(T::Boolean) }
+    def should_perform?(journey); end
 
     # Performs the step on the passed Journey, wrapping the step with the required context.
     # 
@@ -128,6 +139,8 @@ module StepperMotor
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
+    # _@param_ `if` — 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. The step will only be performed if the condition returns a truthy value.
+    # 
     # _@param_ `additional_step_definition_options` — Any remaining options get passed to `StepperMotor::Step.new` as keyword arguments.
     # 
     # _@return_ — the step definition that has been created
@@ -137,11 +150,12 @@ module StepperMotor
         wait: T.nilable(T.any(Float, T.untyped, ActiveSupport::Duration)),
         after: T.nilable(T.any(Float, T.untyped, ActiveSupport::Duration)),
         on_exception: Symbol,
-        additional_step_definition_options: T.untyped,
+        if: T.any(TrueClass, FalseClass, Symbol, Proc),
+        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, on_exception: :pause!, **additional_step_definition_options, &blk); end
+    def self.step(name = nil, wait: nil, after: nil, on_exception: :pause!, if: true, **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

data/sig/stepper_motor.rbs

@@ -31,13 +31,23 @@ module StepperMotor
     # _@param_ `wait` — the amount of time to wait before entering the step
     # 
     # _@param_ `on_exception` — the action to take if an exception occurs when performing the step. The possible values are: * `:cancel!` - cancels the Journey and re-raises the exception. The Journey will be persisted before re-raising. * `:reattempt!` - reattempts the Journey and re-raises the exception. The Journey will be persisted before re-raising.
+    # 
+    # _@param_ `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)
+                      ?wait: (Numeric | ActiveSupport::Duration),
+                      ?if: (TrueClass | FalseClass | NilClass | Symbol | Proc)
                     ) -> void
 
+    # Checks if the step should be performed based on the if condition
+    # 
+    # _@param_ `journey` — the journey to check the condition for
+    # 
+    # _@return_ — true if the step should be performed, false otherwise
+    def should_perform?: (StepperMotor::Journey journey) -> bool
+
     # Performs the step on the passed Journey, wrapping the step with the required context.
     # 
     # _@param_ `journey` — the journey to perform the step in. If a `step_block` is passed in, it is going to be executed in the context of the journey using `instance_exec`. If only the name of the step has been provided, an accordingly named public method on the journey will be called
@@ -117,6 +127,8 @@ module StepperMotor
     # 
     # _@param_ `on_exception` — See {StepperMotor::Step#on_exception}
     # 
+    # _@param_ `if` — 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. The step will only be performed if the condition returns a truthy value.
+    # 
     # _@param_ `additional_step_definition_options` — Any remaining options get passed to `StepperMotor::Step.new` as keyword arguments.
     # 
     # _@return_ — the step definition that has been created
@@ -125,7 +137,8 @@ module StepperMotor
                      ?wait: (Float | untyped | ActiveSupport::Duration)?,
                      ?after: (Float | untyped | ActiveSupport::Duration)?,
                      ?on_exception: Symbol,
-                     **untyped additional_step_definition_options
+                     ?if: (TrueClass | FalseClass | Symbol | Proc),
+                     **::Hash[untyped, untyped] additional_step_definition_options
                    ) -> StepperMotor::Step
 
     # sord warn - "StepperMotor::Step?" does not appear to be a type

data/stepper_motor.gemspec

@@ -37,6 +37,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest"
   spec.add_development_dependency "rails", "~> 7.0"
   spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "mysql2"
+  spec.add_development_dependency "pg"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "standard", "~> 1.50.0", "< 2.0"
   spec.add_development_dependency "magic_frozen_string_literal"

data/test/dummy/config/database.mysql2.yml

@@ -0,0 +1,14 @@
+default: &default
+  adapter: mysql2
+  database: stepper_motor_dummy_<%= Rails.env %>
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  username: root
+  password: constabulary
+  timeout: 5000
+
+development:
+  <<: *default
+test:
+  <<: *default
+production:
+  <<: *default

data/test/dummy/config/database.postgres.yml

@@ -0,0 +1,14 @@
+default: &default
+  adapter: postgres
+  database: stepper_motor_dummy_<%= Rails.env %>
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  username: root
+  password: constabulary
+  timeout: 5000
+
+development:
+  <<: *default
+test:
+  <<: *default
+production:
+  <<: *default

data/test/dummy/config/database.sqlite3.yml

@@ -0,0 +1,32 @@
+# SQLite. Versions 3.8.0 and up are supported.
+#   gem install sqlite3
+#
+#   Ensure the SQLite 3 gem is defined in your Gemfile
+#   gem "sqlite3"
+#
+default: &default
+  adapter: sqlite3
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  timeout: 5000
+
+development:
+  <<: *default
+  database: storage/development.sqlite3
+
+# Warning: The database defined as "test" will be erased and
+# re-generated from your development database when you run "rake".
+# Do not set this db to the same as development or production.
+test:
+  <<: *default
+  database: storage/test.sqlite3
+
+
+# SQLite3 write its data on the local filesystem, as such it requires
+# persistent disks. If you are deploying to a managed service, you should
+# make sure it provides disk persistence, as many don't.
+#
+# Similarly, if you deploy your application as a Docker container, you must
+# ensure the database is located in a persisted volume.
+production:
+  <<: *default
+  # database: path/to/persistent/storage/production.sqlite3

data/test/dummy/config/initializers/stepper_motor.rb

@@ -9,7 +9,7 @@
 #
 # and add its cycle job into your recurring jobs table. For example, for solid_queue:
 #
-#   stepper_motor_houseleeping:
+#   run_stepper_motor_scheduling_cycle:
 #     schedule: "*/30 * * * *" # Every 30 minutes
 #     class: "StepperMotor::CyclicScheduler::RunSchedulingCycleJob"
 #