rubyn-code 0.1.0

data/skills/rspec/build_stubbed.md

@@ -0,0 +1,199 @@
+# RSpec: build_stubbed vs build vs create
+
+## Pattern
+
+Choose the cheapest factory strategy that satisfies the test. Default to `build_stubbed`, fall back to `build`, use `create` only when the test genuinely needs a persisted database record.
+
+```ruby
+RSpec.describe Order do
+  # FASTEST: No database, no save, generates a fake id
+  # Use for: testing methods that don't touch the DB
+  let(:order) { build_stubbed(:order, total: 100.00) }
+
+  describe "#discounted_total" do
+    it "applies 10% discount" do
+      expect(order.discounted_total).to eq(90.00)
+    end
+  end
+
+  describe "#high_value?" do
+    let(:cheap_order) { build_stubbed(:order, total: 50) }
+    let(:expensive_order) { build_stubbed(:order, total: 500) }
+
+    it "returns true for orders over 200" do
+      expect(expensive_order.high_value?).to be true
+      expect(cheap_order.high_value?).to be false
+    end
+  end
+end
+```
+
+```ruby
+RSpec.describe Order do
+  # MEDIUM: In-memory object, not saved. Has valid attributes.
+  # Use for: testing validations, or when you need to call .save yourself
+  let(:order) { build(:order) }
+
+  describe "validations" do
+    it "requires a shipping address" do
+      order.shipping_address = nil
+      expect(order).not_to be_valid
+      expect(order.errors[:shipping_address]).to include("can't be blank")
+    end
+
+    it "is valid with all required attributes" do
+      expect(order).to be_valid
+    end
+  end
+end
+```
+
+```ruby
+RSpec.describe Order do
+  # SLOWEST: Writes to database. Generates real id, timestamps, etc.
+  # Use for: testing scopes, queries, uniqueness, DB constraints, and associations that query
+  let(:user) { create(:user) }
+
+  describe ".recent" do
+    let!(:new_order) { create(:order, user: user, created_at: 1.day.ago) }
+    let!(:old_order) { create(:order, user: user, created_at: 1.year.ago) }
+
+    it "returns orders from the last 30 days" do
+      expect(user.orders.recent).to eq([new_order])
+    end
+  end
+
+  describe ".total_revenue" do
+    before do
+      create(:order, user: user, total: 100)
+      create(:order, user: user, total: 250)
+    end
+
+    it "sums all order totals" do
+      expect(user.orders.total_revenue).to eq(350)
+    end
+  end
+end
+```
+
+The decision tree:
+
+```
+Does the test need the record in the database?
+├── YES (scopes, queries, uniqueness, associations that query) → create
+└── NO
+    ├── Does the test call .save, .valid?, or .errors? → build
+    └── NO (testing return values, calculations, formatting) → build_stubbed
+```
+
+## Why This Is Good
+
+- **Speed.** `build_stubbed` is 10-50x faster than `create`. It skips database writes, transactions, callbacks, and index updates. In a 2,000-spec suite, choosing the right strategy can save 5-10 minutes of run time.
+- **Isolation.** `build_stubbed` tests logic in complete isolation from the database. If the test passes, the method works regardless of database state.
+- **Clearer intent.** When a test uses `create`, it signals "this test depends on the database." When it uses `build_stubbed`, it signals "this test is about pure logic." Readers immediately understand the scope.
+- **Less factory overhead.** `build_stubbed` doesn't trigger `after_create` callbacks or cascade through association chains. A stubbed order doesn't create a real user, real line items, and real products.
+
+## Anti-Pattern
+
+Using `create` for everything because "it's easier" or "just in case":
+
+```ruby
+RSpec.describe Order do
+  # SLOW: Every test creates 3+ database records
+  let(:user) { create(:user) }
+  let(:product) { create(:product) }
+  let(:order) { create(:order, user: user) }
+  let(:line_item) { create(:line_item, order: order, product: product) }
+
+  describe "#high_value?" do
+    it "returns true over 200" do
+      # This test only checks a comparison: total > 200
+      # It does NOT need any database records
+      order.total = 500
+      expect(order.high_value?).to be true
+    end
+  end
+
+  describe "#formatted_total" do
+    it "formats as currency" do
+      # This test only checks string formatting
+      # 4 database records created for zero reason
+      expect(order.formatted_total).to eq("$100.00")
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **4 INSERT statements for a string formatting test.** The `formatted_total` test checks `sprintf` behavior. It needs zero database interaction, yet it creates a user, product, order, and line item.
+- **Factory chain cascades.** `create(:order)` triggers `create(:user)` via the association. `create(:line_item)` triggers `create(:product)` and `create(:order)`. One `create` can cascade into 5+ INSERTs.
+- **Slower test suite.** Across hundreds of tests, unnecessary `create` calls add up to minutes. A test suite that should run in 30 seconds takes 3 minutes.
+- **Fragile.** Database-backed tests can fail for reasons unrelated to the behavior being tested — unique constraint violations from other test data, unexpected callbacks, or association validation errors.
+
+## When To Apply
+
+**Use `build_stubbed` when:**
+- Testing instance methods that compute, format, or return values (`#total`, `#display_name`, `#high_value?`)
+- Testing methods that check object state without querying (`#pending?`, `#can_cancel?`)
+- Building objects to pass into service objects or other units under test
+- You need an object with an `id` but don't need it in the database
+
+**Use `build` when:**
+- Testing model validations (`.valid?`, `.errors`)
+- Testing `before_validation` or `before_save` callbacks
+- You need to call `.save` in the test and check the result
+- Building an object that will be passed to `create` or `save` explicitly
+
+**Use `create` when:**
+- Testing database scopes and queries (`.where`, `.recent`, `.active`)
+- Testing uniqueness validations (need a real record to conflict with)
+- Testing `has_many` / `belongs_to` associations that are loaded via query
+- Testing `after_create` or `after_commit` callbacks
+- Testing code that calls `.reload`
+- Testing counter caches or database-computed columns
+
+## When NOT To Apply
+
+- Don't overthink it for one-off tests. If a test file has 3 examples and they all need `create`, just use `create`. The optimization matters at scale — hundreds of tests, not three.
+- Don't `build_stubbed` when the method under test calls `.reload`, `.save`, or queries the database. It will raise or return stale data.
+
+## Edge Cases
+
+**`build_stubbed` and associations:**
+Stubbed associations work for `belongs_to` (the foreign key is set). They don't work for `has_many` queries (no database to query against).
+
+```ruby
+order = build_stubbed(:order)
+order.user          # Works — returns a stubbed user
+order.line_items    # Returns empty collection — no DB to query
+```
+
+If you need associations, stub them manually or use `build_stubbed` with inline assignment:
+
+```ruby
+items = build_stubbed_list(:line_item, 3)
+order = build_stubbed(:order)
+allow(order).to receive(:line_items).and_return(items)
+```
+
+**`build_stubbed` and `.persisted?`:**
+Stubbed objects return `true` for `.persisted?` and have a fake `id`. This makes them behave like saved records in most contexts — useful for testing path helpers, serializers, and view rendering.
+
+**Testing both validation and persistence:**
+Split into two tests. Validation test uses `build`. Persistence test uses `create`.
+
+```ruby
+describe "email" do
+  it "validates format" do
+    user = build(:user, email: "invalid")
+    expect(user).not_to be_valid
+  end
+
+  it "enforces uniqueness in database" do
+    create(:user, email: "taken@example.com")
+    duplicate = build(:user, email: "taken@example.com")
+    expect(duplicate).not_to be_valid
+  end
+end
+```

data/skills/rspec/factory_design.md

@@ -0,0 +1,206 @@
+# RSpec: Factory Design
+
+## Pattern
+
+Design factories to produce valid records with the minimum possible attributes. Use traits for variations. Use sequences for unique fields. Avoid deeply nested association chains and never put business logic in factories.
+
+```ruby
+# spec/factories/users.rb
+FactoryBot.define do
+  factory :user do
+    sequence(:email) { |n| "user#{n}@example.com" }
+    password { "password123" }
+    name { "Jane Doe" }
+    role { :user }
+    plan { :free }
+
+    trait :admin do
+      role { :admin }
+      sequence(:email) { |n| "admin#{n}@example.com" }
+    end
+
+    trait :pro do
+      plan { :pro }
+    end
+
+    trait :with_api_key do
+      after(:create) do |user|
+        create(:api_key, user: user)
+      end
+    end
+  end
+end
+```
+
+```ruby
+# spec/factories/orders.rb
+FactoryBot.define do
+  factory :order do
+    user
+    sequence(:reference) { |n| "ORD-#{n.to_s.rjust(6, '0')}" }
+    shipping_address { "123 Main St" }
+    status { :pending }
+
+    trait :with_line_items do
+      transient do
+        item_count { 2 }
+      end
+
+      after(:create) do |order, evaluator|
+        create_list(:line_item, evaluator.item_count, order: order)
+        order.reload
+      end
+    end
+
+    trait :shipped do
+      status { :shipped }
+      shipped_at { 1.day.ago }
+    end
+
+    trait :cancelled do
+      status { :cancelled }
+      cancelled_at { 1.hour.ago }
+    end
+
+    trait :high_value do
+      total { 500.00 }
+    end
+  end
+end
+```
+
+```ruby
+# spec/factories/line_items.rb
+FactoryBot.define do
+  factory :line_item do
+    order
+    product
+    quantity { 1 }
+    unit_price { 10.00 }
+  end
+end
+```
+
+Usage in tests:
+
+```ruby
+# Minimal — just what the test needs
+user = build_stubbed(:user)
+admin = build_stubbed(:user, :admin)
+pro_user = create(:user, :pro)
+
+# Compose traits
+order = create(:order, :shipped, :high_value)
+
+# Override specific attributes
+order = create(:order, total: 99.99, user: user)
+
+# Use transient attributes
+order = create(:order, :with_line_items, item_count: 5)
+```
+
+## Why This Is Good
+
+- **Minimal by default.** The base factory creates a valid record with nothing extra. Tests that need specific attributes override them explicitly, making dependencies visible.
+- **Traits are composable.** `:shipped`, `:cancelled`, `:high_value` can be mixed and matched. No need for separate factories like `shipped_order`, `cancelled_order`, `shipped_high_value_order`.
+- **Sequences prevent collisions.** Unique fields use sequences, so tests never fail due to duplicate emails or reference numbers regardless of run order.
+- **Transient attributes control association creation.** `item_count: 5` is clearer than creating 5 line items manually. The complexity is in the factory, not in every test.
+- **Readable test code.** `create(:order, :shipped, :high_value)` reads like a description of what you need. No setup noise.
+
+## Anti-Pattern
+
+Factories with heavy defaults, deep association chains, and business logic:
+
+```ruby
+FactoryBot.define do
+  factory :order do
+    user
+    shipping_address { Faker::Address.full_address }
+    billing_address { Faker::Address.full_address }
+    status { :pending }
+    notes { Faker::Lorem.paragraph }
+    reference { "ORD-#{SecureRandom.hex(6)}" }
+    currency { "USD" }
+    tax_rate { 0.08 }
+    discount_code { nil }
+    ip_address { Faker::Internet.ip_v4_address }
+    user_agent { Faker::Internet.user_agent }
+
+    after(:create) do |order|
+      create_list(:line_item, 3, order: order)
+      order.update!(
+        subtotal: order.line_items.sum(&:total),
+        tax: order.line_items.sum(&:total) * 0.08,
+        total: order.line_items.sum(&:total) * 1.08
+      )
+      create(:shipment, order: order)
+      create(:payment, order: order, amount: order.total)
+      OrderMailer.confirmation(order).deliver_now
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Every `create(:order)` creates 8+ records.** The order, a user, 3 line items, 3 products (via line items), a shipment, and a payment. A test that just needs an order object now waits for 8+ INSERTs.
+- **Side effects in factories.** `OrderMailer.confirmation(order).deliver_now` runs in tests. Every test that creates an order sends an email. Tests become slow and flaky.
+- **Unnecessary data.** `Faker::Lorem.paragraph` for notes, `Faker::Internet.ip_v4_address` for IP — these slow down factory execution with random generation, and the test almost certainly doesn't care about these values.
+- **Hidden coupling.** The factory calculates subtotal, tax, and total. If the calculation logic changes, the factory breaks — or worse, silently produces wrong data that makes tests pass incorrectly.
+- **Can't use `build_stubbed`.** Heavy `after(:create)` callbacks mean this factory only works with `create`. You're forced into database hits even for tests that don't need them.
+
+## When To Apply
+
+Always. Every project using FactoryBot should follow these principles from the start:
+
+- **Base factory has required fields only.** If the model validates presence of `email` and `name`, the factory sets `email` and `name`. Nothing else gets a default unless it's required for validity.
+- **Use traits for every variation.** Don't add optional fields to the base factory. A shipped order is `create(:order, :shipped)`, not a factory that always sets `shipped_at`.
+- **Sequences for every unique field.** Email, reference numbers, slugs, usernames — anything with a uniqueness validation.
+- **Transient attributes for controlled association creation.** Don't create associations in the base factory. Use traits like `:with_line_items` that are opt-in.
+- **No business logic in factories.** Don't calculate totals, send emails, or trigger service objects. Factories create data — that's it.
+
+## When NOT To Apply
+
+- **Seed data is different from factories.** `db/seeds.rb` can and should create rich, interconnected data for development. That's not a factory — different purpose, different rules.
+- **Complex setup for integration/system tests.** System tests may need a fully populated order with line items, shipments, and payments. Use a dedicated factory trait or a setup helper — don't bloat the base factory.
+
+## Edge Cases
+
+**Circular associations:**
+If Order belongs_to User and User has_many Orders, the factory chain can loop. Break the cycle by not auto-creating associations in both directions:
+
+```ruby
+factory :user do
+  # Don't create orders here
+end
+
+factory :order do
+  user # Creates user, but user factory doesn't create orders
+end
+```
+
+**Factories for STI (Single Table Inheritance):**
+Use inheritance in factories too:
+
+```ruby
+factory :notification do
+  user
+  message { "Something happened" }
+
+  factory :email_notification, class: "EmailNotification" do
+    trait :sent do
+      sent_at { 1.hour.ago }
+    end
+  end
+
+  factory :sms_notification, class: "SmsNotification" do
+    phone_number { "+15551234567" }
+  end
+end
+```
+
+**Faker vs static values:**
+Use static values in factories (`name { "Jane Doe" }`), not Faker (`name { Faker::Name.name }`). Faker adds execution time, produces random data that makes test output inconsistent, and occasionally generates values that fail validations (too long, invalid characters). Save Faker for seed data.
+
+**Association strategy mismatch:**
+When using `build_stubbed(:order)`, FactoryBot also stubs the `user` association. But if you `create(:line_item)`, it will `create` (not stub) the associated order. Be deliberate about which strategy you use at each level.

data/skills/rspec/let_vs_let_bang.md

@@ -0,0 +1,161 @@
+# RSpec: let vs let!
+
+## Pattern
+
+Use `let` (lazy) by default. Use `let!` (eager) only when the record must exist in the database before the example runs, and no example in the group references it directly.
+
+```ruby
+RSpec.describe Order do
+  # CORRECT: Lazy — only created when an example calls `user`
+  let(:user) { create(:user) }
+
+  # CORRECT: Lazy — only created when an example calls `order`
+  let(:order) { create(:order, user: user) }
+
+  describe "#total" do
+    # These line items are only created for examples that call `line_items`
+    let(:line_items) do
+      [
+        create(:line_item, order: order, quantity: 2, unit_price: 10.00),
+        create(:line_item, order: order, quantity: 1, unit_price: 25.00)
+      ]
+    end
+
+    it "calculates from line items" do
+      line_items # Trigger creation
+      expect(order.reload.total).to eq(45.00)
+    end
+  end
+
+  describe ".recent" do
+    # CORRECT use of let! — these must exist BEFORE the scope query runs.
+    # No example references `old_order` directly, but it must be in the DB
+    # for the scope to correctly exclude it.
+    let!(:recent_order) { create(:order, created_at: 1.day.ago) }
+    let!(:old_order) { create(:order, created_at: 1.year.ago) }
+
+    it "returns orders from the last 30 days" do
+      expect(Order.recent).to include(recent_order)
+      expect(Order.recent).not_to include(old_order)
+    end
+  end
+end
+```
+
+## Why This Is Good
+
+- **Lazy `let` avoids unnecessary DB hits.** If an example doesn't reference a `let` variable, the record is never created. In a describe block with 10 examples where only 3 need a specific record, you save 7 unnecessary INSERT statements.
+- **Each example is self-documenting.** When you see `let(:order)` used in an example, you know that example needs an order. With `let!`, you have to mentally track "which records exist before every example runs?" even in examples that don't use them.
+- **Faster test suite.** Lazy evaluation means the minimum number of records are created per example. In a large test suite, this compounds into minutes saved.
+- **Memoized per example.** `let` evaluates once per example and caches. Calling `user` three times in one example hits the database once. No need for instance variables.
+
+## Anti-Pattern
+
+Using `let!` everywhere "just to be safe":
+
+```ruby
+RSpec.describe Order do
+  let!(:user) { create(:user) }
+  let!(:admin) { create(:user, role: :admin) }
+  let!(:product) { create(:product) }
+  let!(:category) { create(:category) }
+  let!(:order) { create(:order, user: user) }
+  let!(:line_item) { create(:line_item, order: order, product: product) }
+  let!(:shipping_rate) { create(:shipping_rate) }
+
+  describe "#total" do
+    it "calculates correctly" do
+      # Only needs order and line_item, but ALL 7 records are created
+      expect(order.total).to eq(line_item.quantity * line_item.unit_price)
+    end
+  end
+
+  describe "#shipped?" do
+    it "returns false when pending" do
+      # Only needs order, but ALL 7 records are created
+      expect(order.shipped?).to be false
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Every example pays for every record.** 7 INSERT statements run before every single example, even if the example only needs 1 record. With 20 examples in this describe block, that's 140 INSERTs instead of ~40.
+- **Hides dependencies.** When everything is `let!`, you can't tell which records an example actually needs by reading it. The implicit "everything exists" makes the test harder to understand and maintain.
+- **Masks missing associations.** If an example works only because `let!(:product)` happens to exist, removing it later breaks the test in a confusing way. With `let`, the dependency is explicit — the example calls `product` or it doesn't.
+- **Factory chain explosion.** If `create(:order)` creates a user, and `create(:line_item)` creates a product and a category, `let!` on all of them creates duplicate records you never asked for.
+
+## When To Apply
+
+Use `let!` ONLY when ALL of these are true:
+
+1. The record must exist in the database BEFORE the example runs
+2. The example doesn't reference the variable directly — it's testing a query/scope that should find (or exclude) the record
+3. There's no other way to trigger the creation
+
+The classic case is **testing scopes and queries**:
+
+```ruby
+describe ".active" do
+  let!(:active_user) { create(:user, active: true) }
+  let!(:inactive_user) { create(:user, active: false) }
+
+  it "returns only active users" do
+    # Both must exist in DB before User.active runs
+    # The example references active_user for the assertion but
+    # inactive_user must exist to prove exclusion
+    expect(User.active).to eq([active_user])
+  end
+end
+```
+
+## When NOT To Apply
+
+- **The example references the variable directly.** If the example calls `order`, use `let` — it will be created on first reference.
+- **You're "not sure if it needs to exist first."** Default to `let`. If the test fails because the record doesn't exist, then switch to `let!` for that specific variable. Don't preemptively use `let!`.
+- **You're setting up context for a single example.** Use inline `create` inside the example instead:
+
+```ruby
+it "rejects duplicate emails" do
+  create(:user, email: "taken@example.com")
+  duplicate = build(:user, email: "taken@example.com")
+  expect(duplicate).not_to be_valid
+end
+```
+
+## Edge Cases
+
+**`let` inside a `before` block:**
+Don't. If you need something to exist before all examples, use `let!` or a `before` block with `create` directly. Calling `let` variables inside `before` works but obscures intent.
+
+```ruby
+# Clear intent
+let!(:admin) { create(:user, role: :admin) }
+
+# Also clear
+before { create(:user, role: :admin) }
+
+# Confusing — looks lazy but is eager because before forces evaluation
+let(:admin) { create(:user, role: :admin) }
+before { admin }
+```
+
+**`let` with `build_stubbed`:**
+Always prefer `let(:user) { build_stubbed(:user) }` when the test doesn't need a database record. This is even faster than lazy `let` with `create` because no DB hit ever occurs.
+
+**Nested `describe` blocks with `let`:**
+Inner `let` overrides outer `let` with the same name. This is useful for testing variations:
+
+```ruby
+let(:user) { create(:user, plan: :free) }
+
+context "with pro plan" do
+  let(:user) { create(:user, plan: :pro) }
+  it { expect(user.can_export?).to be true }
+end
+
+context "with free plan" do
+  it { expect(user.can_export?).to be false }
+end
+```