rspec_in_context 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 730a3e4b4ffb390f1331ac01a19295c91c8c7d21b356e23618bc10d619645f2a
-  data.tar.gz: 74b2c2d9f4f4921a7611d678dfc7202226bd123a670148564b6302d6f951a772
+  metadata.gz: e63cf4bd9f911ee7f0434682e2b104578555086eba35590ff0c8d72214ef2f48
+  data.tar.gz: d4737b49923e3a8080603987f4c490d19ed798f824ce0822dd0e349028683c79
 SHA512:
-  metadata.gz: 21923024896432dbcd2e4234306df21ccb3e3ef8eddb3325c576322e5d54a8e54ad4169c2b94b9b3cb8b43ab78531a20f5dd61e9fa7653b6e54832eb05a84948
-  data.tar.gz: 44badaca77e3c8994c0fc9faea35c8877d1d50c73bdee4a3caaeebd6497c336545c8e6ac3743c8b639fa4e6b1c1193a523ea5dd3beb4996e72eda6fccdbd9b3b
+  metadata.gz: 589321b198f19691378d28b67aa92beb237ba1bf6ceca7f78fc6fee08ad983cf94467ce4b288007ae98e825ab57aaa441c872ee3a0234d674b88e7e733d2a762
+  data.tar.gz: fac8b3dd1d6bb726f51fdd3377fcdf10092129d0e005bbd3133ff7169bd6dcf4a22fdedb97dc77602890b489014e2105e76b82c0a8480316d00250802a4b026f

data/.rubocop.yml

@@ -42,6 +42,10 @@ Style/GuardClause:
 Style/OneClassPerFile:
   Enabled: false
 
+# Ruby >= 3.2 required, frozen string literal comment is unnecessary noise
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
 ### End Prettier
 Naming/MethodParameterName:
   Enabled: false

data/CHANGELOG.md

@@ -6,6 +6,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-03-05
+### Added
+- `LLMS.md` — comprehensive API reference for LLMs
+- `examples/` directory with real-world usage patterns (contexts and specs)
+
+### Changed
+- Complete rewrite of `README.md` with better structure, real-world examples, and comparison with `shared_examples`
+
 ## [1.2.0] - 2026-01-27
 ### Breaking
 - **BREAKING** Minimum Ruby version is now 3.2
@@ -53,7 +61,8 @@ This is a release in order to test all type of actions
 - Changelog
 - Support ruby 3.0
 
-[Unreleased]: https://github.com/zaratan/rspec_in_context/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/zaratan/rspec_in_context/compare/v1.2.1...HEAD
+[1.2.1]: https://github.com/zaratan/rspec_in_context/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/zaratan/rspec_in_context/compare/v1.1.0.3...v1.2.0
 [1.1.0.3]: https://github.com/zaratan/rspec_in_context/compare/v1.1.0.2...v1.1.0.3
 [1.1.0.2]: https://github.com/zaratan/rspec_in_context/compare/v1.1.0.1...v1.1.0.2

data/LLMS.md

@@ -0,0 +1,388 @@
+# rspec_in_context — LLM Reference
+
+## What is this gem?
+
+`rspec_in_context` is a Ruby gem that provides `define_context` / `in_context` as a replacement for RSpec's `shared_examples` / `it_behaves_like`. The key advantage: contexts can accept blocks that get injected at a specific point via `execute_tests`, making them composable like methods. Contexts can also accept arguments, be namespaced, and nest within each other.
+
+## Setup
+
+**Gemfile:**
+```ruby
+gem 'rspec_in_context'
+```
+
+**spec_helper.rb (or rails_helper.rb):**
+```ruby
+require 'rspec_in_context'
+
+RSpec.configure do |config|
+  config.include RspecInContext
+end
+```
+
+Requires Ruby >= 3.2.
+
+## API Reference
+
+### `RSpec.define_context(name, namespace: nil, ns: nil, silent: true, print_context: nil, &block)`
+
+Define a global context (available in all spec files). Use outside any `describe`/`context` block.
+
+```ruby
+RSpec.define_context :with_frozen_time do
+  before { freeze_time }
+  execute_tests
+end
+```
+
+### `define_context(name, namespace: nil, ns: nil, silent: true, print_context: nil, &block)`
+
+Define a scoped context (available only within the enclosing `describe`/`context` block). Use inside a spec.
+
+```ruby
+RSpec.describe MyService do
+  define_context :with_valid_params do
+    let(:params) { { name: "test" } }
+    execute_tests
+  end
+
+  in_context :with_valid_params do
+    it "works" do
+      expect(MyService.call(params)).to be_success
+    end
+  end
+end
+```
+
+**Parameters:**
+- `name` (String, Symbol) — required. The context identifier.
+- `namespace:` / `ns:` (String, Symbol) — optional namespace to avoid name collisions.
+- `silent:` (Boolean, default: `true`) — when `true`, wraps in anonymous context. When `false`, wraps in a named context visible in `--format doc`.
+- `print_context:` (Boolean) — inverse of `silent`. `print_context: true` is equivalent to `silent: false`.
+- `&block` — required. The context body.
+
+### `in_context(name, *args, namespace: nil, ns: nil, &block)`
+
+Use a previously defined context. The optional block is injected where `execute_tests` appears in the context definition.
+
+```ruby
+in_context :with_frozen_time do
+  it "uses frozen time" do
+    expect(Time.current).to eq(Time.current) # always true
+  end
+end
+
+# With arguments (no block)
+in_context :validates_field, :email
+```
+
+**Parameters:**
+- `name` (String, Symbol) — the context to use.
+- `*args` — positional arguments passed to the context block.
+- `namespace:` / `ns:` — namespace to look in.
+- `&block` — optional. Injected at `execute_tests`.
+
+### `execute_tests` / `instantiate_context`
+
+Placeholder inside a `define_context` block. Marks where the caller's block (from `in_context`) will be injected.
+
+```ruby
+RSpec.define_context :setup_env do
+  let(:user) { create(:user) }
+  before { sign_in user }
+
+  execute_tests  # <-- caller's block runs here
+end
+```
+
+These are aliases. `instanciate_context` also works but is deprecated (typo).
+
+## Key Concepts
+
+### Scoped vs Global contexts
+
+- **Scoped**: `define_context` inside a `describe`/`context` — automatically removed when the block ends.
+- **Global**: `RSpec.define_context` outside any describe — available everywhere, never cleaned up.
+
+### Block injection (execute_tests)
+
+The core feature. When you call `in_context :foo do ... end`, the block is stored and injected where `execute_tests` appears in the `:foo` definition. If `execute_tests` is absent and you pass a block, the block is silently ignored.
+
+### Arguments
+
+Context blocks can accept arguments via block parameters:
+
+```ruby
+RSpec.define_context :validates_field do |field_name|
+  context "when #{field_name} is nil" do
+    let(field_name) { nil }
+    it { is_expected.not_to be_valid }
+  end
+end
+
+in_context :validates_field, :email
+```
+
+### Namespacing
+
+Prevents name collisions when different parts of your test suite define contexts with the same name:
+
+```ruby
+RSpec.define_context :valid_params, ns: :users do ... end
+RSpec.define_context :valid_params, ns: :posts do ... end
+
+in_context :valid_params, ns: :users do ... end
+```
+
+If the same name exists in multiple namespaces and you don't specify `ns:`, `AmbiguousContextName` is raised.
+
+### Silent mode
+
+- `silent: true` (default): `in_context` wraps in an anonymous `context {}` block — invisible in `--format doc`.
+- `silent: false` or `print_context: true`: wraps in `context("context_name") {}` — visible in `--format doc`.
+
+### Thread-local block stack for nesting
+
+Nested `in_context` calls work correctly. The gem uses `Thread.current[:test_block_stack]` (a stack) to track which block should be injected at each nesting level.
+
+## Common Patterns
+
+### Pattern: Setup context (before/let + execute_tests)
+
+The most common pattern. Set up state, then let the caller provide assertions.
+
+```ruby
+RSpec.define_context :as_admin do
+  let(:current_user) { create(:user, role: :admin) }
+  before { sign_in current_user }
+  execute_tests
+end
+
+in_context :as_admin do
+  it "can access admin panel" do
+    get admin_path
+    expect(response).to have_http_status(:ok)
+  end
+end
+```
+
+### Pattern: Parameterized context (arguments)
+
+Pass data to customize the context behavior.
+
+```ruby
+RSpec.define_context :contract_validation do |required_fields|
+  required_fields.each do |field|
+    context "when #{field} is missing" do
+      let(field) { nil }
+      it("fails") { expect(subject).to be_a_failure }
+    end
+  end
+end
+
+in_context :contract_validation, %i[name email phone]
+```
+
+### Pattern: Built-in tests + execute_tests
+
+Include both built-in tests and a placeholder for injected tests.
+
+```ruby
+RSpec.define_context :authenticated_request do
+  let(:user) { create(:user) }
+  before { sign_in user }
+
+  context "without authentication" do
+    before { sign_out user }
+    it("returns 401") { expect(response).to have_http_status(:unauthorized) }
+  end
+
+  execute_tests  # caller's authenticated tests go here
+end
+```
+
+### Pattern: Inline define + use
+
+For contexts only needed in one spec file.
+
+```ruby
+RSpec.describe ReportGenerator do
+  define_context :with_sample_data do
+    let!(:records) { create_list(:record, 5) }
+    execute_tests
+  end
+
+  in_context :with_sample_data do
+    it "generates the report" do
+      expect(ReportGenerator.call.rows.count).to eq(5)
+    end
+  end
+end
+```
+
+### Pattern: Nested in_context in define_context
+
+Compose higher-level contexts from smaller ones.
+
+```ruby
+RSpec.define_context :full_integration do
+  in_context :with_frozen_time do
+    in_context :as_admin do
+      execute_tests
+    end
+  end
+end
+```
+
+### Pattern: File organization (spec/contexts/*.rb)
+
+```
+spec/
+  contexts/
+    authenticated_request_context.rb
+    frozen_time_context.rb
+    contract_validation_context.rb
+  spec_helper.rb  # requires all contexts
+```
+
+```ruby
+# spec_helper.rb
+Dir[File.join(__dir__, "contexts", "**", "*.rb")].each { |f| require f }
+```
+
+## Error Reference
+
+### `RspecInContext::NoContextFound`
+
+**Cause:** `in_context` references a name that doesn't exist or is out of scope.
+
+**Fix:** Check spelling, ensure the context is defined globally or in an enclosing scope.
+
+### `RspecInContext::AmbiguousContextName`
+
+**Cause:** The same context name exists in multiple namespaces and no namespace was specified.
+
+**Fix:** Add `ns: :your_namespace` to `in_context`.
+
+### `RspecInContext::InvalidContextName`
+
+**Cause:** `define_context` called with `nil` or `""`.
+
+**Fix:** Provide a valid string or symbol name.
+
+### `RspecInContext::MissingDefinitionBlock`
+
+**Cause:** `define_context` called without a block.
+
+**Fix:** Add a block: `define_context(:name) { ... }`.
+
+## Anti-patterns / Gotchas
+
+### Forgetting execute_tests when passing a block
+
+```ruby
+# BAD — the block passed to in_context is silently ignored
+RSpec.define_context :setup do
+  let(:user) { create(:user) }
+  # missing execute_tests!
+end
+
+in_context :setup do
+  it "never runs" do  # <-- this test is lost
+    expect(user).to be_present
+  end
+end
+
+# GOOD
+RSpec.define_context :setup do
+  let(:user) { create(:user) }
+  execute_tests
+end
+```
+
+### Ambiguous context names without namespace
+
+```ruby
+# BAD — raises AmbiguousContextName
+RSpec.define_context :valid_params, ns: :users do ... end
+RSpec.define_context :valid_params, ns: :posts do ... end
+in_context :valid_params do ... end  # which one?
+
+# GOOD
+in_context :valid_params, ns: :users do ... end
+```
+
+### Using deprecated instanciate_context
+
+```ruby
+# DEPRECATED — emits warning
+instanciate_context
+
+# GOOD
+execute_tests
+# or
+instantiate_context
+```
+
+## Real-World Examples
+
+The `examples/` directory in the repository contains real-world usage patterns:
+
+- `examples/contexts/` — Context definitions (authentication, interactor contracts, frozen time, job setup, mailer, composed contexts)
+- `examples/usage/` — Spec files showing how to use those contexts in practice
+
+See `examples/README.md` for the full list.
+
+## Complete Example
+
+Showing multiple features together:
+
+```ruby
+# spec/contexts/api_context.rb
+RSpec.define_context :authenticated_api, silent: false do
+  let(:user) { create(:user) }
+  let(:headers) { { "Authorization" => "Bearer #{user.token}" } }
+
+  context "without authentication" do
+    let(:headers) { {} }
+
+    it "returns 401" do
+      send(http_method, endpoint, headers: headers)
+      expect(response).to have_http_status(:unauthorized)
+    end
+  end
+
+  execute_tests
+end
+
+RSpec.define_context :validates_contract do |required_fields|
+  required_fields.each do |field|
+    context "when #{field} is missing" do
+      let(field) { nil }
+      it("returns 422") { expect(response).to have_http_status(:unprocessable_entity) }
+    end
+  end
+end
+
+# spec/requests/api/projects_spec.rb
+RSpec.describe "API Projects", type: :request do
+  let(:http_method) { :post }
+  let(:endpoint) { api_projects_path }
+
+  in_context :authenticated_api do
+    let(:name) { "My Project" }
+    let(:description) { "A great project" }
+
+    before do
+      post endpoint, params: { name: name, description: description }, headers: headers
+    end
+
+    in_context :validates_contract, %i[name]
+
+    it "creates the project" do
+      expect(response).to have_http_status(:created)
+      expect(json_response["name"]).to eq("My Project")
+    end
+  end
+end
+```

data/README.md

@@ -3,9 +3,67 @@
 [![Gem Version](https://badge.fury.io/rb/rspec_in_context.svg)](https://badge.fury.io/rb/rspec_in_context)
 ![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
 
@@ -25,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
@@ -59,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
@@ -79,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
 ```
@@ -88,30 +163,44 @@ 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:
 
 `instantiate_context` is an alias of `execute_tests` so you can't use both.
@@ -121,63 +210,82 @@ But it lets you describe what the block will do better.
 
 #### 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
 ```
 
@@ -188,15 +296,15 @@ 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 choices:
@@ -220,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
@@ -248,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
@@ -269,6 +377,36 @@ end
 ```
 Will print "MyNiceClass with my_var defined works" and "MyNiceClass without my_var defined doesn't work". Which is valid and readable documentation.
 
+#### 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
@@ -289,10 +427,17 @@ Will print "MyNiceClass with my_var defined works" and "MyNiceClass without my_v
 
 ## 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/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

data/examples/usage/interactor_spec.rb

@@ -0,0 +1,23 @@
+# Example: Using :interactor_expect for contract validation
+#
+# Tests that the interactor fails when any required field is nil,
+# then tests the happy path separately.
+
+require "rails_helper"
+
+RSpec.describe CreateInvoice do
+  subject do
+    described_class.call(amount: amount, client: client, due_date: due_date)
+  end
+
+  let(:amount) { 100 }
+  let(:client) { create(:client) }
+  let(:due_date) { Date.tomorrow }
+
+  in_context :interactor_expect, %i[amount client due_date]
+
+  it "creates the invoice" do
+    expect(subject).to be_success
+    expect(subject.invoice).to be_persisted
+  end
+end

data/examples/usage/nested_contexts_spec.rb

@@ -0,0 +1,30 @@
+# Example: Nesting multiple contexts together
+#
+# Combines :with_frozen_time and :with_inline_mailer
+# to test time-sensitive email delivery.
+
+require "rails_helper"
+
+RSpec.describe PasswordReset do
+  in_context :with_frozen_time do
+    in_context :with_inline_mailer do
+      it "sends the reset email" do
+        user = create(:user)
+
+        PasswordReset.call(user)
+
+        expect(ActionMailer::Base.deliveries.size).to eq(1)
+      end
+
+      it "includes the current timestamp" do
+        user = create(:user)
+
+        PasswordReset.call(user)
+
+        expect(ActionMailer::Base.deliveries.last.body.to_s).to include(
+          Time.current.iso8601,
+        )
+      end
+    end
+  end
+end

data/examples/usage/request_spec.rb

@@ -0,0 +1,29 @@
+# Example: Using :authenticated_request in a request spec
+#
+# The context handles authentication setup and tests the unauthenticated case.
+# Your tests inside the block run in an authenticated state.
+
+require "rails_helper"
+
+RSpec.describe "Projects", type: :request do
+  let(:http_method) { :get }
+  let(:endpoint_path) { projects_path }
+
+  in_context :authenticated_request do
+    describe "GET /projects" do
+      it "returns 200" do
+        get projects_path
+
+        expect(response).to have_http_status(:ok)
+      end
+
+      it "lists the user's projects" do
+        project = create(:project, account: account)
+
+        get projects_path
+
+        expect(response.body).to include(project.name)
+      end
+    end
+  end
+end

data/lib/rspec_in_context/context_management.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module RspecInContext
   # Allow context to be scoped inside a block
   module ContextManagement

data/lib/rspec_in_context/in_context.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 # Base module
 module RspecInContext
   # Base error class for all gem errors

data/lib/rspec_in_context/version.rb

@@ -1,6 +1,4 @@
-# frozen_string_literal: true
-
 module RspecInContext
   # Version of the gem
-  VERSION = "1.2.0"
+  VERSION = "1.2.1".freeze
 end

data/lib/rspec_in_context.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "rspec_in_context/version"
 require "rspec_in_context/in_context"
 require "rspec_in_context/context_management"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec_in_context
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Denis <Zaratan> Pasin
@@ -213,11 +213,23 @@ files:
 - CHANGELOG.md
 - Gemfile
 - Guardfile
+- LLMS.md
 - README.md
 - Rakefile
 - TODO.md
 - bin/console
 - bin/setup
+- examples/README.md
+- examples/contexts/active_job_context.rb
+- examples/contexts/authenticated_request_context.rb
+- examples/contexts/composed_context.rb
+- examples/contexts/frozen_time_context.rb
+- examples/contexts/inline_mailer_context.rb
+- examples/contexts/interactor_contract_context.rb
+- examples/usage/composed_context_spec.rb
+- examples/usage/interactor_spec.rb
+- examples/usage/nested_contexts_spec.rb
+- examples/usage/request_spec.rb
 - lib/rspec_in_context.rb
 - lib/rspec_in_context/context_management.rb
 - lib/rspec_in_context/in_context.rb