rspec_in_context 1.1.0.3 → 1.2.1

data/README.md

@@ -1,12 +1,69 @@
 # RspecInContext
 
 [![Gem Version](https://badge.fury.io/rb/rspec_in_context.svg)](https://badge.fury.io/rb/rspec_in_context)
-[![Codacy Badge](https://app.codacy.com/project/badge/Grade/6490834b08664dc898d0107c74a78357)](https://www.codacy.com/gh/zaratan/rspec_in_context/dashboard?utm_source=github.com&utm_medium=referral&utm_content=zaratan/rspec_in_context&utm_campaign=Badge_Grade)
 ![Test and Release badge](https://github.com/zaratan/rspec_in_context/workflows/Test%20and%20Release/badge.svg)
 
-This gem is here to help you write better shared_examples in Rspec.
+This gem is here to help you write better shared_examples in RSpec.
 
-Ever been bothered by the fact that they don't really behave like methods and that you can't pass it a block ? There you go: `rspec_in_context`
+Ever been bothered by the fact that they don't really behave like methods and that you can't pass them a block? There you go: `rspec_in_context`
+
+## Why not just shared_examples?
+
+`shared_examples` are great but they have a few limitations that can get annoying:
+
+**You can't inject a block of tests at a specific point.** With `shared_examples`, your tests are either all inside the shared example or all outside. There's no way to say "set things up, run _these_ tests, then tear down". With `in_context`, you place `execute_tests` exactly where you want the caller's block to be injected.
+
+**Composing them is awkward.** Nesting `it_behaves_like` inside another `shared_examples` works but reads poorly. `in_context` calls nest naturally, and you can use `in_context` inside a `define_context`.
+
+**They don't accept arguments naturally.** `shared_examples` rely on `let` or params passed via `include_examples`. `in_context` accepts arguments directly, like a method call:
+
+```ruby
+# shared_examples way
+shared_examples "validates presence" do
+  it { is_expected.not_to be_valid }
+end
+
+RSpec.describe User do
+  context "when email is nil" do
+    let(:email) { nil }
+    it_behaves_like "validates presence"
+  end
+  context "when name is nil" do
+    let(:name) { nil }
+    it_behaves_like "validates presence"
+  end
+end
+
+# in_context way
+RSpec.define_context :validates_presence do |field|
+  context "when #{field} is nil" do
+    let(field) { nil }
+    it { is_expected.not_to be_valid }
+  end
+end
+
+RSpec.describe User do
+  in_context :validates_presence, :email
+  in_context :validates_presence, :name
+end
+```
+
+In short: `in_context` makes reusable test blocks behave more like methods.
+
+## Table of Contents
+
+- [Why not just shared_examples?](#why-not-just-shared_examples)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Add this into RSpec](#add-this-into-rspec)
+  - [Define a new in_context](#define-a-new-in_context)
+  - [Use the context](#use-the-context)
+  - [Things to know](#things-to-know)
+- [Errors](#errors)
+- [Examples](#examples)
+- [Migrating to 1.2.0](#migrating-to-120)
+- [Development](#development)
+- [Contributing](#contributing)
 
 ## Installation
 
@@ -26,28 +83,28 @@ Or install it yourself as:
 
 ## Usage
 
-### Add this into Rspec
+### Add this into RSpec
 
 You must require the gem on top of your spec_helper:
 ```ruby
 require 'rspec_in_context'
 ```
 
-Then include it into Rspec:
+Then include it into RSpec:
 ```ruby
 RSpec.configure do |config|
   [...]
-  
+
   config.include RspecInContext
 end
 ```
 
 ### Define a new in_context
 
-You can define in_context block that are reusable almost anywhere.
-They completely look like normal Rspec.
+You can define in_context blocks that are reusable almost anywhere.
+They completely look like normal RSpec.
 
-##### Inside a Rspec block (scoped)
+##### Inside a RSpec block (scoped)
 
 ```ruby
 # A in_context can be named with a symbol or a string
@@ -60,19 +117,36 @@ end
 
 Those in_context will be scoped to their current `describe`/`context` block.
 
-##### Outside a Rspec block (globally)
+##### Outside a RSpec block (globally)
 
 Outside of a test you have to use `RSpec.define_context`. Those in_context will be defined globally in your tests.
 
+##### File organization
+
+For global contexts, we recommend creating a `spec/contexts/` directory with one file per context (or per group of related contexts):
+
+```
+spec/
+  contexts/
+    authenticated_request_context.rb
+    frozen_time_context.rb
+    interactor_contract_context.rb
+  spec_helper.rb
+```
+
+Then require them in your `spec_helper.rb`:
+
+```ruby
+Dir[File.join(__dir__, "contexts", "**", "*.rb")].each { |f| require f }
+```
 
 ### Use the context
 
 Anywhere in your test description, use a `in_context` block to use a predefined in_context.
 
-**Important**: in_context are scoped to their current `describe`/`context` block. If you need globally defined context see `RSpec.define_context`
+**Important**: in_context are scoped to their current `describe`/`context` block. If you need globally defined contexts see `RSpec.define_context`
 
 ```ruby
-# A in_context can be named with a symbol or a string
 RSpec.define_context :context_name do
   it 'works' do
     expect(true).to be_truthy
@@ -80,7 +154,7 @@ RSpec.define_context :context_name do
 end
 
 [...]
-Rspec.describe MyClass do
+RSpec.describe MyClass do
   in_context :context_name # => will execute the 'it works' test here
 end
 ```
@@ -89,94 +163,129 @@ end
 
 #### Inside block execution
 
-* You can chose exactly where your inside test will be used:
+* You can choose exactly where your inside test will be used:
 By using `execute_tests` in your define context, the test passed when you *use* the context will be executed here
 
 ```ruby
-define_context :context_name do
-  it 'works' do
-    expect(true).to be_truthy
-  end
-  context "in this context pomme exists" do
-    let(:pomme) { "abcd" }
-    
-    execute_tests
+RSpec.define_context :authenticated_request do
+  let(:user) { create(:user) }
+
+  before { sign_in user }
+
+  context "without authentication" do
+    before { sign_out user }
+
+    it "redirects to login" do
+      send(http_method, endpoint_path)
+      expect(response).to redirect_to(new_user_session_path)
+    end
   end
+
+  execute_tests
 end
 
 [...]
 
-in_context :context_name do
-  it 'will be executed at execute_tests place' do
-    expect(pomme).to eq("abcd") # => true
+RSpec.describe "Projects", type: :request do
+  let(:http_method) { :get }
+  let(:endpoint_path) { projects_path }
+
+  in_context :authenticated_request do
+    it "returns 200" do
+      get projects_path
+      expect(response).to have_http_status(:ok)
+    end
   end
 end
 ```
 
+The block you pass to `in_context` gets injected exactly where `execute_tests` is placed. Setup, teardown, and built-in tests live together in the context definition. Your specific tests are injected right where they belong.
+
 * You can add variable instantiation relative to your test where you exactly want:
 
-`instanciate_context` is an alias of `execute_tests` so you can't use both.
-But it let you describe what the block will do better.
+`instantiate_context` is an alias of `execute_tests` so you can't use both.
+But it lets you describe what the block will do better.
+
+> **Note**: The old spelling `instanciate_context` still works but is deprecated and will emit a warning.
 
 #### Variable usage
 
-* You can use variable in the in_context definition
+* You can use variables in the in_context definition
 
 ```ruby
-define_context :context_name do |name|
-  it 'works' do
-    expect(true).to be_truthy
-  end
-  context "in this context #{name} exists" do
-    let(name) { "abcd" }
-    
-    execute_tests
+RSpec.define_context :interactor_contract do |required_fields|
+  required_fields.each do |field|
+    context "when #{field} is missing" do
+      let(field) { nil }
+
+      it "fails" do
+        expect(subject).to be_a_failure
+      end
+
+      it "reports the breach" do
+        expect(subject.breaches).to include(field)
+      end
+    end
   end
 end
 
 [...]
 
-in_context :context_name, :poire do
-  it 'the right variable will exists' do
-    expect(poire).to eq("abcd") # => true
-  end
+RSpec.describe CreateInvoice do
+  subject { described_class.call(amount: amount, client: client) }
+
+  let(:amount) { 100 }
+  let(:client) { create(:client) }
+
+  in_context :interactor_contract, %i[amount client]
 end
 ```
 
 #### Scoping
 
-* In_contexts can be scope inside one another
+* In_contexts can be scoped inside one another
 
 ```ruby
-define_context :context_name do |name|
-  it 'works' do
-    expect(true).to be_truthy
-  end
-  context "in this context #{name} exists" do
-    let(name) { "abcd" }
-    
-    execute_tests
+RSpec.define_context :with_frozen_time do
+  before { freeze_time }
+  execute_tests
+end
+
+RSpec.define_context :with_inline_mailer do
+  around do |example|
+    ActiveJob::Base.queue_adapter = :inline
+    ActionMailer::Base.deliveries.clear
+    example.run
+    ActionMailer::Base.deliveries.clear
+    ActiveJob::Base.queue_adapter = :test
   end
+  execute_tests
 end
 
-define_context "second in_context" do
-  context 'and tree also' do
-    let(:tree) { 'abcd' }
+[...]
 
-    it 'will scope correctly' do
-      expect(tree).to eq(poire)
+RSpec.describe PasswordReset do
+  in_context :with_frozen_time do
+    in_context :with_inline_mailer do
+      it "sends the reset email with correct timestamp" do
+        PasswordReset.call(user)
+        expect(ActionMailer::Base.deliveries.last.body)
+          .to include(Time.current.to_s)
+      end
     end
   end
 end
+```
 
-[...]
+* You can also use `in_context` inside a `define_context` to compose contexts together:
 
-in_context :context_name, :poire do
-  it 'the right variable will exists' do
-    expect(poire).to eq("abcd") # => true
-  end
+```ruby
+RSpec.define_context :statistics_processor do
+  in_context :interactor_contract, %i[account date]
 
-  in_context "second in_context" # => will work
+  it "succeeds" do
+    expect(subject).to be_success
+  end
 end
 ```
 
@@ -187,29 +296,29 @@ end
 * You can add a namespace to a in_context definition
 
 ```ruby
-define_context "this is a namespaced context", namespace: "namespace name"
+define_context "with valid params", namespace: "users"
 ```
 Or
 ```ruby
-define_context "this is a namespaced context", ns: "namespace name"
+define_context "with valid params", ns: "users"
 ```
 Or
 ```ruby
-RSpec.define_context "this is a namespaced context", ns: "namespace name"
+RSpec.define_context "with valid params", ns: "users"
 ```
 
-* When you want to use a namespaced in_context, you have two choice:
+* When you want to use a namespaced in_context, you have two choices:
 
-Ignore any namespace and it will try to find a corresponding in_context in any_namespace (the ones defined without namespace have the priority);
+Ignore any namespace and it will try to find a corresponding in_context in any namespace (the ones defined without namespace have the priority). **Note**: if the same context name exists in multiple namespaces, an `AmbiguousContextName` error will be raised — you must specify the namespace explicitly.
 ```ruby
 define_context "namespaced context", ns: "namespace name" do
   [...]
 end
 
-in_context "namespaced context"
+in_context "namespaced context" # Works if only one namespace has this name
 ```
 
-Pass a namespace and it will look only in this context.
+Pass a namespace and it will look only in this namespace.
 ```ruby
 define_context "namespaced context", ns: "namespace name" do
   [...]
@@ -219,12 +328,12 @@ in_context "namespaced context", namespace: "namespace name"
 in_context "namespaced context", ns: "namespace name"
 ```
 
-#### Making `in_context` adverstise itself
+#### Making `in_context` advertise itself
 
 The fact that a `in_context` block is used inside the test is silent and invisible by default.
-`in_context` will still wrap its own execution inside a anonymous context.
+`in_context` will still wrap its own execution inside an anonymous context.
 
-But, there's some case where it helps to make the `in_context` to wrap its execution in a named `context` block.
+But, there's some cases where it helps to make the `in_context` wrap its execution in a named `context` block.
 For example:
 ```ruby
 define_context "with my_var defined" do
@@ -247,7 +356,7 @@ end
 Using a `rspec -f doc` will only print "MyNiceClass works" and "MyNiceClass doesn't work" which is not really a good documentation.
 
 So, you can define a context specifying it not to be `silent` or to `print_context`.
-For example :
+For example:
 ```ruby
 define_context "with my_var defined", silent: false do
   before do
@@ -268,12 +377,67 @@ end
 ```
 Will print "MyNiceClass with my_var defined works" and "MyNiceClass without my_var defined doesn't work". Which is valid and readable documentation.
 
-## Development
+#### Thread-safety & parallel_tests
+
+The context registry is protected by a Mutex so it's safe to use with `parallel_tests` in thread mode.
+
+#### Memory cleanup
 
+For long-running test suites with many dynamically generated contexts, you can free all stored contexts:
+
+```ruby
+RspecInContext::InContext.clear_all_contexts!
+```
+
+### Errors
+
+| Error | Cause |
+|---|---|
+| `NoContextFound` | `in_context` refers to a name that doesn't exist or is out of scope |
+| `AmbiguousContextName` | Same name exists in multiple namespaces, no namespace specified |
+| `InvalidContextName` | `define_context` called with `nil` or empty name |
+| `MissingDefinitionBlock` | `define_context` called without a block |
+
+## Examples
+
+The [`examples/`](examples/) directory contains real-world usage patterns:
+
+- **`contexts/`** — Context definitions you'd put in `spec/contexts/` (authentication, interactor contracts, frozen time, job setup, mailer, composed contexts)
+- **`usage/`** — Spec files showing how to use those contexts in practice
+
+See [`examples/README.md`](examples/README.md) for the full list.
+
+## Migrating to 1.2.0
+
+### Breaking changes
+
+- **Ruby >= 3.2 required.** Older Rubies are no longer supported.
+- **`AmbiguousContextName` error.** If the same context name exists in multiple namespaces and you call `in_context` without specifying a namespace, `AmbiguousContextName` is now raised instead of silently picking one. Fix: add `ns:` to disambiguate.
+- **`ActiveSupport` removed.** The gem no longer depends on `activesupport`. This should be transparent, but if you were relying on `HashWithIndifferentAccess` behavior from the gem's internals, note that contexts are now stored in a plain `Hash` with string-normalized keys (symbols and strings still work interchangeably).
+
+### Deprecations
+
+- **`instanciate_context`** is deprecated (typo). Use `instantiate_context` or `execute_tests` instead. The old method still works but emits a warning to `$stderr`.
+
+### New features
+
+- **Input validation**: `define_context` now raises `InvalidContextName` (nil/empty name) and `MissingDefinitionBlock` (no block).
+- **`clear_all_contexts!`**: Call `RspecInContext::InContext.clear_all_contexts!` to free all stored contexts for memory cleanup in long-running suites.
+- **Thread-safety**: The context registry is now protected by a Mutex for `parallel_tests` in thread mode.
+
+## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-After setuping the repo, you should run `overcommit --install` to install the different hooks.
+After setting up the repo, you should run `overcommit --install` to install the different hooks.
+
+Every commit/push is checked by overcommit.
+
+Tool used in dev:
+
+- RSpec
+- Rubocop
+- Prettier
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/TODO.md

@@ -0,0 +1,44 @@
+# TODO
+
+Issues identified during review of the codebase and PR #21.
+
+## PR #21 — Resolved
+
+- [x] Stack leak if `find_context` raises — moved `find_context` before `push`
+- [x] Indentation of `spec.metadata` in gemspec — fixed by prettier
+- [ ] `.ruby-version` 4.0.1 vs CI matrix — `head` covers it, revisit if contributor confusion arises
+
+## P0 — Before merge
+
+- [x] Quote prettier globs in CI — quoted `'lib/**/*.rb'` etc. in both workflow files
+- [x] Gitignore `.rubocop-remote-*.yml` — added pattern to `.gitignore`
+
+## P1 — Réduction des dépendances
+
+- [x] Retirer `active_support/all` — remplacé `HashWithIndifferentAccess` par `Hash` avec `.to_s` sur les clés, retiré `present?`. Temps de boot des tests : 0.27s → 0.08s
+- [x] Retirer `faker` — retiré de `spec_helper.rb` et `rspec_in_context.gemspec`
+
+## P1 — Robustesse face aux internals RSpec
+
+- [x] Smoke test pour `hooks.instance_variable_get(:@owner)` — vérifie que `@owner` est non-nil et est une Class
+- [x] Smoke test pour le prepend de `ContextManagement` sur `ExampleGroup.subclass`
+- [x] Resserrer les contraintes de version — `rspec "~> 3.0"`, `rake "~> 13.0"`, `activesupport` retiré
+
+## P2 — Qualité de l'API
+
+- [x] Ajouter `RspecInContext::Error` comme classe de base — `NoContextFound` et `AmbiguousContextName` en héritent
+- [x] Retirer le `instance_exec` inutile dans `define_context`
+- [x] Corriger les typos dans les commentaires (`find` → `found`, `overriden` → `overridden`, `colisions` → `collisions`)
+- [x] Corriger `instanciate_context` — ajouté `instantiate_context` comme alias principal, l'ancien émet un deprecation warning
+
+## P2 — Tests
+
+- [x] Renforcer les tests — block delivery guard dynamique (voir `spec/support/block_delivery_guard.rb`) détecte les blocs non-consommés et les groupes vides. Les `expect(true).to be_truthy` restants sont acceptables car le guard couvre la disparition silencieuse.
+- [x] Sémantique de `test_inexisting_context` — vérifiée et documentée. Appelle `find_context` au runtime, qui est la première opération de `in_context`. Le comportement est identique.
+
+## P3 — Nice to have
+
+- [x] Ajouter `clear_all_contexts!` pour le nettoyage mémoire — `RspecInContext::InContext.clear_all_contexts!` réinitialise le registre. Test ajouté avec sauvegarde/restauration du state.
+- [x] Ajouter un Mutex autour de `@contexts` — `@contexts_mutex` protège l'initialisation et le clear. Thread-safe pour `parallel_tests` en mode thread.
+- [x] Corriger les typos restantes dans les commentaires — fait avec les fixes P2
+- [x] Section migration dans le README — section "Migrating to 1.2.0" ajoutée avec breaking changes, deprecations, et nouvelles features. Mise à jour de la mention `instanciate_context` → `instantiate_context`.

data/examples/README.md

@@ -0,0 +1,23 @@
+# Examples
+
+Real-world usage examples for `rspec_in_context`.
+
+## contexts/
+
+Context definitions you'd put in `spec/contexts/` in a real project:
+
+- **authenticated_request_context.rb** — Authentication setup with built-in unauthenticated test + `execute_tests` for your authenticated tests
+- **interactor_contract_context.rb** — Parameterized contract validation for interactor-style service objects
+- **frozen_time_context.rb** — Simple setup context using `freeze_time`
+- **active_job_context.rb** — `around` hook to run jobs in test mode
+- **inline_mailer_context.rb** — Delivers emails synchronously during tests
+- **composed_context.rb** — Composing contexts: uses `in_context` inside `define_context`
+
+## usage/
+
+Spec files showing how to use the contexts above:
+
+- **request_spec.rb** — Using `:authenticated_request` in a request spec
+- **interactor_spec.rb** — Using `:interactor_expect` for contract validation
+- **nested_contexts_spec.rb** — Nesting `:with_frozen_time` and `:with_inline_mailer`
+- **composed_context_spec.rb** — Using `:service_processor` (which itself uses `:interactor_expect`)

data/examples/contexts/active_job_context.rb

@@ -0,0 +1,15 @@
+# Sets up ActiveJob in test mode for the duration of the tests.
+# Useful when you need to assert on enqueued/performed jobs.
+
+RSpec.define_context :with_test_jobs do
+  include ActiveJob::TestHelper
+
+  around do |example|
+    original_adapter = ActiveJob::Base.queue_adapter
+    ActiveJob::Base.queue_adapter = :test
+    example.run
+    ActiveJob::Base.queue_adapter = original_adapter
+  end
+
+  execute_tests
+end

data/examples/contexts/authenticated_request_context.rb

@@ -0,0 +1,27 @@
+# A context that sets up authentication, tests the unauthenticated case,
+# then lets you inject your authenticated tests via execute_tests.
+#
+# Expects the caller to define:
+#   - http_method (e.g. :get, :post)
+#   - endpoint_path (e.g. users_path)
+
+RSpec.define_context :authenticated_request do
+  let(:user) { create(:user) }
+  let(:account) { user.accounts.first }
+
+  before { sign_in user }
+
+  describe "authentication" do
+    context "without authentication" do
+      before { sign_out user }
+
+      it "redirects to login" do
+        send(http_method, endpoint_path)
+
+        expect(response).to redirect_to(new_user_session_path)
+      end
+    end
+  end
+
+  execute_tests
+end

data/examples/contexts/composed_context.rb

@@ -0,0 +1,13 @@
+# Example of composing contexts together.
+# This context reuses :interactor_expect and adds a success test.
+#
+# Shows how in_context can be used inside define_context
+# to build higher-level reusable blocks.
+
+RSpec.define_context :service_processor do
+  in_context :interactor_expect, %i[account date]
+
+  it "succeeds with valid params" do
+    expect(subject).to be_success
+  end
+end

data/examples/contexts/frozen_time_context.rb

@@ -0,0 +1,8 @@
+# Freezes time for the duration of the tests.
+# Uses ActiveSupport's freeze_time.
+
+RSpec.define_context :with_frozen_time do
+  before { freeze_time }
+
+  execute_tests
+end

data/examples/contexts/inline_mailer_context.rb

@@ -0,0 +1,15 @@
+# Delivers emails inline (synchronously) during tests.
+# Clears the deliveries before and after each test.
+
+RSpec.define_context :with_inline_mailer do
+  around do |example|
+    original_adapter = ActiveJob::Base.queue_adapter
+    ActiveJob::Base.queue_adapter = :inline
+    ActionMailer::Base.deliveries.clear
+    example.run
+    ActionMailer::Base.deliveries.clear
+    ActiveJob::Base.queue_adapter = original_adapter
+  end
+
+  execute_tests
+end

data/examples/contexts/interactor_contract_context.rb

@@ -0,0 +1,23 @@
+# Validates that an interactor fails when required fields are missing.
+# Pass the list of required fields as an argument.
+#
+# Expects the caller to define a subject that returns an interactor result,
+# and a let for each required field.
+
+RSpec.define_context :interactor_expect do |required_fields|
+  required_fields.each do |field|
+    context "when the field #{field} is not present" do
+      let(field) { nil }
+
+      it "fails" do
+        context = subject
+        expect(context).to be_a_failure
+      end
+
+      it "populates the breaches" do
+        context = subject
+        expect(context.breaches).to include(field)
+      end
+    end
+  end
+end

data/examples/usage/composed_context_spec.rb

@@ -0,0 +1,15 @@
+# Example: Using a composed context
+#
+# :service_processor reuses :interactor_expect internally,
+# so you get contract validation + success test in one call.
+
+require "rails_helper"
+
+RSpec.describe DailyStatsProcessor do
+  subject { described_class.call(account: account, date: date) }
+
+  let(:account) { create(:account) }
+  let(:date) { Date.current }
+
+  in_context :service_processor
+end