trailblazer-test 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02bdfafb7d0c3648980cf33724a89d9954428fbd8466fd0f58df7fe0366b8d25
-  data.tar.gz: 2753cb581aa889d898f5b23bff1daa44e802150e877087d32faf7e3a46357f90
+  metadata.gz: 25326dbdb940038e49c6830ac6c4c833583c13db2d5f11782cac2b457f0836cb
+  data.tar.gz: e0639ac0cacc534a105138840e15f1019c9136c30042d8ef5d28c80eeb4800fa
 SHA512:
-  metadata.gz: 9e999f603f7944601d56d17c18e1cbfebe43234fa539e5c7ce9176ca5cf3e1aa2e211bcc1097569b372776020a9b63c6fb86a0f8a350968bea4b0dc755a2eafb
-  data.tar.gz: 4701ebcfbb62202dcac8bbcc13149779c63add90ab9471484f1495a5a3a7ca682ee2e17c9210e8c70543f0707939edb3c4bda9d2de46283a54e9e91e5f0a024f
+  metadata.gz: 00332de32685126953eff6bfc0f1384f497e431e4ec1038a2f33a04cd3b37f762c8612c6834757a81095633ceaf55c748a799bf925ce27c923b5a391e8d2481d
+  data.tar.gz: a09347b703bf1eb6298f63b3e0c3b4481590e92b29b3d8abfb7e192e28a1986a94e2eafb1ff1d18792fc9693c94bcc4cad0cbec922ff9aff637e8ac2cc12fb4f

data/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+## This file is managed by Terraform.
+## Do not modify this file directly, as it may be overwritten.
+## Please open an issue instead.
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # commenting out 2.7 because of dry.
+        ruby: ['3.0', '3.1', '3.2', "3.3", "head", "jruby"]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle exec rake

data/CHANGES.md

@@ -1,3 +1,11 @@
+# 1.0.0
+
+* Releasing the first stable version.
+
+# 0.1.1
+
+* Added `mock_step` helper to mock activity's or nested activity's step
+
 # 0.1.0
 
 * `ctx` and `params` helper methods implemented

data/Gemfile

@@ -2,3 +2,10 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in trailblazer-test.gemspec
 gemspec
+
+# gem "reform-rails", path: "../reform-rails"
+
+gem "trailblazer-endpoint", path: "../trailblazer-endpoint"
+# gem "trailblazer-core-utils", path: "../trailblazer-core-utils"
+# gem "trailblazer-endpoint", github: "trailblazer/trailblazer-endpoint"
+gem "ostruct"

data/README.md

@@ -1,211 +1,45 @@
 # Trailblazer::Test
 
-[![Build Status](https://travis-ci.org/trailblazer/trailblazer-test.svg)](https://travis-ci.org/trailblazer/trailblazer-test)
-[![Gem Version](https://badge.fury.io/rb/trailblazer-test.svg)](http://badge.fury.io/rb/trailblazer-test)
+_Assertions and helpers for operation unit tests._
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'trailblazer-test'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install trailblazer-test
-
-## Usage
-
-Add in your test `_helper` the following modules:
-
-```ruby
-include Trailblazer::Test::Assertions
-include Trailblazer::Test::Operation::Assertions
-```
-
-If you are using Trailblazer v2.0 you need to add also:
-
-```ruby
-require "trailblazer/test/deprecation/operation/assertions"
-
-include Trailblazer::Test::Deprecation::Operation::Assertions # in your test class
-```
-
-To be able to test an operation we need 3 auxiliary methods which have to be defined at the start of your tests:
-* `default_params` (**required**): hash of params which will be always passed to the operation unless overriden by `params` or `ctx`
-* `expected_attrs` (**required**): hash always used to assert model attributes
-* `default_options` (**required if using `ctx`**): hash of options which will be always passed to the operation unless overriden by `ctx`
-
-We are also providing 2 helper methods:
-* `params(new_params)`
-* `ctx(new_params, options)`
-
-Those will merge params and options for you and return the final inputs which then can be passed to the operation under testing.
-
-Pass `deep_merge: false` to the helper methods to disable the default deep merging of params and options.
-
-*Same API for Trailblazer v2.0 and v2.1.*
-
-Finally, using the built-in assertions you are able to test your operations in a fast and easy way:
-* `assert_pass` -> your operation is successful and model has the correct attributes
-* `assert_fail` -> your operation fails and returns some specific errors
-* `assert_policy_fail` -> your operation fails because policy fails
-
-#### params
-
-`params` accepts one argument which is merged into `default_params`.
-
-```ruby
-let(:default_params) { { title: 'My title' } }
-
-params(artist: 'My Artist') -> { params: { title: 'My title', artist: 'My Artist' } }
-params(title: 'Other one') -> { params: { title: 'Other one' } }
-```
-
-#### ctx
-
-`ctx` accepts 2 arguments, first one will be merged into the `default_params` and the second one will be merged into `default_options`
-
-```ruby
-let(:default_params)  { { title: 'My title' } }
-let(:default_options) { { current_user: 'me' } }
-
-ctx(artist: 'My Artist') -> { params: { title: 'My title', artist: 'My Artist' }, current_user: 'me' }
-ctx({title: 'Other one'}, current_user: 'you') -> { params: { title: 'Other one' }, current_user: 'you' }
-```
-
-### assert_pass
-
-```ruby
-assert_pass(operation, ctx, expected_attributes)
-```
-
-Example:
-```ruby
-let(:default_params) { { band: 'The Chats'} }
-let(:default_options) { { current_user: user} }
-let(:expected_attrs) { { band: 'The Chats'} }
-
-it { assert_pass MyOp, ctx(title: 'Smoko'), title: 'Smoko' }
-```
-
-Pass `deep_merge: false` to disable the deep merging of the third argument `expected_attributes` and the auxiliary method `expected_attrs`.
-
-It's also possible to test in a more detailed way using a block:
-
-```ruby
-assert_pass MyOp, ctx(title: 'Smoko'), {} do |result|
-  assert_equal "Smoko", result[:model].title
-end
-```
-
-### assert_fail
-
-```ruby
-assert_fail(operation, ctx)
-```
-
-Example:
-```ruby
-let(:default_params) { { band: 'The Chats'} }
-let(:default_options) { { current_user: user} }
-let(:expected_attrs) { { band: 'The Chats'} }
-
-it { assert_fail MyOp, ctx(title: 'Smoko') }
-```
-
-This will just test that the operation fails instead passing `expected_errors` as an array of symbols will also test that specific attribute has an error:
-
-```ruby
-assert_fail MyOp, ctx(band: 'Justing Beaver'), expected_errors: [:band] # definitely wrong!!!!
-```
-
-Using the block here will allow to test the error message:
-
-```ruby
-assert_fail MyOp, ctx(band: 'Justing Beaver') do |result|
-  assert_equal 'You cannot listen Justing Beaver', result['contract.default'].errors.messages[:band]
-end
-```
-
-Change contract name using `contract_name`.
+The [comprehensive docs are here](https://trailblazer.to/2.1/docs/test/).
 
-*We will improve this part and allowing to the test message directly without using a block*
+Read our introducing blog post for a better overview.
 
+## Installation
 
-### assert_policy_fail
-
-Add this in your test file to be able to use it:
-```ruby
-include Trailblazer::Test::Operation::PolicyAssertions
-```
-
-```ruby
-assert_policy_fail(operation, ctx)
-```
-
-This will test that the operation fails due to a policy failure.
+Add the following line to your project's `Gemfile`.
 
-Example:
 ```ruby
-let(:default_params) { { band: 'The Chats'} }
-let(:default_options) { { current_user: user} }
-
-it { assert_policy_fail MyOp, ctx({title: 'Smoko'}, current_user: another) }
+gem "trailblazer-test", ">= 1.0.0", "< 2.0.0"
 ```
-Change policy name using `policy_name`.
-
-## Test Setup
-
-It is obviously crucial to test your operation in the correct test enviroment calling operation instead of using `FactoryBot` or simply `Model.create`.
 
-To do so we provide 2 helper methods:
-* `call`: will call the operation and **will not raise** an error in case of failure
-* `factory`: will call the operation and **will raise** an error in case of failure returning also the trace and a validate error message in case exists
+## Overview
 
-### Usage
+This gem adds the following assertions and helpers:
 
-Add this in your test `_helper.rb`:
+* `#assert_pass` to test an operation terminating with success.
+* `#assert_fail` to assert validation errors and the like.
+* `#mock_step` helping the replace steps with stubs.
 
-```ruby
-include Trailblazer::Test::Operation::Helper
-```
+## Example
 
-In case you use are Trailblazer v2.0, you need to add this instead:
+An example test case checking if an operation passed and created a model could look as follows.
 
 ```ruby
-require "trailblazer/test/deprecation/operation/helper"
+# test/operation/memo_test.rb
 
-include Trailblazer::Test::Deprecation::Operation::Helper
-```
-
-*Same API for both Trailblazer v2.0 and v2.1*
-
-Examples:
-```ruby
-# call
-let(:user) { call(User::Create, params: params)[:model] }
-
-# call with block
-let(:user) do
-  call User::Create, params: params do |result|
-    # run some code to reproduce some async jobs (for example)
-  end[:model]
-end
+require "test_helper"
 
-# factory - this will raise an error if User::Create fails
-let(:user) { factory(User::Create, params: params)[:model] }
+class MemoOperationTest < Minitest::Spec
+  Trailblazer::Test.module!(self) # install our helpers.
 
-# factory - this will raise an error if User::Create fails
-let(:user) do
-  factory User::Create, params: params do |result|
-    # this block will be yield only if User::Create is successful
-    # run some code to reproduce some async jobs (for example)
-  end[:model]
+  it "passes with valid input" do
+    # ...
+    assert_pass Memo::Operation::Create, input,
+      content:    "Stock up beer",
+      persisted?: true,
+      id:         ->(asserted:, **) { asserted.id > 0 }
+  end
 end
 ```

data/Rakefile

@@ -1,8 +1,5 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new(:rubocop)
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"

data/lib/trailblazer/test/assertion/assert_exposes.rb

@@ -0,0 +1,73 @@
+module Trailblazer
+  module Test
+    module Assertion
+      module AssertExposes
+        # Test if all `tuples` values on `asserted` match the expected values.
+        # @param asserted Object Object that exposes attributes to test
+        # @param tuples Hash Key/value attribute pairs to test
+        # @param options Hash Default :reader is `asserted.{name}`,
+        # TODO: test err msgs!
+        def assert_exposes(asserted, expected=nil, reader: nil, **options)
+          expected = options.any? ? options : expected # allow passing {expected} as kwargs, too.
+
+          _assert_exposes_for(asserted, expected, reader: reader)
+        end
+
+        # def assert_exposes_hash(asserted, expected)
+        #   _assert_exposes_for(asserted, expected, reader: :[])
+        # end
+
+        # @private
+        def _assert_exposes_for(asserted, expected, **options)
+          passed, matches, last_failed = Assert.assert_attributes(asserted, expected, **options) do |_matches, last_failed|
+            name, expected_value, actual_value, _passed, is_eq, error_msg = last_failed
+
+            is_eq ? assert_equal(expected_value, actual_value, error_msg) : assert(expected_value, error_msg)
+
+            return false
+          end
+
+          return true
+        end
+
+        module Assert
+          module_function
+
+          # Yields {block} if tuples don't match/failed.
+          def assert_attributes(asserted, expected, reader: false, &block)
+            passed, matches, last_failed = match_tuples(asserted, expected, reader: reader)
+
+            yield matches, last_failed unless passed
+
+            return passed, matches, last_failed
+          end
+
+          # Test if all properties match using our own {#test_equal}.
+          # @private
+          def match_tuples(asserted, expected, reader:)
+            passed = true # goes {false} if one or more attributes didn't match.
+
+            matches = expected.collect do |k, v|
+              actual          = Test::Assertion.actual(asserted, reader, k)
+              expected, is_eq = Test::Assertion.expected(asserted, v, actual)
+
+              is_eq ?
+                [k, expected, actual, passed &= test_equal(expected, actual), is_eq, "Property [#{k}] mismatch"] :
+                [k, expected, actual, passed &= test_true(expected, actual), is_eq, "Actual: #{actual.inspect}."]
+            end
+
+            [passed, matches, matches.find { |k, v, actual, passed, *| !passed }]
+          end
+
+          def test_equal(expected, actual)
+            expected == actual
+          end
+
+          def test_true(expected, actual)
+            !! expected
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/test/assertion/assert_fail.rb

@@ -0,0 +1,58 @@
+module Trailblazer
+  module Test
+    module Assertion
+      module AssertFail
+        module_function
+
+        extend AssertPass::Utils
+
+        # {expected_errors} can be nil when using the {#assert_fail} block syntax.
+        def call(activity, ctx, expected_errors=nil, test:, invoke:, **kws)
+          signal, ctx, _ = invoke.(activity, ctx)
+
+          assert_fail_with_model(signal, ctx, expected_errors: expected_errors, test: test, operation: activity, **kws)
+        end
+
+        # @private
+        def assert_fail_with_model(signal, ctx, test:, **options)
+          assert_after_call(ctx, **options) do |ctx|
+
+            test.assert_equal *arguments_for_assert_fail(signal), error_message_for_assert_fail_after_call(signal, ctx, **options)
+
+            if options[:expected_errors]
+              # TODO: allow error messages from somewhere else.
+              # only test _if_ errors are present, not the content.
+              colored_errors = AssertPass::Errors.colored_errors_for(ctx)
+
+              test.assert_equal *arguments_for_assert_contract_errors(signal, ctx, contract_name: :default, **options), "Actual contract errors: #{colored_errors}"
+            end
+          end
+        end
+
+        def arguments_for_assert_fail(signal)
+          return false, Assertion::SUCCESS_TERMINI.include?(signal.to_h[:semantic]) # FIXME: same logic as in {#assert_pass}.
+        end
+
+        def arguments_for_assert_contract_errors(signal, ctx, contract_name:, expected_errors:, **)
+          with_messages = expected_errors.is_a?(Hash)
+
+          raise ExpectedErrorsTypeError, "expected_errors has to be an Array or Hash" unless expected_errors.is_a?(Array) || with_messages # TODO: test me!
+
+          errors = ctx[:"contract.#{contract_name}"].errors.messages # TODO: this will soon change with the operation Errors object.
+
+          if with_messages
+            expected_errors = expected_errors.collect { |k, v| [k, Array(v)] }.to_h
+
+            return expected_errors, errors
+          else
+            return expected_errors.sort, errors.keys.sort
+          end
+        end
+
+        def error_message_for_assert_fail_after_call(signal, ctx, operation:, **)
+          %{{#{operation}} didn't fail, it passed}
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/test/assertion/assert_pass.rb

@@ -0,0 +1,101 @@
+module Trailblazer
+  module Test
+    module Assertion
+      module AssertPass
+        module_function
+
+        def call(activity, ctx, invoke:, **options)
+          signal, ctx, _ = invoke.(activity, ctx)
+
+          assert_pass_with_model(signal, ctx, operation: activity, **options)
+        end
+
+        def assert_pass_with_model(signal, ctx, **options)
+          assert_after_call(ctx, **options) do |ctx|
+            Passed.new.call(signal, ctx, **options)
+            PassedWithAttributes.new.call(signal, ctx, **options)
+          end
+        end
+
+        class Passed
+          # Check if the operation terminates on {:success}.
+          # @semi-public Used in rspec-trailblazer
+          def call(signal, ctx, **options)
+            expected_outcome, actual_outcome = arguments_for_assertion(signal)
+            error_msg = error_message(signal, ctx, **options) # DISCUSS: compute error message before there was an error?
+
+            outcome = assertion(expected_outcome, actual_outcome, error_msg, **options)
+            return outcome, error_msg
+          end
+
+          # What needs to be compared?
+          def arguments_for_assertion(signal)
+            return true, Assertion::SUCCESS_TERMINI.include?(signal.to_h[:semantic])
+          end
+
+          def error_message(signal, ctx, operation:, **)
+            colored_errors = Errors.colored_errors_for(ctx)
+
+            %{{#{operation}} failed: #{colored_errors}} # FIXME: only if contract's there!
+          end
+
+          def assertion(expected_outcome, actual_outcome, error_msg, test:, **)
+            test.assert_equal(
+              expected_outcome,
+              actual_outcome,
+              error_msg
+            )
+          end
+        end
+
+        # @semi-public Used in rspec-trailblazer
+        class PassedWithAttributes
+          def call(signal, ctx, **options)
+            model = model_for(ctx, **options)
+
+            outcome, error_msg = assertion(ctx, **options, model: model)
+            return outcome, error_msg
+          end
+
+          # DISCUSS: should we default options like {:model_at} here?
+          def model_for(ctx, model_at: :model, **)
+            ctx[model_at]
+          end
+
+          def assertion(ctx, model:, expected_model_attributes:, test:, **)
+            test.assert_exposes(model, expected_model_attributes)
+          end
+        end
+
+        module Utils
+          # @private
+          def assert_after_call(ctx, user_block:, **kws)
+            yield(ctx)
+
+            user_block.call(ctx) if user_block
+
+            ctx
+          end
+        end # Utils
+
+        module Errors
+          module_function
+
+          def colored_errors_for(ctx)
+            # TODO: generic errors object "finding"
+            errors =
+              if ctx[:"contract.default"]
+                ctx[:"contract.default"].errors.messages.inspect
+              else
+                ""
+              end
+
+            colored_errors = %{\e[33m#{errors}\e[0m}
+          end
+        end
+
+        extend Utils
+      end
+    end
+  end
+end

data/lib/trailblazer/test/assertion.rb

@@ -0,0 +1,114 @@
+module Trailblazer
+  module Test
+    # Top-level entry points for end users.
+    # These methods expose the end user syntax, not the logic.
+    module Assertion
+      def self.module!(receiver, activity: false, suite: false, spec: true)
+        modules = [Helper::MockStep, AssertExposes]
+        if suite
+          modules += [Suite, Suite::Spec] if spec
+          modules += [Suite, Suite::Test] if suite && !spec
+        else
+          modules += [Assertion]
+        end
+
+        modules += [Assertion::Activity] if activity
+
+        receiver.include(*modules.reverse)
+      end
+
+      SUCCESS_TERMINI = [:success, :pass_fast] # DISCUSS: where should this be defined?
+
+      # @private
+      # Invoker for Operation
+      def self.invoke_operation(operation, ctx)
+        result = operation.call(ctx)
+
+        return result.terminus, result # translate the holy {Operation::Result} object back to a normal "circuit interface" return value.
+      end
+
+      # @private
+      # Invoker with debugging for Operation
+      def self.invoke_operation_with_wtf(operation, ctx)
+        result = operation.wtf?(ctx)
+
+        return result.terminus, result
+      end
+
+      # Evaluate value if it's a lambda, and let the caller know whether we need an
+      # assert_equal or an assert.
+      def self.expected(asserted, value, actual)
+        value.is_a?(Proc) ? [value.(actual: actual, asserted: asserted), false] : [value, true]
+      end
+
+      # # Read the actual value from the asserted object (e.g. a model).
+      def self.actual(asserted, reader, name)
+        reader ? asserted.public_send(reader, name) : asserted.public_send(name)
+      end
+
+      # DISCUSS: move to Assertion::Minitest?
+      # Test case instance method. Specific to Minitest.
+      def assert_pass(activity, options, invoke: Assertion.method(:invoke_operation), model_at: :model, **kws, &block)
+        # DISCUSS: {:model_at} and {:invoke_method} block actual attributes.
+        AssertPass.(activity, options,
+          test: self,
+          user_block: block,
+          expected_model_attributes: kws,
+          model_at: model_at,
+          invoke: invoke,
+        ) # Forward {#assert_pass} to {AssertPass.call} or wherever your implementation sits.
+      end
+
+      # DISCUSS: move to Assertion::Minitest?
+      # Test case instance method. Specific to Minitest.
+      def assert_fail(activity, options, *args, invoke: Assertion.method(:invoke_operation), **kws, &block)
+        AssertFail.(activity, options, *args, test: self, user_block: block, invoke: invoke, **kws) # Forward {#assert_fail} to {AssertFail.call} or wherever your implementation sits.
+      end
+
+      def assert_pass?(*args, **options, &block)
+        assert_pass(*args, **options, invoke: Assertion.method(:invoke_operation_with_wtf), &block)
+      end
+
+      def assert_fail?(*args, **options, &block)
+        assert_fail(*args, **options, invoke: Assertion.method(:invoke_operation_with_wtf), &block)
+      end
+
+      # Assertions for Activity, not for Operation.
+      module Activity
+        def self.invoke_activity(activity, ctx)
+          signal, (ctx, _) = activity.call([ctx, {}]) # call with circuit interface. https://trailblazer.to/2.1/docs/operation/#operation-internals-circuit-interface
+
+          return signal, ctx
+        end
+
+        def self.invoke_activity_with_task_wrap(activity, ctx)
+          signal, (ctx, _) = ::Trailblazer::Activity::TaskWrap.invoke(activity, [ctx, {}]) # call with circuit interface. https://trailblazer.to/2.1/docs/operation/#operation-internals-circuit-interface
+
+          return signal, ctx
+        end
+
+        def self.invoke_activity_with_tracing(activity, ctx)
+          signal, (ctx, _) = Developer::Wtf.invoke(activity, [ctx, {}])
+
+          return signal, ctx
+        end
+
+        def assert_pass(*args, invoke: Activity.method(:invoke_activity_with_task_wrap), **options, &block)
+          super(*args, **options, invoke: invoke, &block)
+        end
+
+        def assert_fail(*args, invoke: Activity.method(:invoke_activity_with_task_wrap), **options, &block)
+          super(*args, **options, invoke: invoke, &block)
+        end
+
+        def assert_pass?(*args, **options, &block)
+          assert_pass(*args, **options, invoke: Activity.method(:invoke_activity_with_tracing), &block)
+        end
+
+        def assert_fail?(*args, **options, &block)
+          assert_fail(*args, **options, invoke: Activity.method(:invoke_activity_with_tracing), &block)
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/test/context.rb

@@ -0,0 +1,5 @@
+module Trailblazer::Test
+  class Context < Hash
+    # TODO: override {#inspect}
+  end
+end