standard_procedure_operations 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cfaaef3f5470debfff84e64763fd703752ae0c70a7c62c2926468aa9b897c83
-  data.tar.gz: 2af99adbc94c3c6f734e9272b909d42d199ddc7d7f18a866f4d14bd2ad78b9ff
+  metadata.gz: d19a26ed4cb26b809efc2e4d551a4895613608348f3524f1764c000aceb6aeca
+  data.tar.gz: 2290a93af8caeacfa00fd941e62e4785366e4efa80d59579201bfe93cd85fa0a
 SHA512:
-  metadata.gz: 40ba366b5f54cfd1d376ac34731f1d8e462afffef0512b9011603734a3c45319e40994b7790f556e6bfd27923b0cf67aadd521bebf98f004b71d7aad5956c53f
-  data.tar.gz: 833099833d7ef03773530f4301ee5b66434c26c94af54508e0c006aa082e6d4c812b84fd621dd9e5d9cb9a300be17292bf4be7c46679f5429c50937d5362a94b
+  metadata.gz: 898f19eb0c69a359a939f5f3b563645dd36d8d6bc2e77707ecc1099698541c02210cbc351866d255a3a6747fb957fbb5f82146a120e53c1ba7d87cd68b280e61
+  data.tar.gz: 8b44ab81583ce10937a02d9cc9cbe7e6d7c153a83b29661d4cb1055876b39f181de7aa022aa9a3bbb2adf0e97aa618034582512bb72465172908b388243d11b1

data/README.md

@@ -44,6 +44,7 @@ Here's how this would be represented using Operations.
 
 ```ruby
 class PrepareDocumentForDownload < Operations::Task
+  inputs :user, :document, :use_filename_scrambler
   starts_with :authorised?
 
   decision :authorised? do
@@ -78,6 +79,8 @@ end
 
 The five states are represented as three [decision](#decisions) handlers, one [action](#actions) handler and a [result](#results) handler.  
 
+The task also declares that it requires a `user`, `document` and `use_filename_scrambler` parameter to be provided, and also declares its initial state - `authorised?`.  
+
 ### Decisions
 A decision handler evaluates a condition, then changes state depending upon if the result is true or false. 
 
@@ -194,14 +197,12 @@ Handlers can alternatively be implemented as methods on the task itself.  This m
 The final `results` data from any `result` handlers is stored, along with the task, in the database, so it can be examined later.  It is accessed as an OpenStruct that is encoded into JSON.  But any ActiveRecord models are translated using a [GlobalID](https://github.com/rails/globalid) using [ActiveJob::Arguments](https://guides.rubyonrails.org/active_job_basics.html#supported-types-for-arguments).  Be aware that if you do store an ActiveRecord model into your `results` and that model is later deleted from the database, your task's `results` will be unavailable, as the `GlobalID::Locator` will fail when it tries to load the record.  The data is not lost though - if the deserialisation fails, the routine will return the JSON string as `results.raw_data`.
 
 ### Failures and exceptions
-
-If any handlers raise an exception, the task will be terminated. It will be marked as `failed?` and the `results` hash will contain `results.exception_message`, `results.exception_class` and `results.exception_backtrace` for the exception's message, class name and backtrace respectively.  
+If any handlers raise an exception, the task will be terminated. It will be marked as `failed?` and the `results` hash will contain `results.failure_message`, `results.exception_class` and `results.exception_backtrace` for the exception's message, class name and backtrace respectively.  
 
 You can also stop a task at any point by calling `fail_with message`.  This will mark the task as `failed?` and the `reeults` has will contain `results.failure_message`.
 
 ### Task life-cycle and the database
-
-There is an ActiveRecord migration that creates the `operations_tasks` table.  Use `bin/rails app:operations:install:migrations` to copy it to your application.  
+There is an ActiveRecord migration that creates the `operations_tasks` table.  Use `bin/rails operations:install:migrations` to copy it to your application, then run `bin/rails db:migrate` to add the table to your application's database.  
 
 When you `call` a task, it is written to the database.  Then whenever a state transition occurs, the task record is updated.  
 
@@ -214,33 +215,69 @@ This gives you a number of possibilities:
 However, it also means that your database table could fill up with junk that you're no longer interested in.  Therefore you can specify the maximum age of a task and, periodically, clean old tasks away.  Every task has a `delete_at` field that, by default, is set to `90.days.from_now`.  This can be changed by calling `Operations::Task.delete_after 7.days` (or whatever value you prefer).  Then, run a cron job (once per day) that calls `Operations::Task.delete_expired`, removing any tasks whose `deleted_at` date has passed.  
 
 ### Status messages
-
 Documentation coming soon.  
 
 ### Child tasks
-
 Coming soon.  
 
 ### Background operations and pauses
-
 Coming soon.  
 
-## Installation
-Add this line to your application's Gemfile:
+## Testing
+Because operations are intended to model long, complex, flowcharts of decisions and actions, it can be a pain coming up with the combinations of inputs to test every path through the sequence.  
 
+Instead, you can test each state handler in isolation.  As the handlers are state-less, we can simulate calling one by creating a task object and then calling the appropriate handler with the data that it expects.  This is done by calling `handling`, which yields a `test` object with outcomes from the handler that we can inspect
+
+To test if we have moved on to another state (for actions or decisions):
 ```ruby
-gem "standard_procedure_operations"
+MyOperation.handling(:an_action_or_decision, some: "data") do |test|
+  assert_equal test.next_state, "new_state"
+  # or
+  expect(test).to have_moved_to "new_state"
+end
 ```
+To test if some data has been set or modified (for actions):
+```ruby
+MyOperation.handling(:an_action, existing_data: "some_value") do |test|
+  # has a new data value been added?
+  assert_equal test.new_data, "new_value"
+  # or
+  expect(test.new_data).to eq "new_value"
+  # has an existing data value been modified?
+  assert_equal test.existing_data, "some_other_value"
+  # or
+  expect(test.existing_data).to eq "some_other_value"
+end
+```
+To test the results from a result handler:
+```ruby
+MyOperation.handling(:a_result, some: "data") do |test|
+  assert_equal test.outcome, "everything is as expected"
+  # or
+  expect(test.outcome).to eq "everything is as expected"
+end
+```
+To test if a handler has failed:
+```ruby
+MyOperation.handling(:a_failure, some: "data") do |test|
+  assert_equal test.failure_message, "oh dear"
+  # or
+  expect(test).to have_failed_with "oh dear"
+end
+```
+If you are using RSpec, you must `require "operations/matchers"` to make the matchers available to your specs.  
 
-Run `bundle install`, copy and run the migrations to add the tasks table to your database:
-
+## Installation
+Step 1: Add the gem to your Rails application's Gemfile:
+```ruby
+gem "standard_procedure_operations"
+```
+Step 2: Run `bundle install`, then copy and run the migrations to add the tasks table to your database:
 ```sh
-bin/rails app:operations:install:migrations 
+bin/rails operations:install:migrations 
 bin/rails db:migrate
 ```
-
-Then create your own operations by inheriting from `Operations::Task`.
-
+Step 3: Create your own operations by inheriting from `Operations::Task` and revel in the stateful flowcharts!
 ```ruby
 class DailyLife < Operations::Task
   starts_with :am_i_awake?
@@ -256,6 +293,7 @@ class DailyLife < Operations::Task
   def am_i_awake? = (7..23).include?(Time.now.hour)
 end
 ```
+Step 4: If you're using RSpec for testing, add `require "operations/matchers" to your "spec/rails_helper.rb" file.
 
 ## License
 The gem is available as open source under the terms of the [LGPL License](/LICENSE).  This may or may not make it suitable for your needs.

data/app/models/operations/task/data_carrier.rb

@@ -2,4 +2,6 @@ class Operations::Task::DataCarrier < OpenStruct
   def go_to(state, message = nil) = task.go_to(state, self, message)
 
   def fail_with(message) = task.fail_with(message)
+
+  def complete(results) = task.complete(results)
 end

data/app/models/operations/task/state_management.rb

@@ -7,6 +7,10 @@ module Operations::Task::StateManagement
   end
 
   class_methods do
+    def inputs(*names) = @required_inputs = names.map(&:to_sym)
+
+    def required_inputs = @required_inputs ||= []
+
     def starts_with(value) = @initial_state = value.to_sym
 
     def initial_state = @initial_state
@@ -20,13 +24,17 @@ module Operations::Task::StateManagement
     def state_handlers = @state_handlers ||= {}
 
     def handler_for(state) = state_handlers[state.to_sym]
+
+    def required_inputs_are_present_in?(data) = missing_inputs_from(data).empty?
+
+    def missing_inputs_from(data) = (required_inputs - data.keys.map(&:to_sym))
   end
 
   private def handler_for(state) = self.class.handler_for(state.to_sym)
   private def process_current_state(data)
     handler_for(state).call(self, data)
   rescue => ex
-    update! status: "failed", results: OpenStruct.new(exception_message: ex.message, exception_class: ex.class.name, exception_backtrace: ex.backtrace)
+    update! status: "failed", results: OpenStruct.new(failure_message: ex.message, exception_class: ex.class.name, exception_backtrace: ex.backtrace)
   end
   private def state_is_valid
     errors.add :state, :invalid if state.blank? || handler_for(state.to_sym).nil?
@@ -61,7 +69,7 @@ module Operations::Task::StateManagement
     def call(task, data)
       result = @condition.nil? ? task.send(@name, data) : data.instance_exec(&@condition)
       next_state = result ? @true_state : @false_state
-      next_state.respond_to?(:call) ? data.instance_eval(&next_state) : task.go_to(next_state, data)
+      next_state.respond_to?(:call) ? data.instance_eval(&next_state) : data.go_to(next_state, data)
     end
   end
 
@@ -74,7 +82,7 @@ module Operations::Task::StateManagement
     def call(task, data)
       results = OpenStruct.new
       data.instance_exec(results, &@handler) unless @handler.nil?
-      task.send :complete, results
+      data.complete(results)
     end
   end
 end

data/app/models/operations/task/testing.rb

@@ -0,0 +1,27 @@
+module Operations::Task::Testing
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def handling state, **data, &block
+      task = new state: state
+      data = TestResultCarrier.new(data.merge(task: task))
+      handler_for(state).call(task, data)
+      data.completion_results.nil? ? block.call(data) : block.call(data.completion_results)
+    end
+  end
+
+  class TestResultCarrier < OpenStruct
+    def go_to(state, message = nil)
+      self.next_state = state
+      self.status_message = message || next_state.to_s
+    end
+
+    def fail_with(message)
+      self.failure_message = message
+    end
+
+    def complete(results)
+      self.completion_results = results
+    end
+  end
+end

data/app/models/operations/task.rb

@@ -2,11 +2,17 @@ module Operations
   class Task < ApplicationRecord
     include StateManagement
     include Deletion
+    include Testing
     enum :status, in_progress: 0, completed: 1, failed: -1
     composed_of :results, class_name: "OpenStruct", constructor: ->(results) { results.to_h }, converter: ->(hash) { OpenStruct.new(hash) }
     serialize :results, coder: Operations::GlobalIDSerialiser, type: Hash, default: {}
 
-    def self.call(data = {}) = create!(state: initial_state).tap { |task| task.send(:process_current_state, DataCarrier.new(data.merge(task: task))) }
+    def self.call(data = {})
+      raise MissingInputsError, "Missing inputs: #{missing_inputs_from(data).join(", ")}" unless required_inputs_are_present_in?(data)
+      create!(state: initial_state).tap do |task|
+        task.send(:process_current_state, DataCarrier.new(data.merge(task: task)))
+      end
+    end
 
     def go_to(state, data = {}, message = nil)
       update!(state: state, status_message: message || state.to_s)
@@ -15,6 +21,6 @@ module Operations
 
     def fail_with(message) = update! status: "failed", results: {failure_message: message.to_s}
 
-    private def complete(results) = update!(status: "completed", results: results)
+    def complete(results) = update!(status: "completed", results: results)
   end
 end

data/db/migrate/20250127160616_create_operations_tasks.rb

@@ -1,12 +1,12 @@
-class CreateOperationsTasks < ActiveRecord::Migration[8.0]
+class CreateOperationsTasks < ActiveRecord::Migration[7.1]
   def change
     create_table :operations_tasks do |t|
       t.string :type
       t.integer :status, default: 0, null: false
       t.string :state, null: false
       t.string :status_message, default: "", null: false
-      t.text :data, default: "{}"
-      t.text :results, default: "{}"
+      t.text :data
+      t.text :results
       t.boolean :background, default: false, null: false
       t.datetime :delete_at, null: false, index: true
       t.timestamps

data/lib/operations/matchers.rb

@@ -0,0 +1,23 @@
+require "rspec/expectations"
+
+# Has the state of the task moved to the expected new state?
+#
+# Example:
+#     expect(test).to have_moved_to "new_state"
+#
+RSpec::Matchers.matcher :have_moved_to do |state|
+  match do |test_result|
+    test_result.next_state.to_s == state.to_s
+  end
+end
+
+# Has the task failed with a given failure message?
+#
+# Example:
+#     expect(test).to have_failed_with "some_error"
+#
+RSpec::Matchers.matcher :have_failed_with do |failure_message|
+  match do |test_result|
+    test_result.failure_message.to_s == failure_message.to_s
+  end
+end

data/lib/operations/missing_inputs_error.rb

@@ -0,0 +1,2 @@
+class Operations::MissingInputsError < Operations::Error
+end

data/lib/operations/version.rb

@@ -1,3 +1,3 @@
 module Operations
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/operations.rb

@@ -1,7 +1,10 @@
 require "ostruct"
 
 module Operations
+  class Error < StandardError
+  end
   require "operations/version"
   require "operations/engine"
   require "operations/global_id_serialiser"
+  require "operations/missing_inputs_error"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rahoul Baruah
@@ -37,11 +37,14 @@ files:
 - app/models/operations/task/data_carrier.rb
 - app/models/operations/task/deletion.rb
 - app/models/operations/task/state_management.rb
+- app/models/operations/task/testing.rb
 - config/routes.rb
 - db/migrate/20250127160616_create_operations_tasks.rb
 - lib/operations.rb
 - lib/operations/engine.rb
 - lib/operations/global_id_serialiser.rb
+- lib/operations/matchers.rb
+- lib/operations/missing_inputs_error.rb
 - lib/operations/version.rb
 - lib/standard_procedure_operations.rb
 - lib/tasks/operations_tasks.rake
@@ -52,7 +55,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://theartandscienceofruby.com/
   source_code_uri: https://github.com/standard-procedure/operations
-  changelog_uri: https://github.com/standard-procedure/operations/releases
+  changelog_uri: https://github.com/standard-procedure/operations/tags
 rdoc_options: []
 require_paths:
 - lib