rspec_power 0.1.0

data/lib/rspec_power/db_dump.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "csv"
+require "json"
+require "time"
+require "fileutils"
+
+module RSpecPower
+  module DbDumpHelpers
+    DEFAULT_EXCLUDED_TABLES = %w[schema_migrations ar_internal_metadata].freeze
+
+    def dump_database_on_failure(example, options = {})
+      return unless defined?(::ActiveRecord)
+
+      connection = ::ActiveRecord::Base.connection
+
+      base_dir = resolve_base_dir(options[:dir])
+      spec_label = sanitize_label(example.full_description)
+      timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+
+      tables = resolve_tables(connection, options)
+      non_empty_tables = tables.select { |t| table_has_rows?(connection, t) }
+
+      return nil if non_empty_tables.empty?
+
+      out_dir = File.join(base_dir, "#{timestamp}_#{spec_label}")
+      FileUtils.mkdir_p(out_dir)
+
+      non_empty_tables.each do |table|
+        csv_path = File.join(out_dir, "#{table}.csv")
+        dump_table_to_csv(connection, table, csv_path)
+      end
+
+      write_metadata(out_dir, example, non_empty_tables)
+
+      puts "[rspec_power] DB dump written to: #{out_dir}"
+      puts "[rspec_power] Tables: #{non_empty_tables.join(", ")}" unless non_empty_tables.empty?
+
+      out_dir
+    rescue => e
+      warn "[rspec_power] Failed to dump DB on failure: #{e.class}: #{e.message}"
+      nil
+    end
+
+    private
+
+    def resolve_base_dir(custom_dir)
+      return custom_dir if custom_dir && !custom_dir.to_s.strip.empty?
+
+      base = if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        Rails.root.join("tmp", "rspec_power", "db_failures").to_s
+      else
+        File.join(Dir.pwd, "tmp", "rspec_power", "db_failures")
+      end
+      FileUtils.mkdir_p(base)
+      base
+    end
+
+    def resolve_tables(connection, options)
+      specified = Array(options[:tables] || options[:only]).map(&:to_s)
+      excluded = Array(options[:except] || options[:exclude]).map(&:to_s)
+
+      all = connection.tables - DEFAULT_EXCLUDED_TABLES
+      list = specified.empty? ? all : (all & specified)
+      list - excluded
+    end
+
+    def table_has_rows?(connection, table)
+      qt = connection.quote_table_name(table)
+      sql = "SELECT 1 FROM #{qt} LIMIT 1"
+      !connection.select_value(sql).nil?
+    rescue
+      false
+    end
+
+    def dump_table_to_csv(connection, table, csv_path)
+      qt = connection.quote_table_name(table)
+      primary_key = safe_primary_key(connection, table)
+
+      sql = if primary_key
+        qc = connection.quote_column_name(primary_key)
+        "SELECT * FROM #{qt} ORDER BY #{qc} ASC"
+      else
+        "SELECT * FROM #{qt}"
+      end
+
+      result = connection.exec_query(sql)
+
+      CSV.open(csv_path, "w") do |csv|
+        csv << result.columns
+        result.rows.each { |row| csv << row }
+      end
+    end
+
+    def safe_primary_key(connection, table)
+      connection.primary_key(table)
+    rescue
+      nil
+    end
+
+    def sanitize_label(label)
+      label.to_s.gsub(/[^a-zA-Z0-9\-_]+/, "_")[0, 120]
+    end
+
+    def write_metadata(out_dir, example, tables)
+      meta = {
+        "spec" => example.full_description,
+        "id" => example.id,
+        "file_path" => example.metadata[:file_path],
+        "exception" => example.exception&.message,
+        "created_at" => Time.now.utc.iso8601,
+        "tables" => tables
+      }
+      File.write(File.join(out_dir, "metadata.json"), JSON.pretty_generate(meta))
+    rescue
+      # Fallback to plain text if JSON isn't available for some reason
+      File.write(
+        File.join(out_dir, "metadata.txt"),
+        [
+          "spec: #{example.full_description}",
+          "id: #{example.id}",
+          "file_path: #{example.metadata[:file_path]}",
+          "exception: #{example.exception&.message}",
+          "created_at: #{Time.now.utc.iso8601}",
+          "tables: #{tables.join(', ')}"
+        ].join("\n")
+      )
+    end
+  end
+end
+
+RSpec.shared_context "rspec_power::db_dump:on_fail" do
+  include RSpecPower::DbDumpHelpers
+
+  after(:each) do |example|
+    dump_meta = example.metadata[:with_dump_db_on_fail]
+    dump_meta = example.metadata[:dump_db_on_fail] if dump_meta.nil?
+    next unless dump_meta
+    next unless example.exception
+
+    options = dump_meta.is_a?(Hash) ? dump_meta : {}
+    dump_database_on_failure(example, options)
+  end
+end

data/lib/rspec_power/engine.rb

@@ -0,0 +1,5 @@
+module RSpecPower
+  class Engine < ::Rails::Engine
+    isolate_namespace RSpecPower
+  end
+end

data/lib/rspec_power/env.rb

@@ -0,0 +1,30 @@
+module RSpecPower
+  module EnvHelpers
+      def with_test_env(overrides = {})
+        old_values = overrides.each_with_object({}) do |(key, _), memo|
+          memo[key] = ENV.key?(key) ? ENV[key] : :__undefined__
+        end
+
+        # apply overrides (stringify keys just in case)
+        overrides.each { |k, v| ENV[k.to_s] = v }
+
+        yield
+      ensure
+        # restore old values
+        old_values.each do |key, val|
+          if val == :__undefined__
+            ENV.delete(key)
+          else
+            ENV[key] = val
+          end
+        end
+      end
+  end
+end
+
+RSpec.shared_context "rspec_power::env:override" do
+  around(:each) do |example|
+    overrides = example.metadata[:with_env] || {}
+    with_test_env(overrides) { example.run }
+  end
+end

data/lib/rspec_power/i18n.rb

@@ -0,0 +1,21 @@
+module RSpecPower
+  module I18nHelpers
+      def with_locale(locale)
+        old = I18n.locale
+        I18n.locale = locale
+        yield
+      ensure
+        I18n.locale = old
+      end
+  end
+end
+
+RSpec.shared_context "rspec_power::i18n:dynamic" do
+  around(:each) do |example|
+    if example.metadata.key?(:with_locale)
+      with_locale(example.metadata[:with_locale]) { example.run }
+    else
+      example.run
+    end
+  end
+end

data/lib/rspec_power/logging.rb

@@ -0,0 +1,112 @@
+require "logger"
+require "active_support/tagged_logging" if defined?(ActiveSupport::TaggedLogging)
+require "active_support/logger"         if defined?(ActiveSupport::Logger)
+require "active_record"                 if defined?(ActiveRecord)
+require "active_support/log_subscriber" if defined?(ActiveSupport::LogSubscriber)
+
+module RSpecPower
+  module LoggingHelpers
+      class << self
+        def logger=(new_logger)
+          @logger = new_logger
+          global_loggables.each { |l| l.logger = new_logger }
+        end
+
+        def logger
+          return @logger if defined?(@logger)
+          @logger = if defined?(ActiveSupport::TaggedLogging)
+            ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new($stdout))
+          elsif defined?(ActiveSupport::Logger)
+            ActiveSupport::Logger.new($stdout)
+          else
+            Logger.new($stdout)
+          end
+        end
+
+        def global_loggables
+          @global_loggables ||= []
+        end
+
+        def swap_logger(targets)
+          targets.map do |target|
+            old_logger = target.logger
+            begin
+              target.logger = logger
+            rescue NoMethodError
+              # Some classes expose .logger= only via class_attribute; try via Rails.logger
+              # but we still continue to next target to avoid halting.
+            end
+            old_logger
+          end
+        end
+
+        def restore_logger(old_loggers, targets)
+          targets.each_with_index { |t, i| t.logger = old_loggers[i] }
+        end
+
+        def all_loggables
+          base = [
+            (::Rails if defined?(::Rails)),
+            (::ActiveSupport::LogSubscriber if defined?(::ActiveSupport::LogSubscriber)),
+            (::ActiveRecord::Base          if defined?(::ActiveRecord::Base)),
+            (::ActionController::Base      if defined?(::ActionController::Base)),
+            (::ActiveJob::Base             if defined?(::ActiveJob::Base)),
+            (::ActionView::Base            if defined?(::ActionView::Base)),
+            (::ActionMailer::Base          if defined?(::ActionMailer::Base)),
+            (::ActionCable                 if defined?(::ActionCable))
+          ].compact
+
+          # Include all log subscribers for controller/action_view etc.
+          if defined?(::ActiveSupport::LogSubscriber)
+            ObjectSpace.each_object(Class).select { |c| c < ::ActiveSupport::LogSubscriber }.each do |subscriber|
+              base << subscriber if subscriber.respond_to?(:logger)
+            end
+          end
+
+          base.select { |l| l.respond_to?(:logger) }
+        end
+
+        def ar_loggables
+          @ar_loggables ||= [
+            ::ActiveRecord::Base,
+            ::ActiveSupport::LogSubscriber
+          ]
+        end
+      end
+
+      def with_logging
+        old = LoggingHelpers.swap_logger(LoggingHelpers.all_loggables)
+        yield
+      ensure
+        LoggingHelpers.restore_logger(old, LoggingHelpers.all_loggables)
+      end
+
+      def with_ar_logging
+        old = LoggingHelpers.swap_logger(LoggingHelpers.ar_loggables)
+        yield
+      ensure
+        LoggingHelpers.restore_logger(old, LoggingHelpers.ar_loggables)
+      end
+  end
+end
+
+RSpec.shared_context "rspec_power::logging:verbose" do
+  around(:each) do |ex|
+    if ex.metadata[:with_log] == true || ex.metadata[:with_log] == :all ||
+       ex.metadata[:with_logs] == true || ex.metadata[:with_logs] == :all
+      with_logging(&ex)
+    else
+      ex.call
+    end
+  end
+end
+
+RSpec.shared_context "rspec_power::logging:active_record" do
+  around(:each) do |ex|
+    if ex.metadata[:with_log_ar]
+      with_ar_logging(&ex)
+    else
+      ex.call
+    end
+  end
+end

data/lib/rspec_power/performance.rb

@@ -0,0 +1,32 @@
+module RSpecPower
+  module PerformanceHelpers
+      # Ensures the given block completes within the specified duration (milliseconds).
+      # Raises RSpec::Expectations::ExpectationNotMetError if the threshold is exceeded.
+      def with_maximum_execution_time(max_duration_ms)
+        raise ArgumentError, "with_maximum_execution_time requires a block" unless block_given?
+
+        max_ms = max_duration_ms.to_f
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        yield
+      ensure
+        elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
+        if elapsed_ms > max_ms
+          formatted_elapsed = format("%.3f", elapsed_ms)
+          formatted_limit = format("%.3f", max_ms)
+          raise RSpec::Expectations::ExpectationNotMetError,
+                "Execution time exceeded: #{formatted_elapsed}ms > #{formatted_limit}ms"
+        end
+      end
+  end
+end
+
+RSpec.shared_context "rspec_power::performance:maximum_execution_time" do
+  around(:each) do |example|
+    threshold = example.metadata[:with_maximum_execution_time]
+    if threshold
+      with_maximum_execution_time(threshold) { example.run }
+    else
+      example.run
+    end
+  end
+end

data/lib/rspec_power/request_dump.rb

@@ -0,0 +1,125 @@
+module RSpecPower
+  module RequestDumpHelpers
+    def dump_state_after_example(example, what_items)
+      items_to_dump = Array(what_items).map(&:to_sym)
+
+      puts "\n[rspec_power] Dump after example: #{example.full_description}"
+
+      if items_to_dump.include?(:session)
+        value = fetch_session_value
+        puts "[rspec_power] session: #{safe_inspect(value)}"
+      end
+
+      if items_to_dump.include?(:cookies)
+        value = fetch_cookies_value
+        puts "[rspec_power] cookies: #{safe_inspect(value)}"
+      end
+
+      if items_to_dump.include?(:flash)
+        value = fetch_flash_value
+        puts "[rspec_power] flash: #{safe_inspect(value)}"
+      end
+
+      if items_to_dump.include?(:headers)
+        value = fetch_headers_value
+        puts "[rspec_power] headers: #{safe_inspect(value)}"
+      end
+    end
+
+    private
+
+    def safe_inspect(value)
+      case value
+      when Hash
+        begin
+          value.transform_keys { |k| k.to_s }.inspect
+        rescue
+          value.inspect
+        end
+      else
+        value.inspect
+      end
+    end
+
+    def fetch_session_value
+      if respond_to?(:session)
+        coerce_to_hash(session)
+      elsif defined?(request) && request.respond_to?(:session)
+        coerce_to_hash(request.session)
+      elsif defined?(controller) && controller.respond_to?(:session)
+        coerce_to_hash(controller.session)
+      else
+        :unavailable
+      end
+    rescue => e
+      "unavailable (#{e.class}: #{e.message})"
+    end
+
+    def fetch_cookies_value
+      if respond_to?(:cookies)
+        coerce_to_hash(cookies)
+      elsif defined?(request) && request.respond_to?(:cookie_jar)
+        coerce_to_hash(request.cookie_jar)
+      elsif defined?(response) && response.respond_to?(:cookies)
+        coerce_to_hash(response.cookies)
+      else
+        :unavailable
+      end
+    rescue => e
+      "unavailable (#{e.class}: #{e.message})"
+    end
+
+    def fetch_flash_value
+      if respond_to?(:flash)
+        coerce_to_hash(flash)
+      elsif defined?(controller) && controller.respond_to?(:flash)
+        coerce_to_hash(controller.flash)
+      else
+        :unavailable
+      end
+    rescue => e
+      "unavailable (#{e.class}: #{e.message})"
+    end
+
+    def fetch_headers_value
+      if defined?(request) && request.respond_to?(:headers)
+        coerce_to_hash(request.headers)
+      elsif defined?(response) && response.respond_to?(:request) && response.request.respond_to?(:headers)
+        coerce_to_hash(response.request.headers)
+      elsif defined?(controller) && controller.respond_to?(:request) && controller.request.respond_to?(:headers)
+        coerce_to_hash(controller.request.headers)
+      else
+        :unavailable
+      end
+    rescue => e
+      "unavailable (#{e.class}: #{e.message})"
+    end
+
+    def coerce_to_hash(obj)
+      return {} if obj.nil?
+      return obj.to_hash if obj.respond_to?(:to_hash)
+      return obj.to_h if obj.respond_to?(:to_h)
+      if defined?(ActionDispatch::Request::Session) && obj.is_a?(ActionDispatch::Request::Session)
+        return obj.to_hash
+      end
+      obj.inspect
+    end
+  end
+end
+
+RSpec.shared_context "rspec_power::request_dump:after" do
+  include RSpecPower::RequestDumpHelpers
+
+  after(:each) do |example|
+    dump_meta = example.metadata[:with_request_dump]
+    next unless dump_meta
+
+    what = if dump_meta.is_a?(Hash) && dump_meta[:what]
+      dump_meta[:what]
+    else
+      [ :session, :cookies, :flash, :headers ]
+    end
+
+    dump_state_after_example(example, what)
+  end
+end

data/lib/rspec_power/sql.rb

@@ -0,0 +1,105 @@
+module RSpecPower
+  module ActiveRecordHelpers
+      # Fails the example if any SQL is executed within the provided block.
+      # Ignores cached, schema, and transaction events to avoid false positives.
+      def expect_no_sql
+        raise ArgumentError, "expect_no_sql requires a block" unless block_given?
+
+        executed_sql_statements = capture_executed_sql { yield }
+
+        if executed_sql_statements.any?
+          message = "Expected no SQL to be executed, but #{executed_sql_statements.length} statement(s) were run.\n" \
+                    + executed_sql_statements.map { |sql| "  - #{sql}" }.join("\n")
+          raise RSpec::Expectations::ExpectationNotMetError, message
+        end
+      end
+
+      # Passes only if at least one SQL statement is executed within the block.
+      # Ignores cached, schema, and transaction events to avoid false positives.
+      def expect_sql
+        raise ArgumentError, "expect_sql requires a block" unless block_given?
+
+        executed_sql_statements = capture_executed_sql { yield }
+
+        if executed_sql_statements.empty?
+          raise RSpec::Expectations::ExpectationNotMetError,
+                "Expected some SQL to be executed, but none was run"
+        end
+      end
+
+      private
+
+      # Subscribes to ActiveRecord SQL notifications and captures relevant statements
+      # executed within the given block. Returns an Array of SQL strings.
+      def capture_executed_sql
+        raise ArgumentError, "capture_executed_sql requires a block" unless block_given?
+
+        executed_sql_statements = []
+
+        notification_callback = lambda do |_name, _started, _finished, _unique_id, payload|
+          event_name = payload[:name].to_s
+          is_cached_event = payload[:cached]
+
+          # Skip noise that doesn't represent user-level SQL
+          next if is_cached_event
+          next if event_name == "SCHEMA" || event_name == "TRANSACTION"
+
+          executed_sql_statements << payload[:sql]
+        end
+
+        ActiveSupport::Notifications.subscribed(notification_callback, "sql.active_record") do
+          yield
+        end
+
+        executed_sql_statements
+      end
+  end
+end
+
+RSpec.shared_context "rspec_power::sql:none" do
+  around(:each) do |example|
+    executed_sql = []
+
+    callback = lambda do |_name, _started, _finished, _unique_id, payload|
+      event_name = payload[:name].to_s
+      cached = payload[:cached]
+      next if cached
+      next if event_name == "SCHEMA" || event_name == "TRANSACTION"
+
+      executed_sql << payload[:sql]
+    end
+
+    ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
+      example.run
+    end
+
+    if executed_sql.any?
+      message = "Expected no SQL to be executed, but #{executed_sql.length} statement(s) were run.\n" \
+                + executed_sql.map { |sql| "  - #{sql}" }.join("\n")
+      raise RSpec::Expectations::ExpectationNotMetError, message
+    end
+  end
+end
+
+RSpec.shared_context "rspec_power::sql:must" do
+  around(:each) do |example|
+    executed_sql = []
+
+    callback = lambda do |_name, _started, _finished, _unique_id, payload|
+      event_name = payload[:name].to_s
+      cached = payload[:cached]
+      next if cached
+      next if event_name == "SCHEMA" || event_name == "TRANSACTION"
+
+      executed_sql << payload[:sql]
+    end
+
+    ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
+      example.run
+    end
+
+    if executed_sql.empty?
+      raise RSpec::Expectations::ExpectationNotMetError, "Expected some SQL to be executed, but none was run"
+    end
+  end
+end

data/lib/rspec_power/time.rb

@@ -0,0 +1,37 @@
+require "active_support/testing/time_helpers"
+require "time"
+
+module RSpecPower
+  module TimeHelpers
+    include ActiveSupport::Testing::TimeHelpers
+
+    def with_time_zone(zone)
+      if defined?(ActiveSupport::TimeZone)
+        ::Time.use_zone(zone) { yield }
+      else
+        yield
+      end
+    end
+  end
+end
+
+RSpec.shared_context "rspec_power::time:freeze" do
+  around(:each) do |example|
+    if ts = example.metadata[:with_time_freeze]
+      ts = Time.parse(ts) if ts.is_a?(String)
+      travel_to(ts) { example.run }
+    else
+      example.run
+    end
+  end
+end
+
+RSpec.shared_context "rspec_power::time:zone" do
+  around(:each) do |example|
+    if zone = example.metadata[:with_time_zone]
+      with_time_zone(zone) { example.run }
+    else
+      example.run
+    end
+  end
+end

data/lib/rspec_power/version.rb

@@ -0,0 +1,3 @@
+module RSpecPower
+  VERSION = "0.1.0"
+end

data/lib/rspec_power.rb

@@ -0,0 +1,61 @@
+require "rspec_power/version"
+require "rspec_power/engine"
+require "rspec_power/logging"
+require "rspec_power/env"
+require "rspec_power/i18n"
+require "rspec_power/time"
+require "rspec_power/request_dump"
+require "rspec_power/db_dump"
+require "rspec_power/ci"
+require "rspec_power/sql"
+require "rspec_power/performance"
+require "rspec_power/benchmark"
+
+RSpec.configure do |config|
+  # Logging
+  config.include RSpecPower::LoggingHelpers
+  config.include_context "rspec_power::logging:verbose", with_log: true
+  config.include_context "rspec_power::logging:verbose", with_logs: true
+  config.include_context "rspec_power::logging:active_record", with_log_ar: true
+
+  # Environment variable overrides
+  config.include RSpecPower::EnvHelpers
+  config.include_context "rspec_power::env:override", :with_env
+
+  # I18n
+  config.include RSpecPower::I18nHelpers
+  config.include_context "rspec_power::i18n:dynamic", :with_locale
+
+  # Time manipulation
+  config.include RSpecPower::TimeHelpers
+  config.include_context "rspec_power::time:freeze", :with_time_freeze
+  config.include_context "rspec_power::time:zone", :with_time_zone
+
+  # CI-only guards
+  # Prefer new tags with "with_" prefix; keep old ones for compatibility
+  config.include_context "rspec_power::ci:only", :with_ci_only
+  config.include_context "rspec_power::ci:skip", :with_skip_ci
+  config.include_context "rspec_power::ci:only", :ci_only
+  config.include_context "rspec_power::ci:skip", :skip_ci
+
+  # SQL guards
+  config.include RSpecPower::ActiveRecordHelpers
+  config.include_context "rspec_power::sql:none", :with_no_sql_queries
+  config.include_context "rspec_power::sql:must", :with_sql_queries
+
+  # Performance
+  config.include RSpecPower::PerformanceHelpers
+  config.include_context "rspec_power::performance:maximum_execution_time", :with_maximum_execution_time
+
+  # Benchmark
+  config.include_context "rspec_power::benchmark:run", :with_benchmark
+
+  # Request dump helpers (session/cookies/flash/headers)
+  config.include RSpecPower::RequestDumpHelpers
+  config.include_context "rspec_power::request_dump:after", :with_request_dump
+
+  # DB dump on failure
+  # Prefer :with_dump_db_on_fail; keep :dump_db_on_fail for backward compatibility
+  config.include_context "rspec_power::db_dump:on_fail", :with_dump_db_on_fail
+  config.include_context "rspec_power::db_dump:on_fail", :dump_db_on_fail
+end