trailblazer-test 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 484e57db55ede663a53082654e62fc6d12b1384b1591718dfc7fc440c59dd86b
-  data.tar.gz: 5595d2f6daab154412e612e226474e1e88592e82ebdc8d8a1cdf8afc1849ae1e
+  metadata.gz: 25326dbdb940038e49c6830ac6c4c833583c13db2d5f11782cac2b457f0836cb
+  data.tar.gz: e0639ac0cacc534a105138840e15f1019c9136c30042d8ef5d28c80eeb4800fa
 SHA512:
-  metadata.gz: 302594051f040ca9c3570ac2316cfb5c0a511814727fffc74727b9b2bd0d2adea2ee56a7037406af11c02c93b5c6fa91e7a0a28517352db72c2f6e99949b60c7
-  data.tar.gz: a510c4907ace3ba13e59872d698c8771705bd3047072e3296141381a9c0281ce36bae05759038052dc98a2e0e3421b8e5d3dae9ce28dc4249dab3289367e4ba0
+  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,7 @@
+# 1.0.0
+
+* Releasing the first stable version.
+
 # 0.1.1
 
 * Added `mock_step` helper to mock activity's or nested activity's step

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,140 +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._
 
-## Usage
+The [comprehensive docs are here](https://trailblazer.to/2.1/docs/test/).
 
-Testing Trailblazer applications usually involves the following tests.
+Read our introducing blog post for a better overview.
 
-1. **Unit tests for operations**: They test all edge cases in a nice, fast unit test environment without any HTTP involved.
-2. **Integration tests for controllers**: These Smoke tests only test the wiring between controller, operation and presentation   layer. Usually, a coded click path simulates you manually clicking through your app and testing if it works. The preferred way    here is using Rack-test and Capybara.
-3. **Unit tests for cells** By invoking your cells with arbitrary data you functionally test the rendered markup using Capybara.
-
-All the up to date details on the available assertions and helpers is available at [official documentation](http://2019.trailblazer.to/2.1/docs/trailblazer.html#trailblazer-test).
-
-### Assertions
-
-To use available assertions, 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
-```
-
-[Learn more](http://2019.trailblazer.to/2.1/docs/trailblazer.html#trailblazer-test-assertions)
-
-#### assert_pass
-
-Use `assert_pass` to run an operation and assert it was successful, while checking if the attributes of the operation's `model` are what you're expecting.
-
-```ruby
-it { assert_pass Blog::Operation::Create, { params: { title: "Ruby Soho" } }, title: "Ruby Soho" }
-```
-
-#### assert_fail
-
-To test an unsuccessful outcome of an operation, use `assert_fail`. This is used for testing all kinds of validations. By passing insufficient or wrong data to the operation, it will fail and mark errors on the errors object.
-
-```ruby
-it { assert_fail Blog::Operation::Update, { params: { band: nil } }, expected_errors: [:band] }
-```
-
-#### assert_policy_fail
-
-This will test that the operation fails due to a policy failure.
-
-```ruby
-it { assert_policy_fail Blog::Operation::Delete, ctx({title: "Ruby Soho"}, current_user: not_allowed_user) }
-```
-
-#### assert_exposes
-
-Test attributes of an arbitrary object.
-
-```ruby
-it { assert_exposes model, title: "Timebomb", band: "Rancid" }
-```
-
-### Helpers
+## Installation
 
-There are several helpers to deal with operation tests and operations used as factories.
-Add this in your `_helper.rb` file to use all available helpers.
+Add the following line to your project's `Gemfile`.
 
 ```ruby
-include Trailblazer::Test::Operation::Helper
+gem "trailblazer-test", ">= 1.0.0", "< 2.0.0"
 ```
 
-[Learn more](http://2019.trailblazer.to/2.1/docs/trailblazer.html#trailblazer-test-helpers)
+## Overview
 
-#### call
+This gem adds the following assertions and helpers:
 
-Instead of manually invoking an operation, you can use the `call` helper.
-
-```ruby
-it do
-  result = call Blog::Operation::Create, params: {title: "Shipwreck", band: "Rancid"}
-  # use `result` object however you want
-end
-```
+* `#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.
 
-#### factory
+## Example
 
-The `factory` method calls the operation and raises an error should the operation have failed. If successful, it will do the exact same thing `call` does.
+An example test case checking if an operation passed and created a model could look as follows.
 
 ```ruby
-it do
-  assert_raises do
-    factory Blog::Operation::Create, params: {title: "Shipwreck", band: "The Chats"}
-  end
-end
-```
-
-#### mock_step
+# test/operation/memo_test.rb
 
-This helper allows you to mock any step within a given or deeply nested activities. For example,
+require "test_helper"
 
-```ruby
-class Show < Trailblazer::Operation
-  step :load_user
-  ...
-end
-```
+class MemoOperationTest < Minitest::Spec
+  Trailblazer::Test.module!(self) # install our helpers.
 
-To skip processing inside `:load_user` and use a mock instead, use `mock_step`.
-
-```ruby
-it do
-  new_activity = mock_step(Show, id: :load_user) do |ctx|
-    ctx[:user] = Struct.new(:name).new('Mocky')
-  end
-
-  assert_pass new_activity, {}, {} do |ctx|
-    assert_equal ctx[:user].name, 'Mocky'
+  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
 ```
-
-## 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

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

data/lib/trailblazer/test/endpoint.rb

@@ -0,0 +1,42 @@
+module Trailblazer
+  module Test
+    # DISCUSS: this is not really endpoint related, it's more like setting a "global" invocation mechanism.
+    module Endpoint
+      # DISCUSS: not sure this is the final "technique" to use the global endpoint invoker.
+      def self.module!(receiver, invoke_method:, invoke_method_wtf:)
+        receiver.class_eval do
+          @@INVOKE_METHOD = invoke_method
+          @@INVOKE_METHOD_WTF = invoke_method_wtf
+
+          def trailblazer_test_invoke_method
+            @@INVOKE_METHOD
+          end
+
+          def trailblazer_test_invoke_method_wtf
+            @@INVOKE_METHOD_WTF
+          end
+        end
+
+        Assertion
+      end
+
+      module Assertion
+        def assert_pass(*args, invoke: trailblazer_test_invoke_method, **options, &block)
+          super(*args, **options, invoke: invoke, &block)
+        end
+
+        def assert_fail(*args, invoke: trailblazer_test_invoke_method, **options, &block)
+          super(*args, **options, invoke: invoke, &block)
+        end
+
+        def assert_pass?(*args, **options, &block)
+          assert_pass(*args, **options, invoke: trailblazer_test_invoke_method_wtf, &block)
+        end
+
+        def assert_fail?(*args, **options, &block)
+          assert_fail(*args, **options, invoke: trailblazer_test_invoke_method_wtf, &block)
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/test/helper/mock_step.rb

@@ -0,0 +1,19 @@
+module Trailblazer::Test
+  module Helper
+    module MockStep
+      def mock_step(activity, path:, &block)
+        raise ArgumentError, "Missing block: `#mock_step` requires a block." unless block_given?
+
+        mocked_step_id, path = path.last, path[0..-2]
+
+        mock_step = ->(ctx, **) { yield(ctx) }
+        mock_instruction = -> { step mock_step, replace: mocked_step_id }
+
+
+        Trailblazer::Activity::DSL::Linear::Patch.(activity, path, mock_instruction)
+      end
+    end
+  end
+end
+
+# [:delete_assets] => -> { step Destroy.method(:tidy_storage), before: :rm_uploads }