rspec-activerecord-expectations 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6e24b218adcab0f1e6fb117d66463a2cdf60996fe5c16f60d48f8efd37c3259
-  data.tar.gz: 4f0acb5f4c489f4b2ded11b7d27a1bec613d231b04d836f651a26daf1bdb5bb1
+  metadata.gz: 3205b050d5f2164b5bc72de9fe29a0f6d988cd869ecd6703a09b83b2550bb02e
+  data.tar.gz: d43d363888f5c8f85dc551fae7d1381a945ac304c597192544ffd1506d1f7495
 SHA512:
-  metadata.gz: d077a6aa43e9f243a4be0d5b4db338a2aa3272e49974b8cc9b987499571de846e6f5cbc4c9d1f4d3d58d50b1d91ce3d361f2719ee3073ae8eeeee589a62d3e8c
-  data.tar.gz: 4473b4f016d10ca617e4ef5b3b1550c44903a170e9fde1291a88097a264028a0e21383fa37324f063c9529412c52e70e6fb24fab9e7a6df2382568f6a763fbc5
+  metadata.gz: a98cfac5ba127c3e5f7bd2b42ef48fa56e6750e75d0ab841988b076a2a39c0ca13e5d67e534020fd81af3b7885cba3d192c23a2fbb0b4ccd0d8e725e3cafb147
+  data.tar.gz: 65347df27d406531b1ea594bfe9a3d9b6405c75ad5f8be5c3f52f668e3d976e0e73c5e1560caeb308cb203b73547ab18c0ffd758aff0e913a9f010665a0a6595

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.2.0] - 2022-01-14
+- Adds transaction matcher to verify that code was executed within a
+  transaction at minimum
+- Transaction matcher also allows for commits and rollbacks
+- Update README for accompanying functionality
+
 ## [2.1.1] - 2022-01-12
 - Gemspec is really generated using the version of ruby that's locally in use.
   Update that build artifact to use non-java dependencies.

data/README.md

@@ -181,7 +181,57 @@ expect {}.to execute.exactly(20).transaction_queries
 categories, nor are queries that load the DB schema.
 
 **Note:** Destroy and delete queries are both condensed into the matcher for
-`destroy_queries`.
+the errorthe error  `destroy_queries`.
+
+## Transaction Management
+
+Sometimes, it makes sense to monitor whether database transactions were
+successful or not. This is very similar to using `expect{}.to change(SomeModel,
+:count)` in a spec, but nonetheless it can be useful to assert transactions
+themselves. Some assertions are available for this purpose.
+
+```ruby
+expect {}.to execute_a_transaction
+expect {}.to rollback_a_transaction
+expect {}.to roll_back_a_transaction
+expect {}.to commit_a_transaction
+```
+
+A complication to this scheme is that Rails tries not to make unnecessary database
+calls, which means that attempting to save a model that has failing validations
+won't actually attempt to save to the database.
+
+```ruby
+expect {
+  MyClass.create!(required_field: nil)
+}.to rollback_a_transaction
+```
+
+This assertion will fail, as `create!` will never make it as far as the
+database.  That said, if you manually create a transaction, _and you select
+data within that transaction_, you may assert a rollback.
+
+```ruby
+expect {
+  MyClass.first # triggers the transaction
+  MyClass.create!(required_field: nil)
+}.to rollback_a_transaction
+```
+
+It you need to make transaction-related assertions of this sort, your best bet
+may be to assert that a commit statement was _not_ issued.
+
+```ruby
+expect do
+  MyClass.create!(required_field: nil)
+rescue
+  # NOOP
+end.not_to rollback_a_transaction
+```
+
+Note that ActiveRecord will not only roll back the transaction, but also
+re-raise errors. As such, it's necessary in this example to rescue that
+error in order for the test to fail.
 
 ## Future Planned Functionality
 
@@ -194,14 +244,13 @@ expect {}.to execute.at_least(2).load_queries("Audited::Audit")
 expect {}.to execute.at_least(2).activerecord_queries
 expect {}.to execute.at_least(2).hand_rolled_queries
 
-expect {}.not_to rollback_transaction.exactly(5).times
-expect {}.not_to commit_transaction.once
-expect {}.to run_a_transaction
-
 expect {}.to create.exactly(5).of_type(User)
 expect {}.to insert.exactly(5).subscription_changes
 expect {}.to update.exactly(2).of_any_type
 expect {}.to delete.exactly(2).of_any_type
+
+expect {}.to commit_a_transaction.once
+expect {}.to rollback_a_transaction.exactly(5).times
 ```
 
 - warn if we smite any built in methods (or methods from other libs)

data/lib/rspec/activerecord/expectations/matchers/transaction_matcher.rb

@@ -0,0 +1,70 @@
+module RSpec::ActiveRecord::Expectations
+  module Matchers
+    class TransactionMatcher
+      def initialize(transaction_type)
+        @collector    = Collector.new
+        @transaction  = transaction_type
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def matches?(block)
+        block.call
+
+        @count = @collector.queries_of_type(@transaction)
+        @count > 0
+      end
+
+      def failure_message
+        type_msg = case @transaction
+                   when :transaction_queries
+                     "execute a transaction"
+                   when :rollback_queries
+                     "roll back a transaction"
+                   when :commit_queries
+                     "commit a transaction"
+                   end
+
+        "expected block to #{type_msg}, but it didn't do so"
+      end
+
+      def failure_message_when_negated
+        if @count == 1
+          negated_message_singular
+        else
+          negated_message_plural
+        end
+      end
+
+      private
+
+      def negated_message_singular
+        pre_msg, post_msg  = case @transaction
+                             when :transaction_queries
+                               ["execute a transaction", "executed one"]
+                             when :rollback_queries
+                               ["roll back a transaction", "rolled one back"]
+                             when :commit_queries
+                               ["commit a transaction", "committed one"]
+                             end
+
+        "expected block not to #{pre_msg}, but it #{post_msg}"
+      end
+
+      def negated_message_plural
+        pre_msg, post_msg = case @transaction
+                   when :transaction_queries
+                     ["execute a transaction", "executed #{@count} transactions"]
+                   when :rollback_queries
+                     ["roll back a transaction", "rolled back #{@count} transactions"]
+                   when :commit_queries
+                     ["commit a transaction", "committed #{@count} transactions"]
+                   end
+
+        "expected block not to #{pre_msg}, but it #{post_msg}"
+      end
+    end
+  end
+end

data/lib/rspec/activerecord/expectations/query_inspector.rb

@@ -1,14 +1,19 @@
 module RSpec::ActiveRecord::Expectations
   class QueryInspector
     def self.valid_query_types
-      [:queries, :schema_queries, :transaction_queries, :insert_queries,
-       :load_queries, :destroy_queries, :exists_queries]
+      [:queries, :schema_queries, :insert_queries, :load_queries,
+       :destroy_queries, :exists_queries,
+       :transaction_queries, :commit_queries, :rollback_queries]
     end
 
     def categorize(query)
       if query[:name] == "SCHEMA"
         [:schema_queries]
-      elsif query[:name] == "TRANSACTION" || query[:sql] =~ /^begin/i || query[:sql] =~ /^commit/i
+      elsif query[:sql] =~ /^commit/i
+        [:commit_queries]
+      elsif query[:sql] =~ /^rollback/i
+        [:rollback_queries]
+      elsif query[:name] == "TRANSACTION"
         [:transaction_queries]
       elsif query[:name] =~ /Create$/
         [:queries, :insert_queries]

data/lib/rspec/activerecord/expectations.rb

@@ -8,6 +8,22 @@ module RSpec
       def repeatedly_load(klass)
         Matchers::LoadMatcher.new(klass)
       end
+
+      def execute_a_transaction
+        Matchers::TransactionMatcher.new(:transaction_queries)
+      end
+
+      def rollback_a_transaction
+        Matchers::TransactionMatcher.new(:rollback_queries)
+      end
+
+      def roll_back_a_transaction
+        Matchers::TransactionMatcher.new(:rollback_queries)
+      end
+
+      def commit_a_transaction
+        Matchers::TransactionMatcher.new(:commit_queries)
+      end
     end
   end
 end
@@ -17,3 +33,4 @@ require_relative 'expectations/query_inspector'
 require_relative 'expectations/collector'
 require_relative 'expectations/matchers/query_count_matcher'
 require_relative 'expectations/matchers/load_matcher'
+require_relative 'expectations/matchers/transaction_matcher'

data/rspec-activerecord-expectations.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "rspec-activerecord-expectations"
-  spec.version       = '2.1.1'
+  spec.version       = '2.2.0'
   spec.authors       = ["Joseph Mastey"]
   spec.email         = ["hello@joemastey.com"]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-activerecord-expectations
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Joseph Mastey
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-13 00:00:00.000000000 Z
+date: 2022-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -104,6 +104,7 @@ files:
 - lib/rspec/activerecord/expectations/errors.rb
 - lib/rspec/activerecord/expectations/matchers/load_matcher.rb
 - lib/rspec/activerecord/expectations/matchers/query_count_matcher.rb
+- lib/rspec/activerecord/expectations/matchers/transaction_matcher.rb
 - lib/rspec/activerecord/expectations/query_inspector.rb
 - rspec-activerecord-expectations.gemspec
 homepage: https://github.com/jmmastey/rspec-activerecord-expectations