standard_procedure_operations 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d0da11583bd5edf6619553813c302fbe675ce5563921e9960149d79888130c5
-  data.tar.gz: aefecc4a15ed64289822318feb10c68128c121a359e049ede7f8a2805ca6405c
+  metadata.gz: d19a26ed4cb26b809efc2e4d551a4895613608348f3524f1764c000aceb6aeca
+  data.tar.gz: 2290a93af8caeacfa00fd941e62e4785366e4efa80d59579201bfe93cd85fa0a
 SHA512:
-  metadata.gz: 998bca6b52931b7048585a22ab6cc53a53a9a872290bd6243a84bed7442c57209a2ea71f0502b744aeaa8b65461e9e7d1aca22321a3811fdac7f7a7d156e15e1
-  data.tar.gz: 474207de30dbe046bd59587f1dfe0fa5f14f7a13d2f72075838e6594d8533c1c9b8ab79e245eafecaf490782329f220fe5dc0f9546e194138c0dafedf0544ef3
+  metadata.gz: 898f19eb0c69a359a939f5f3b563645dd36d8d6bc2e77707ecc1099698541c02210cbc351866d255a3a6747fb957fbb5f82146a120e53c1ba7d87cd68b280e61
+  data.tar.gz: 8b44ab81583ce10937a02d9cc9cbe7e6d7c153a83b29661d4cb1055876b39f181de7aa022aa9a3bbb2adf0e97aa618034582512bb72465172908b388243d11b1

data/README.md

@@ -215,29 +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 the gem to your Rails 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
+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.  
+
+## Installation
+Step 1: Add the gem to your Rails application's Gemfile:
 ```ruby
 gem "standard_procedure_operations"
 ```
-Run `bundle install`, then copy and run the migrations to add the tasks table to your database:
+Step 2: Run `bundle install`, then copy and run the migrations to add the tasks table to your database:
 ```sh
 bin/rails operations:install:migrations 
 bin/rails db:migrate
 ```
-Create your own operations by inheriting from `Operations::Task` and revel in the stateful flowcharts!
+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?
@@ -253,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

@@ -69,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
 
@@ -82,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,6 +2,7 @@ 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: {}
@@ -20,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/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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_operations
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Rahoul Baruah
@@ -37,11 +37,13 @@ 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