rspec_power 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15e38ae448c0c4dfeb0251c6186f5fff49aeb9fc36b68ee2c307e5bb9956a0e3
+  data.tar.gz: 29e94be5c241dcf1f839e5494c41d1327b289c8a6763a1cab3cda2ef4d601e81
+SHA512:
+  metadata.gz: 5966690eb7da430b3e2ddd99acee303efb0c46909b6dca64d4d116fe12264d4e6fb40b215128850e4392f74fb152515e2dc2c667de2c8be52695467eaafe697f
+  data.tar.gz: 2b1c5ce8f74d29bbb54715aa8d4f9255a685f4e624073508e2fc2209d99a65bfcae6339d306a6bcc482641dc1325507781838a5c1dce7ed3b7d37b61128e8dac

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Igor Kasyanchuk
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,503 @@
+# RSpec Power 🔥
+
+[![Gem Version](https://badge.fury.io/rb/rspec_power.svg)](https://badge.fury.io/rb/rspec_power)
+[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![RailsJazz](https://github.com/igorkasyanchuk/rails_time_travel/blob/main/docs/my_other.svg?raw=true)](https://www.railsjazz.com)
+
+A powerful collection of RSpec helpers and utilities that supercharge your Rails testing experience! 🚀
+
+## ✨ Features
+
+| Feature | Summary | Usage |
+| --- | --- | --- |
+| [🔍 Enhanced Logging](#-enhanced-logging) | Capture and control Rails logs; ActiveRecord-only option | `:with_log`, `:with_logs`, `:with_log_ar`, `with_logging`, `with_ar_logging` |
+| [🌍 Environment Management](#-environment-variable-management) | Override environment variables with auto-restore | `:with_env`, `with_test_env` |
+| [🌐 I18n Testing](#-internationalization-i18n-testing) | Switch locales and assert translations | `:with_locale`, `with_locale` |
+| [⏰ Time Freeze](#-time-freeze) | Freeze/travel time for deterministic tests | `:with_time_freeze` |
+| [🕘 Time Zone](#-time-zone) | Run examples in a specific time zone | `:with_time_zone` |
+| [⚡ Performance Budgeting](#-performance-budgeting) | Enforce maximum example execution time | `with_maximum_execution_time`, `:with_maximum_execution_time` |
+| [📏 Benchmarking](#-benchmarking) | Run examples multiple times and summarize | `with_benchmark: { runs: N }` |
+| [🔒 CI Guards](#-ci-guards) | Conditionally run or skip on CI | `:with_ci_only`, `:with_skip_ci` |
+| [🧪 SQL Guards](#-sql-guards) | Ensure no SQL or require at least one | `expect_no_sql`, `:with_no_sql_queries`, `expect_sql`, `:with_sql_queries` |
+| [💾 Request Dump](#-request-dump) | Dump session, cookies, flash, headers after each example | `:with_request_dump`, `with_request_dump: { what: [:session, :cookies, :flash, :headers] }` |
+| [🛢 DB Dump on Failure](#-db-dump-on-failure) | Dump DB tables to CSV when an example fails | `:with_dump_db_on_fail`, `with_dump_db_on_fail: { tables: [...], except: [...] }` |
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+group :test do
+  gem "rspec_power", require: false
+end
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## 🚀 Quick Start
+
+The gem automatically configures itself when required. Just add it to your Gemfile.
+
+## 📚 Usage Examples
+
+### 🔍 Enhanced Logging
+
+Capture all Rails logs during specific tests:
+
+```ruby
+RSpec.describe User, :with_log do
+  it "creates a user with logging" do
+    # All Rails logs will be captured and displayed
+    user = User.create!(name: "John Doe", email: "john@example.com")
+    expect(user).to be_persisted
+  end
+end
+```
+
+or for specific tests (alias `:with_logs` is also supported):
+
+```ruby
+RSpec.describe User do
+  it "creates a user with logging", :with_log do
+    # All Rails logs will be captured and displayed
+    user = User.create!(name: "John Doe", email: "john@example.com")
+    expect(user).to be_persisted
+  end
+end
+```
+
+Capture only ActiveRecord logs:
+
+```ruby
+RSpec.describe User, :with_log_ar do
+  it "shows SQL queries" do
+    # Only ActiveRecord logs will be captured
+    users = User.where(active: true).includes(:profile)
+    expect(users).to be_any
+  end
+end
+```
+
+Manual logging control:
+
+```ruby
+RSpec.describe User do
+  it "manually controls logging" do
+    with_logging do
+      # All Rails logs captured here
+      User.create!(name: "Jane")
+    end
+    # Logging back to normal here
+  end
+
+  it "captures only ActiveRecord logs" do
+    with_ar_logging do
+      # Only ActiveRecord logs captured here
+      User.count
+    end
+  end
+end
+```
+
+### 🧪 SQL Guards
+
+Ensure a block performs no SQL:
+
+```ruby
+RSpec.describe CacheWarmup do
+  it "does not hit the DB" do
+    expect_no_sql do
+      CacheWarmup.build_in_memory!
+    end
+  end
+end
+```
+
+Require that a block performs at least one SQL statement:
+
+```ruby
+RSpec.describe MigrationChecker do
+  it "touches the DB" do
+    expect_sql do
+      ActiveRecord::Base.connection.execute("SELECT 1")
+    end
+  end
+end
+```
+
+Or tag an example/group to enforce or require queries automatically:
+
+```ruby
+RSpec.describe CacheWarmup, :with_no_sql_queries do
+  it "builds entirely in memory" do
+    CacheWarmup.build_in_memory!
+  end
+end
+
+RSpec.describe MigrationChecker, :with_sql_queries do
+  it "must hit the DB at least once" do
+    ActiveRecord::Base.connection.execute("SELECT 1")
+  end
+end
+
+Supported tags: `:with_no_sql_queries`, `:with_sql_queries`
+```
+
+### 🌍 Environment Variable Management
+
+Override environment variables for specific tests:
+
+```ruby
+RSpec.describe PaymentService, :with_env do
+  it "uses test API key", with_env: { 'STRIPE_API_KEY' => 'test_key_123' } do
+    service = PaymentService.new
+    expect(service.api_key).to eq('test_key_123')
+  end
+
+  it "handles multiple env vars", with_env: {
+    'RAILS_ENV' => 'test',
+    'DATABASE_URL' => 'postgresql://localhost/test_db'
+  } do
+    expect(ENV['RAILS_ENV']).to eq('test')
+    expect(ENV['DATABASE_URL']).to eq('postgresql://localhost/test_db')
+  end
+end
+```
+
+Manual environment control:
+
+```ruby
+RSpec.describe ConfigService do
+  it "manually overrides environment" do
+    with_test_env('API_URL' => 'https://api.test.com') do
+      expect(ENV['API_URL']).to eq('https://api.test.com')
+    end
+    # Environment restored automatically
+  end
+end
+```
+
+### 🌐 Internationalization (I18n) Testing
+
+Test your application in different locales:
+
+```ruby
+RSpec.describe User, :with_locale do
+  it "displays name in English", with_locale: :en do
+    user = User.new(name: "John")
+    expect(user.greeting).to eq("Hello, John!")
+  end
+
+  it "displays name in Spanish", with_locale: :es do
+    user = User.new(name: "Juan")
+    expect(user.greeting).to eq("¡Hola, Juan!")
+  end
+
+  it "displays name in French", with_locale: :fr do
+    user = User.new(name: "Jean")
+    expect(user.greeting).to eq("Bonjour, Jean!")
+  end
+end
+```
+
+Manual locale control:
+
+```ruby
+RSpec.describe LocalizationHelper do
+  it "manually changes locale" do
+    with_locale(:de) do
+      expect(I18n.locale).to eq(:de)
+      expect(t('hello')).to eq('Hallo')
+    end
+    # Locale restored automatically
+  end
+end
+```
+
+### ⏰ Time Freeze
+
+Freeze time for consistent test results:
+
+```ruby
+RSpec.describe Order, :with_time_freeze do
+  it "creates order with current timestamp", with_time_freeze: "2024-01-15 10:30:00" do
+    order = Order.create!(amount: 100)
+    expect(order.created_at).to eq(Time.parse("2024-01-15 10:30:00"))
+  end
+
+  it "handles time-sensitive logic", with_time_freeze: Time.new(2024, 12, 25, 12, 0, 0) do
+    expect(Time.current).to eq(Time.new(2024, 12, 25, 12, 0, 0))
+    # Test Christmas-specific logic
+  end
+end
+```
+
+### 🕘 Time Zone
+
+```ruby
+RSpec.describe ReportGenerator do
+  it "builds report in US Pacific", with_time_zone: "Pacific Time (US & Canada)" do
+    # The block runs with Time.zone set to Pacific
+    expect(Time.zone.name).to eq("Pacific Time (US & Canada)")
+  end
+end
+```
+
+### ⚡ Performance Budgeting
+
+Limit example duration:
+
+```ruby
+RSpec.describe Importer do
+  it "is fast enough" do
+    with_maximum_execution_time(50) do
+      Importer.run!
+    end
+  end
+end
+```
+
+Or via metadata:
+
+```ruby
+RSpec.describe Importer, with_maximum_execution_time: 100 do
+  it "completes quickly" do
+    Importer.run!
+  end
+end
+```
+
+### 📏 Benchmarking
+
+Benchmark entire examples via metadata and get a suite summary:
+
+```ruby
+RSpec.describe Parser, with_benchmark: { runs: 10 } do
+  it "parses quickly" do
+    Parser.parse!(payload)
+  end
+end
+```
+
+The example is executed multiple times (runs) and the average/min/max times are printed after the suite.
+
+### 💾 Request Dump
+
+Dump request-related state after each example to help debug request specs.
+
+Supported items:
+
+- `:session`
+- `:cookies`
+- `:flash`
+- `:headers`
+
+Enable for an example or group and choose what to dump:
+
+```ruby
+RSpec.describe "Users API", type: :request do
+  it "dumps everything by default", :with_request_dump do
+    post "/set_state"
+    expect(response).to be_successful
+  end
+
+  it "dumps only session and cookies",
+     with_request_dump: { what: [:session, :cookies] } do
+    post "/set_state"
+    expect(response).to be_successful
+  end
+end
+```
+
+Example output:
+
+```
+[rspec_power] Dump after example: Users API dumps everything by default
+[rspec_power] session: {"user_id"=>42}
+[rspec_power] cookies: {"hello"=>"world"}
+[rspec_power] flash: {"notice"=>"done"}
+[rspec_power] headers: { ... }
+```
+
+### 🔒 CI Guards
+
+Run or skip specs depending on whether the suite is running on CI.
+
+- Tag to run only on CI: `:with_ci_only`
+- Tag to skip on CI: `:with_skip_ci`
+
+```ruby
+RSpec.describe Deployment, :with_ci_only do
+  it "runs only on CI" do
+    expect(ENV["CI"]).to be_present
+  end
+end
+
+RSpec.describe HeavySpec, :with_skip_ci do
+  it "skips on CI" do
+    # expensive checks
+  end
+end
+```
+
+CI detection via environment variable:
+
+The guards rely on the `CI` environment variable:
+
+- Considered CI when `ENV["CI"]` is set to any non-empty value other than `"false"` or `"0"` (case-insensitive).
+- Considered non-CI when `ENV["CI"]` is unset/empty, `"false"`, or `"0"`.
+
+Examples:
+
+```bash
+# Run a single file as if on CI
+CI=true bundle exec rspec spec/path/to/file_spec.rb
+
+# Also treated as CI
+CI=1 bundle exec rspec
+
+# Explicitly run as non-CI
+CI=0 bundle exec rspec
+```
+
+### 🛢 DB Dump on Failure
+
+Dump database state to CSV files when an example fails. Useful to inspect exactly what data led to the failure.
+
+- Defaults:
+  - Dumps all non-empty tables, excluding `schema_migrations` and `ar_internal_metadata`
+  - Exports each table to a separate CSV, ordered by primary key (if present)
+  - Writes to `tmp/rspec_power/db_failures/<timestamp>_<spec-name>/`
+  - Includes `metadata.json` with spec info
+
+Enable for an example or group:
+
+```ruby
+RSpec.describe User, :with_dump_db_on_fail do
+  it "creates a user" do
+    # ...
+  end
+end
+```
+
+Customize which tables to include/exclude and output directory:
+
+```ruby
+RSpec.describe Report, with_dump_db_on_fail: {
+  tables: ["users", "accounts"],
+  except: ["accounts"],
+  dir: Rails.root.join("tmp", "db_dumps").to_s
+} do
+  it "fails and dumps only selected tables" do
+    # ...
+  end
+end
+```
+
+Options:
+
+- `tables` / `only`: whitelist tables to dump
+- `except` / `exclude`: tables to skip
+- `dir`: base output directory (default: `tmp/rspec_power/db_failures`)
+
+Compatibility: the legacy tag `:dump_db_on_fail` remains supported as an alias.
+
+## 🎯 Shared Contexts
+
+The gem provides several pre-configured shared contexts:
+
+- `rspec_power::logging:verbose` - Enables verbose logging for tests with `:with_log` metadata
+- `rspec_power::logging:active_record` - Enables ActiveRecord logging for tests with `:with_log_ar` metadata
+- `rspec_power::env:override` - Automatically handles environment variable overrides
+- `rspec_power::i18n:dynamic` - Manages locale changes for tests with `:with_locale` metadata
+- `rspec_power::time:freeze` - Handles time freezing for tests with `:with_time_freeze` metadata
+- `rspec_power::time:zone` - Executes examples in a given time zone with `:with_time_zone` metadata
+- `rspec_power::ci:only` - Runs examples only in CI when tagged with `:with_ci_only`
+- `rspec_power::ci:skip` - Skips examples in CI when tagged with `:with_skip_ci`
+- `rspec_power::request_dump:after` - Dumps selected request state after each example with `:with_request_dump` metadata
+
+## 🔧 Configuration
+
+The gem automatically configures itself, but you can customize the behavior:
+
+```ruby
+# In spec_helper.rb or rails_helper.rb
+RSpec.configure do |config|
+  # Customize logging behavior
+  config.include RSpecPower::Rails::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
+
+  # Customize environment helpers
+  config.include RSpecPower::Rails::EnvHelpers
+  config.include_context "rspec_power::env:override", :with_env
+
+  # Customize I18n helpers
+  config.include RSpecPower::Rails::I18nHelpers
+  config.include_context "rspec_power::i18n:dynamic", :with_locale
+
+  # Customize time helpers
+  config.include RSpecPower::Rails::TimeHelpers
+  config.include_context "rspec_power::time:freeze", :with_time_freeze
+  config.include_context "rspec_power::time:zone", :with_time_zone
+
+  # CI-only guards
+  config.include_context "rspec_power::ci:only", :with_ci_only
+  config.include_context "rspec_power::ci:skip", :with_skip_ci
+
+  # Request dump helpers (session/cookies/flash/headers)
+  config.include RSpecPower::RequestDumpHelpers
+  config.include_context "rspec_power::request_dump:after", :with_request_dump
+end
+```
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+## Linter
+
+```bash
+bundle exec rubocop
+```
+
+To fix most issues, run:
+
+```bash
+bundle exec rubocop -A
+```
+
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📖 Credits
+
+Code for logging was extracted from [test-prof](https://github.com/test-prof/test-prof) gem.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [MIT-LICENSE](MIT-LICENSE) file for details.
+
+---
+
+[<img src="https://github.com/igorkasyanchuk/rails_time_travel/blob/main/docs/more_gems.png?raw=true"
+/>](https://www.railsjazz.com/?utm_source=github&utm_medium=bottom&utm_campaign=rails_performance)
+
+[!["Buy Me A Coffee"](https://github.com/igorkasyanchuk/get-smart/blob/main/docs/snapshot-bmc-button.png?raw=true)](https://buymeacoffee.com/igorkasyanchuk)
+
+Made with ❤️ for the Rails testing community!

data/Rakefile

@@ -0,0 +1,20 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+
+# plugin’s own specs
+RSpec::Core::RakeTask.new(:spec)
+
+# dummy app specs
+namespace :dummy do
+  desc "Run dummy Rails app specs"
+  task :spec do
+    Dir.chdir("spec/dummy") { sh "bundle exec rspec" }
+  end
+end
+
+task default: [ :spec, "dummy:spec" ]

data/lib/rspec_power/benchmark.rb

@@ -0,0 +1,74 @@
+module RSpecPower
+  module BenchmarkHelpers
+      class << self
+        def results_registry
+          @results_registry ||= []
+        end
+
+        def add_result(result)
+          results_registry << result
+        end
+
+        def results
+          results_registry.dup
+        end
+      end
+
+      # Internal: run the given block multiple times and record a summary.
+      # Used by the shared context, not exposed as a public helper anymore.
+      def __run_benchmark__(runs: 1, label:)
+        raise ArgumentError, "__run_benchmark__ requires a block" unless block_given?
+
+        iterations = runs.to_i
+        raise ArgumentError, "runs must be >= 1" if iterations < 1
+
+        timings_ms = []
+        iterations.times do
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          yield
+          finish = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          timings_ms << (finish - start) * 1000.0
+        end
+
+        avg = timings_ms.sum / timings_ms.length
+        summary = {
+          label: label,
+          runs: iterations,
+          avg_ms: avg,
+          min_ms: timings_ms.min,
+          max_ms: timings_ms.max
+        }
+
+        BenchmarkHelpers.add_result(summary)
+        summary
+      end
+  end
+end
+
+# Shared context to configure benchmark with metadata
+RSpec.shared_context "rspec_power::benchmark:run" do
+  around(:each) do |example|
+    opts = example.metadata[:with_benchmark]
+    if opts
+      runs = (opts[:runs] || 1).to_i
+      label = example.full_description
+      extend RSpecPower::BenchmarkHelpers
+      __run_benchmark__(runs: runs, label: label) { example.run }
+    else
+      example.run
+    end
+  end
+end
+
+# Print a consolidated report after the suite finishes
+RSpec.configure do |config|
+  config.after(:suite) do
+    results = RSpecPower::BenchmarkHelpers.results
+    next if results.empty?
+
+    puts "\nBenchmark results (rspec_power):"
+    results.each do |r|
+      puts "- #{r[:label]}: runs=#{r[:runs]} avg=#{format('%.3f', r[:avg_ms])}ms min=#{format('%.3f', r[:min_ms])}ms max=#{format('%.3f', r[:max_ms])}ms"
+    end
+  end
+end

data/lib/rspec_power/ci.rb

@@ -0,0 +1,21 @@
+RSpec.shared_context "rspec_power::ci:only" do
+  around(:each) do |example|
+    ci = ENV["CI"].to_s.downcase
+    if ci == "" || ci == "false" || ci == "0"
+      skip "Skipped in non-CI environment"
+    else
+      example.run
+    end
+  end
+end
+
+RSpec.shared_context "rspec_power::ci:skip" do
+  around(:each) do |example|
+    ci = ENV["CI"].to_s.downcase
+    if ci != "" && ci != "false" && ci != "0"
+      skip "Skipped in CI environment"
+    else
+      example.run
+    end
+  end
+end