expect_query 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3b8b4ed6d2b74521cc8ba8b8c3d916cccb41270c4c41823bc24ece67d51e2ba
+  data.tar.gz: 9dad000453c5308bde228f74313820d502efcc8ddab0ea4d64012d1c2cfb8a9d
+SHA512:
+  metadata.gz: 74308e0df458e741d4cb8af5b079b164858ab846bfca7d4253fb4c1b5018c8f5aa254b1085d23ec92f44a06fc019b75d20e75837f2df52af7e688d95f9955f5d
+  data.tar.gz: bb3009cbc2d35194b6dc4e30aa1807ed70b313d56c8767303eec51e44757224e767f88d171824ad244a2ffb859ec2d3f86c6617ec0d2ce2ca6b739384ec4a94b

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.1

data/.whitesource

@@ -0,0 +1,14 @@
+{
+  "scanSettings": {
+    "baseBranches": []
+  },
+  "checkRunSettings": {
+    "vulnerableCheckRunConclusionLevel": "failure",
+    "displayMode": "diff",
+    "useMendCheckNames": true
+  },
+  "issueSettings": {
+    "minSeverityLevel": "LOW",
+    "issueType": "DEPENDENCY"
+  }
+}

data/README.md

@@ -0,0 +1,128 @@
+# ExpectQuery
+
+`expect_query` provides Rails 8.0+ compatible assertions and matchers for counting SQL queries and Cache operations. It supports both RSpec and Minitest.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'expect_query', group: :test
+```
+
+## Usage
+
+### RSpec
+
+Add this to your `spec_helper.rb`:
+
+```ruby
+require "expect_query/rspec"
+```
+
+#### SQL Assertions
+
+```ruby
+expect { 
+  User.first 
+}.to make_sql_queries(1)
+
+expect { 
+  User.create(name: "Foo") 
+}.to make_sql_queries(1, matching: /INSERT/)
+
+expect {
+  # ...
+}.to make_sql_queries(at_most: 3)
+```
+
+#### Cache Assertions
+
+```ruby
+expect {
+  Rails.cache.read("foo")
+  Rails.cache.write("bar", 1)
+}.to perform_cache_operations(read: 1, write: 1)
+
+expect {
+  Rails.cache.fetch("foo") { 1 }
+}.to perform_cache_operations(total: 2) # read + write (if miss)
+```
+
+### Multiple Cache Stores
+
+By default, assertions use `Rails.cache` (if available). You can specify a different store or multiple stores using `store` or `stores` options.
+
+```ruby
+# RSpec
+expect {
+  my_cache.write("foo", 1)
+}.to perform_cache_operations(write: 1, store: my_cache)
+
+expect {
+  cache1.write("a", 1)
+  cache2.write("b", 1)
+}.to perform_cache_operations(total: 2, stores: [cache1, cache2])
+```
+
+```ruby
+# Minitest
+assert_cache_operations(write: 1, store: my_cache) do
+  my_cache.write("foo", 1)
+end
+```
+
+```ruby
+require "expect_query/minitest"
+```
+
+#### SQL Assertions
+
+```ruby
+assert_sql_queries(1) do
+  User.first
+end
+```
+
+#### Cache Assertions
+
+```ruby
+assert_cache_operations(read: 1, write: 1) do
+  Rails.cache.read("foo")
+  Rails.cache.write("bar", 1)
+end
+```
+
+## Failure Messages
+
+ExpectQuery provides detailed failure messages to help you debug.
+
+### SQL Failure Example
+
+```
+expected to make 1 SQL queries, but made 2
+Queries run:
+1. SELECT * FROM users
+2. UPDATE users SET name = 'foo'
+```
+
+### Cache Failure Example
+
+```
+expected to perform cache operations: total 10, 
+but got: total 2
+Cache operations performed:
+1. read: foo
+2. write: bar
+```
+
+## Development
+
+To run tests:
+
+```bash
+bundle exec rake
+```
+
+This runs both RSpec and Minitest suites.
+

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rake/testtask"
+
+RSpec::Core::RakeTask.new(:spec)
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: %i[spec test]

data/expect_query.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lib/expect_query/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "expect_query"
+  spec.version = ExpectQuery::VERSION
+  spec.authors = ["Jade Ornelas"]
+  spec.email = ["jade@ornelas.io"]
+
+  spec.summary = "A gem to assert SQL queries and Cache operations count."
+  spec.description = "Provides RSpec matchers and Minitest assertions to count SQL queries and Cache operations, supporting Rails 8.0+."
+  spec.homepage = "https://github.com/yknx4/expect_query"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/yknx4/expect_query"
+  spec.metadata["changelog_uri"] = "https://github.com/yknx4/expect_query/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Rails 8.0+ requirement
+  spec.add_dependency "activesupport", ">= 8.0"
+  spec.add_dependency "activerecord", ">= 8.0"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "sqlite3"
+end

data/lib/expect_query/cache_counter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ExpectQuery
+  class CacheCounter
+    attr_reader :counts, :log
+
+    VALID_EVENTS = %w[
+      cache_read.active_support
+      cache_write.active_support
+      cache_fetch_multi.active_support
+      cache_read_multi.active_support
+      cache_write_multi.active_support
+      cache_delete.active_support
+      cache_delete_multi.active_support
+      cache_exist?.active_support
+      cache_increment.active_support
+      cache_decrement.active_support
+    ].freeze
+
+    def initialize(matching: nil, store_ids: nil)
+      @matching = matching
+      @store_ids = store_ids
+      @counts = Hash.new(0)
+      @log = []
+    end
+
+    def call(name, _start, _finish, _message_id, payload)
+      if @store_ids
+        # If we are filtering by store, we must have a matching ID
+        return unless @store_ids.include?(payload[:expect_query_store_id])
+      end
+
+      # name is like "cache_read.active_support"
+      # We want to extract "read", "write", etc.
+      operation = name.split(".").first.sub(/^cache_/, "")
+      
+      key = payload[:key]
+      
+      if @matching
+        # Key can be a string or an array of strings (for multi operations)
+        if key.is_a?(Array)
+          return unless key.any? { |k| @matching.match?(k.to_s) }
+        else
+          return unless @matching.match?(key.to_s)
+        end
+      end
+
+      @counts[operation.to_sym] += 1
+      @counts[:total] += 1
+      @log << { operation: operation, key: key }
+    end
+  end
+end

data/lib/expect_query/minitest.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ExpectQuery
+  module MinitestAssertions
+    def assert_sql_queries(count = nil, matching: nil, at_most: nil, &block)
+      counter = ExpectQuery::SqlCounter.new(matching: matching)
+      ActiveSupport::Notifications.subscribed(counter, "sql.active_record") do
+        block.call
+      end
+      
+      actual = counter.count
+      
+      debug_info = ""
+      if counter.log.any?
+        debug_info = "\nQueries run:\n" + counter.log.map.with_index(1) { |sql, i| "#{i}. #{sql}" }.join("\n")
+      end
+
+      if at_most
+        assert actual <= at_most, "Expected at most #{at_most} SQL queries, but made #{actual}#{debug_info}"
+      elsif count
+        assert_equal count, actual, "Expected #{count} SQL queries, but made #{actual}#{debug_info}"
+      else
+        assert actual > 0, "Expected some SQL queries, but made none#{debug_info}"
+      end
+    end
+
+    def assert_cache_operations(count = nil, matching: nil, store: nil, stores: nil, **specific_counts, &block)
+      
+      target_stores = Array(stores || store)
+      if target_stores.empty? && defined?(::Rails) && ::Rails.respond_to?(:cache)
+        target_stores = [::Rails.cache]
+      end
+
+      store_ids = []
+      target_stores.each do |s|
+        unless s.singleton_class < ExpectQuery::StorePatch
+          s.singleton_class.prepend(ExpectQuery::StorePatch)
+        end
+        store_ids << s.object_id
+      end
+
+      pass_ids = store_ids.empty? ? nil : store_ids
+
+      counter = ExpectQuery::CacheCounter.new(matching: matching, store_ids: pass_ids)
+      
+      subscriber = ActiveSupport::Notifications.subscribe(/cache_.*\.active_support/, counter)
+      begin
+        block.call
+      ensure
+        ActiveSupport::Notifications.unsubscribe(subscriber)
+      end
+      
+      actual_counts = counter.counts
+      
+      debug_info = ""
+      if counter.log.any?
+        debug_info = "\nCache operations performed:\n" + counter.log.map.with_index(1) { |entry, i| "#{i}. #{entry[:operation]}: #{entry[:key]}" }.join("\n")
+      end
+      
+      if count
+        assert_equal count, actual_counts[:total].to_i, "Expected #{count} total cache operations, but got #{actual_counts[:total].to_i}#{debug_info}"
+      end
+      
+      specific_counts.each do |op, expected|
+        actual = actual_counts[op].to_i
+        assert_equal expected, actual, "Expected #{expected} #{op} cache operations, but got #{actual}#{debug_info}"
+      end
+    end
+  end
+end
+
+if defined?(Minitest::Test)
+  Minitest::Test.include ExpectQuery::MinitestAssertions
+end

data/lib/expect_query/rspec.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+module ExpectQuery
+  module RSpecMatchers
+    def make_sql_queries(count = nil, matching: nil, at_most: nil)
+      MakeSqlQueries.new(count, matching: matching, at_most: at_most)
+    end
+
+    def perform_cache_operations(count = nil, matching: nil, store: nil, stores: nil, **counts)
+      PerformCacheOperations.new(count, matching: matching, store: store, stores: stores, **counts)
+    end
+
+    class MakeSqlQueries
+      include RSpec::Matchers::Composable
+
+      def initialize(expected, matching: nil, at_most: nil)
+        @expected = expected
+        @matching = matching
+        @at_most = at_most
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def matches?(block)
+        @counter = ExpectQuery::SqlCounter.new(matching: @matching)
+        ActiveSupport::Notifications.subscribed(@counter, "sql.active_record") do
+          block.call
+        end
+        
+        @actual = @counter.count
+        
+        if @at_most
+          @actual <= @at_most
+        elsif @expected
+          @actual == @expected
+        else
+          @actual > 0 # generic "makes queries"
+        end
+      end
+
+      def failure_message
+        msg = "expected to make "
+        msg += "#{@expected} " if @expected
+        msg += "at most #{@at_most} " if @at_most
+        msg += "SQL queries"
+        msg += " matching #{@matching.inspect}" if @matching
+        msg += ", but made #{@actual}"
+        
+        if @counter.log.any?
+          msg += "\nQueries run:\n"
+          msg += @counter.log.map.with_index(1) { |sql, i| "#{i}. #{sql}" }.join("\n")
+        end
+        msg
+      end
+    end
+
+    class PerformCacheOperations
+      include RSpec::Matchers::Composable
+
+      def initialize(total = nil, matching: nil, store: nil, stores: nil, **specific_counts)
+        @total = total
+        @matching = matching
+        @specific_counts = specific_counts
+        @stores = Array(stores || store)
+        
+        if @stores.empty? && defined?(::Rails) && ::Rails.respond_to?(:cache)
+          @stores = [::Rails.cache]
+        end
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def matches?(block)
+        # Patch stores
+        store_ids = []
+        @stores.each do |store|
+          unless store.singleton_class < ExpectQuery::StorePatch
+            store.singleton_class.prepend(ExpectQuery::StorePatch)
+          end
+          store_ids << store.object_id
+        end
+
+        # If no stores are defined (e.g. no Rails.cache and no store passed), we can't strict filter by ID.
+        # But we probably should pass empty array if we intended to track but found nothing? 
+        # Or if store_ids is empty, maybe we track ALL?
+        # User said: "By default use Rails.cache". If Rails.cache is missing, maybe we should warn or track nothing?
+        # Let's pass nil if we want to track ALL, but if we defaulted to Rails.cache and it's there, we pass it.
+        # If user explicitly passed empty list?
+        pass_ids = store_ids.empty? ? nil : store_ids
+
+        @counter = ExpectQuery::CacheCounter.new(matching: @matching, store_ids: pass_ids)
+        
+        subscriber = ActiveSupport::Notifications.subscribe(/cache_.*\.active_support/, @counter)
+        begin
+          block.call
+        ensure
+          ActiveSupport::Notifications.unsubscribe(subscriber)
+        end
+        
+        @actual_counts = @counter.counts
+        
+        result = true
+        
+        if @total
+          result &&= (@actual_counts[:total].to_i == @total)
+        end
+        
+        @specific_counts.each do |op, count|
+           # op could be :read, :write
+           result &&= (@actual_counts[op].to_i == count)
+        end
+        
+        result
+      end
+
+      def failure_message
+        msg = "expected to perform cache operations: "
+        msg += "total #{@total}, " if @total
+        @specific_counts.each { |k, v| msg += "#{k}: #{v}, " }
+        msg += "matching #{@matching.inspect}" if @matching
+        msg += "\nbut got: "
+        msg += "total #{@actual_counts[:total].to_i}, "
+        @specific_counts.each { |k, _| msg += "#{k}: #{@actual_counts[k].to_i}, " }
+        
+        if @counter.log.any?
+          msg += "\nCache operations performed:\n"
+          msg += @counter.log.map.with_index(1) { |entry, i| "#{i}. #{entry[:operation]}: #{entry[:key]}" }.join("\n")
+        end
+        msg
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include ExpectQuery::RSpecMatchers
+end

data/lib/expect_query/sql_counter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ExpectQuery
+  class SqlCounter
+    attr_reader :count, :log
+
+    def initialize(matching: nil)
+      @matching = matching
+      @count = 0
+      @log = []
+    end
+
+    def call(_name, _start, _finish, _message_id, payload)
+      return if payload[:cached]
+
+      sql = payload[:sql]
+      
+      # Ignore schema queries, transactions, etc if needed. 
+      # For now, we only care about user queries, but let's keep it simple and filter later if requested.
+      # Common ignores: SCHEMA, TRANSACTION, EXPLAIN
+      return if %w[SCHEMA TRANSACTION EXPLAIN].include?(payload[:name])
+
+      if @matching
+        return unless @matching.match?(sql)
+      end
+
+      @count += 1
+      @log << sql
+    end
+  end
+end

data/lib/expect_query/store_patch.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ExpectQuery
+  module StorePatch
+    def instrument(name, key, options = nil, &block)
+      options ||= {}
+      options = options.dup unless options.frozen? # dup if possible to avoid mutation issues, though usually safe
+      options = options.merge(expect_query_store_id: object_id)
+      super(name, key, options, &block)
+    end
+  end
+end

data/lib/expect_query/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ExpectQuery
+  VERSION = "0.1.5"
+end

data/lib/expect_query.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "expect_query/version"
+require_relative "expect_query/store_patch"
+require_relative "expect_query/sql_counter"
+require_relative "expect_query/cache_counter"
+require "active_support"
+require "active_support/notifications"
+
+module ExpectQuery
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification
+name: expect_query
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: ruby
+authors:
+- Jade Ornelas
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides RSpec matchers and Minitest assertions to count SQL queries
+  and Cache operations, supporting Rails 8.0+.
+email:
+- jade@ornelas.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".tool-versions"
+- ".whitesource"
+- README.md
+- Rakefile
+- expect_query.gemspec
+- lib/expect_query.rb
+- lib/expect_query/cache_counter.rb
+- lib/expect_query/minitest.rb
+- lib/expect_query/rspec.rb
+- lib/expect_query/sql_counter.rb
+- lib/expect_query/store_patch.rb
+- lib/expect_query/version.rb
+homepage: https://github.com/yknx4/expect_query
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yknx4/expect_query
+  source_code_uri: https://github.com/yknx4/expect_query
+  changelog_uri: https://github.com/yknx4/expect_query/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: A gem to assert SQL queries and Cache operations count.
+test_files: []