rubyn-code 0.1.0

data/skills/rspec/shared_examples.md

@@ -0,0 +1,244 @@
+# RSpec: Shared Examples
+
+## Pattern
+
+Use `shared_examples` to DRY up specs that verify the same behavior across multiple contexts. Use `shared_context` for shared setup. Keep shared examples focused on one behavior. Pass parameters via `let`, block, or arguments.
+
+```ruby
+# spec/support/shared_examples/authenticated_endpoint.rb
+RSpec.shared_examples "an authenticated endpoint" do
+  context "without API key" do
+    it "returns 401" do
+      make_request(api_key: nil)
+      expect(response).to have_http_status(:unauthorized)
+    end
+  end
+
+  context "with revoked API key" do
+    let(:api_key) { create(:api_key, :revoked) }
+
+    it "returns 401" do
+      make_request(api_key: api_key.raw_key)
+      expect(response).to have_http_status(:unauthorized)
+    end
+  end
+
+  context "with expired API key" do
+    let(:api_key) { create(:api_key, :expired) }
+
+    it "returns 401" do
+      make_request(api_key: api_key.raw_key)
+      expect(response).to have_http_status(:unauthorized)
+    end
+  end
+end
+```
+
+```ruby
+# spec/support/shared_examples/credit_deducting_endpoint.rb
+RSpec.shared_examples "a credit-deducting endpoint" do
+  it "deducts credits on success" do
+    expect { make_request }.to change { user.credit_ledger_entries.count }.by(1)
+  end
+
+  it "records the interaction" do
+    expect { make_request }.to change(Interaction, :count).by(1)
+  end
+
+  context "with insufficient credits" do
+    before do
+      allow_any_instance_of(Credits::BalanceChecker).to receive(:sufficient?).and_return(false)
+    end
+
+    it "returns 402" do
+      make_request
+      expect(response).to have_http_status(:payment_required)
+    end
+
+    it "does not call Claude" do
+      make_request
+      expect(Ai::ClaudeClient).not_to have_received(:call)
+    end
+  end
+end
+```
+
+```ruby
+# spec/support/shared_examples/project_scoped_endpoint.rb
+RSpec.shared_examples "a project-scoped endpoint" do
+  context "when user is not a member of the project" do
+    let(:other_project) { create(:project) }
+
+    it "returns 403" do
+      make_request(project_id: other_project.id)
+      expect(response).to have_http_status(:forbidden)
+    end
+  end
+
+  context "when project does not exist" do
+    it "returns 404" do
+      make_request(project_id: 999999)
+      expect(response).to have_http_status(:not_found)
+    end
+  end
+end
+```
+
+Using shared examples in specs:
+
+```ruby
+# spec/requests/api/v1/ai/refactor_spec.rb
+RSpec.describe "POST /api/v1/ai/refactor", type: :request do
+  let(:user) { create(:user, :pro) }
+  let(:project) { create(:project) }
+  let(:membership) { create(:project_membership, user: user, project: project) }
+
+  def make_request(api_key: user.api_keys.first.raw_key, project_id: project.id)
+    post "/api/v1/ai/refactor",
+         params: { file_path: "app/controllers/orders_controller.rb", file_content: "...", project_id: project_id },
+         headers: { "Authorization" => "Bearer #{api_key}" }
+  end
+
+  before { membership }
+
+  it_behaves_like "an authenticated endpoint"
+  it_behaves_like "a credit-deducting endpoint"
+  it_behaves_like "a project-scoped endpoint"
+
+  # Endpoint-specific tests
+  it "returns a streaming response" do
+    make_request
+    expect(response).to have_http_status(:ok)
+    expect(response.content_type).to include("text/event-stream")
+  end
+end
+```
+
+Shared context for common setup:
+
+```ruby
+# spec/support/shared_contexts/with_stubbed_claude.rb
+RSpec.shared_context "with stubbed Claude" do
+  let(:claude_response) { "Here is the refactored code..." }
+
+  before do
+    allow(Ai::ClaudeClient).to receive(:call).and_return(
+      OpenStruct.new(
+        content: claude_response,
+        input_tokens: 500,
+        output_tokens: 200,
+        cache_read_tokens: 400,
+        cache_write_tokens: 0
+      )
+    )
+  end
+end
+
+# Usage
+RSpec.describe Orders::CreateService do
+  include_context "with stubbed Claude"
+
+  it "uses the stubbed response" do
+    # Claude is already stubbed
+  end
+end
+```
+
+## Why This Is Good
+
+- **DRY without obscuring.** Auth checks are the same for every endpoint. Writing them once in a shared example and including them with `it_behaves_like` is clearer than copy-pasting the same 20 lines into 30 spec files.
+- **Consistent coverage.** When you add a new auth check (e.g., "suspended account returns 403"), you add it to the shared example once. Every endpoint that includes it gets the new test automatically.
+- **Contract enforcement.** `it_behaves_like "a credit-deducting endpoint"` acts as a contract: every AI endpoint must deduct credits. If a new endpoint doesn't pass the shared example, it's missing credit deduction logic.
+- **Readable spec files.** The endpoint spec reads like a checklist: it's authenticated, it deducts credits, it's project-scoped, and here are the endpoint-specific behaviors.
+- **Shared contexts reduce boilerplate.** Stubbing Claude the same way in 20 spec files is noisy. A shared context does it once and every spec file includes it by name.
+
+## Anti-Pattern
+
+Shared examples that are too broad, too abstract, or tightly coupled to implementation:
+
+```ruby
+# BAD: Shared example that does everything
+RSpec.shared_examples "a standard API endpoint" do |method, path|
+  it "requires auth" do
+    send(method, path)
+    expect(response).to have_http_status(:unauthorized)
+  end
+
+  it "requires project membership" do
+    send(method, path, headers: auth_headers)
+    expect(response).to have_http_status(:forbidden)
+  end
+
+  it "deducts credits" do
+    expect { send(method, path, params: valid_params, headers: auth_headers) }
+      .to change(CreditLedger, :count)
+  end
+
+  it "records the interaction" do
+    expect { send(method, path, params: valid_params, headers: auth_headers) }
+      .to change(Interaction, :count)
+  end
+
+  it "returns success" do
+    send(method, path, params: valid_params, headers: auth_headers)
+    expect(response).to have_http_status(:ok)
+  end
+end
+
+# Usage becomes cryptic
+it_behaves_like "a standard API endpoint", :post, "/api/v1/ai/refactor"
+```
+
+```ruby
+# BAD: Shared example in a deeply nested file nobody can find
+# spec/support/shared_examples/concerns/models/trackable_behavior_for_auditable_records.rb
+RSpec.shared_examples "trackable auditable behavior" do
+  # 50 lines of tests that are impossible to discover
+end
+```
+
+## Why This Is Bad
+
+- **God shared examples test too many things at once.** When `"a standard API endpoint"` fails, you don't know if it's an auth issue, a credit issue, or a response format issue. Smaller shared examples give focused feedback.
+- **Parameterized shared examples are hard to read.** `it_behaves_like "a standard API endpoint", :post, "/api/v1/ai/refactor"` hides what's being tested. The reader has to open the shared example file to understand what 5 tests are running.
+- **Over-abstracted names.** `"trackable auditable behavior"` doesn't communicate what it tests. `"an authenticated endpoint"` does. Name shared examples by the behavior they verify.
+- **Hidden in deep directories.** If shared examples are buried in `spec/support/shared_examples/concerns/models/`, nobody will find or use them. Keep them in `spec/support/shared_examples/` at one level deep.
+
+## When To Apply
+
+- **Identical behavior across multiple specs.** Authentication, authorization, credit deduction, pagination, error handling — if 10+ specs verify the same behavior, extract it.
+- **Contract testing.** "Every AI endpoint must deduct credits" is a contract. A shared example enforces it.
+- **Setup that's the same across a describe group.** `shared_context` for stubbing external services, setting up test data, or configuring the test environment.
+
+## When NOT To Apply
+
+- **Behavior specific to one endpoint.** If only the refactor endpoint has a specific behavior, test it inline. Don't create a shared example for one consumer.
+- **When the shared example needs more than 2 parameters.** If you're passing 4 arguments to configure the shared example, it's too abstract. Write the tests inline.
+- **When the setup is simple.** A 2-line `before` block doesn't need a shared context. Just write the 2 lines.
+
+## Edge Cases
+
+**Shared examples that need different setup per includer:**
+Use `let` overrides. The shared example references `let(:user)` — each including spec defines its own `user`:
+
+```ruby
+RSpec.shared_examples "a credit-deducting endpoint" do
+  it "deducts from the user's balance" do
+    expect { make_request }.to change { user.reload.credit_balance }
+  end
+end
+
+# Spec A
+let(:user) { create(:user, :pro) }
+it_behaves_like "a credit-deducting endpoint"
+
+# Spec B — different user setup, same shared example
+let(:user) { create(:user, :free) }
+it_behaves_like "a credit-deducting endpoint"
+```
+
+**`it_behaves_like` vs `include_examples`:**
+`it_behaves_like` creates a nested context (its own describe block). `include_examples` runs the examples in the current context. Use `it_behaves_like` when you want isolation. Use `include_examples` when the examples need access to the current context's `let` variables.
+
+**Shared examples across spec types:**
+An authenticated endpoint shared example works for both request specs and API specs. Keep them generic enough to work across contexts, using `make_request` as the interface contract.

data/skills/rspec/system_specs.md

@@ -0,0 +1,286 @@
+# RSpec: System Specs (Capybara)
+
+## Pattern
+
+System specs drive a real browser to test complete user journeys — clicking, filling forms, seeing results. They're the most expensive specs but provide the highest confidence that the feature works end-to-end. Write them for critical paths, not every edge case.
+
+```ruby
+# spec/system/order_checkout_spec.rb
+require "rails_helper"
+
+RSpec.describe "Order checkout", type: :system do
+  let(:user) { create(:user) }
+  let!(:product) { create(:product, name: "Widget", price: 25_00, stock: 10) }
+
+  before do
+    driven_by(:selenium_chrome_headless)
+    sign_in user
+  end
+
+  it "completes a full checkout flow" do
+    # Browse products
+    visit products_path
+    expect(page).to have_content("Widget")
+    expect(page).to have_content("$25.00")
+
+    # Add to cart
+    within "#product_#{product.id}" do
+      click_button "Add to Cart"
+    end
+    expect(page).to have_content("Added to cart")
+
+    # View cart and proceed
+    visit cart_path
+    expect(page).to have_content("Widget")
+    fill_in "Quantity", with: "2"
+    click_button "Update"
+    expect(page).to have_content("$50.00")
+
+    # Checkout
+    click_link "Checkout"
+    fill_in "Shipping address", with: "123 Main St, Austin, TX 78701"
+    click_button "Place Order"
+
+    # Confirmation
+    expect(page).to have_content("Order placed")
+    expect(page).to have_content("ORD-")
+    expect(page).to have_content("$50.00")
+    expect(page).to have_content("123 Main St")
+  end
+
+  it "shows validation errors for incomplete checkout" do
+    visit new_order_path
+    click_button "Place Order"
+
+    expect(page).to have_content("Shipping address can't be blank")
+    expect(page).to have_selector(".field_with_errors")
+  end
+
+  it "prevents checkout when product is out of stock" do
+    product.update!(stock: 0)
+    visit product_path(product)
+
+    expect(page).to have_content("Out of Stock")
+    expect(page).not_to have_button("Add to Cart")
+  end
+end
+```
+
+### Testing JavaScript Interactions
+
+```ruby
+RSpec.describe "Order management", type: :system do
+  before do
+    driven_by(:selenium_chrome_headless)
+    sign_in create(:user, :admin)
+  end
+
+  it "filters orders with live search" do
+    create(:order, reference: "ORD-001", status: :pending)
+    create(:order, reference: "ORD-002", status: :shipped)
+
+    visit admin_orders_path
+
+    # Turbo Frame search — updates without page reload
+    fill_in "Search", with: "ORD-001"
+
+    # Capybara auto-waits for the DOM to update
+    expect(page).to have_content("ORD-001")
+    expect(page).not_to have_content("ORD-002")
+  end
+
+  it "toggles order details inline" do
+    order = create(:order, :with_line_items)
+    visit admin_orders_path
+
+    # Click to expand details (Stimulus controller)
+    within "#order_#{order.id}" do
+      click_button "Details"
+      expect(page).to have_content(order.line_items.first.product.name)
+
+      # Click again to collapse
+      click_button "Details"
+      expect(page).not_to have_content(order.line_items.first.product.name)
+    end
+  end
+
+  it "handles confirmation dialogs" do
+    order = create(:order, :pending)
+    visit admin_order_path(order)
+
+    accept_confirm "Are you sure you want to cancel this order?" do
+      click_button "Cancel Order"
+    end
+
+    expect(page).to have_content("Order cancelled")
+    expect(page).to have_content("Cancelled")
+  end
+
+  it "handles dismiss of confirmation" do
+    order = create(:order, :pending)
+    visit admin_order_path(order)
+
+    dismiss_confirm do
+      click_button "Cancel Order"
+    end
+
+    expect(page).to have_content("Pending")  # Status unchanged
+  end
+end
+```
+
+### Testing Authentication Flows
+
+```ruby
+RSpec.describe "Authentication", type: :system do
+  before { driven_by(:selenium_chrome_headless) }
+
+  it "signs in with valid credentials" do
+    user = create(:user, email: "alice@example.com", password: "securepassword")
+
+    visit new_user_session_path
+    fill_in "Email", with: "alice@example.com"
+    fill_in "Password", with: "securepassword"
+    click_button "Sign In"
+
+    expect(page).to have_content("Signed in successfully")
+    expect(page).to have_content("alice@example.com")
+  end
+
+  it "rejects invalid credentials" do
+    create(:user, email: "alice@example.com", password: "securepassword")
+
+    visit new_user_session_path
+    fill_in "Email", with: "alice@example.com"
+    fill_in "Password", with: "wrongpassword"
+    click_button "Sign In"
+
+    expect(page).to have_content("Invalid Email or password")
+    expect(page).to have_current_path(new_user_session_path)
+  end
+
+  it "redirects unauthenticated users to sign in" do
+    visit orders_path
+
+    expect(page).to have_current_path(new_user_session_path)
+    expect(page).to have_content("You need to sign in")
+  end
+end
+```
+
+### Setup and Configuration
+
+```ruby
+# spec/rails_helper.rb (relevant additions)
+RSpec.configure do |config|
+  # System test configuration
+  config.before(:each, type: :system) do
+    driven_by :selenium_chrome_headless
+  end
+
+  # Use visible Chrome for debugging (override in specific tests)
+  # driven_by :selenium, using: :chrome, screen_size: [1400, 900]
+end
+```
+
+```ruby
+# spec/support/system_helpers.rb
+module SystemHelpers
+  def sign_in(user)
+    visit new_user_session_path
+    fill_in "Email", with: user.email
+    fill_in "Password", with: "password"  # Assumes factory default
+    click_button "Sign In"
+    expect(page).to have_content("Signed in")
+  end
+
+  def sign_out
+    click_link "Sign Out"
+  end
+end
+
+RSpec.configure do |config|
+  config.include SystemHelpers, type: :system
+end
+```
+
+### Capybara Matchers Cheat Sheet
+
+```ruby
+# Content assertions
+expect(page).to have_content("text")           # Anywhere on page
+expect(page).not_to have_content("text")
+expect(page).to have_selector("h1", text: "Orders")  # CSS + text
+expect(page).to have_selector(".badge", count: 3)     # Exact count
+
+# Form assertions
+expect(page).to have_field("Email", with: "alice@example.com")
+expect(page).to have_checked_field("Remember me")
+expect(page).to have_select("Status", selected: "Pending")
+expect(page).to have_button("Submit")
+expect(page).to have_link("Edit")
+
+# Scoping
+within "#order-form" do
+  fill_in "Address", with: "123 Main"
+  click_button "Save"
+end
+
+within_table "orders" do
+  expect(page).to have_content("ORD-001")
+end
+
+# Waiting (Capybara auto-waits by default, up to Capybara.default_max_wait_time)
+expect(page).to have_content("Loading complete")           # Waits automatically
+expect(page).to have_selector(".result", wait: 10)         # Custom wait time
+expect(page).to have_no_content("Loading...", wait: 5)     # Wait for disappearance
+
+# Navigation
+expect(page).to have_current_path(orders_path)
+expect(page).to have_current_path(/orders\/\d+/)  # Regex match
+
+# JavaScript
+page.execute_script("window.scrollTo(0, document.body.scrollHeight)")
+accept_alert { click_link "Dangerous" }
+accept_confirm { click_button "Delete" }
+dismiss_confirm { click_button "Delete" }
+```
+
+## Why This Is Good
+
+- **Tests what users actually experience.** Click a button, fill a form, see a result. If this test passes, the feature works.
+- **Catches integration bugs.** Broken JavaScript, missing CSRF tokens, Turbo Frame issues, CSS hiding elements — system specs catch what unit tests miss.
+- **Capybara auto-waits.** `have_content` waits for text to appear (for async rendering, Turbo updates). No manual `sleep` calls for most cases.
+- **`driven_by :selenium_chrome_headless`** runs fast without a visible browser window.
+
+## Anti-Pattern
+
+```ruby
+# BAD: Testing model logic in a system spec
+it "validates email format" do
+  visit signup_path
+  fill_in "Email", with: "invalid"
+  click_button "Sign Up"
+  expect(page).to have_content("Email is invalid")
+end
+# This takes 2-3 seconds. A model spec does it in 2ms:
+# expect(User.new(email: "invalid")).not_to be_valid
+
+# BAD: Testing every edge case in system specs
+# 15 system specs for form validation ← TOO MANY
+# 1 system spec for happy path + 14 model specs for validations ← RIGHT
+```
+
+## When To Apply
+
+- **Critical user journeys.** Sign up, sign in, checkout, key CRUD flows — 1 system spec per journey.
+- **JavaScript-dependent features.** Turbo Frames, Stimulus controllers, live search, modals, drag-and-drop.
+- **Smoke tests.** One test per major page to verify it loads without errors.
+- **Keep count low.** Target 10-30 system specs for a typical Rails app. Not 200.
+
+## When NOT To Apply
+
+- **Validation logic.** Test in model specs (2ms vs 2s).
+- **API endpoints.** Test with request specs — no browser needed.
+- **Service object logic.** Test in service specs.
+- **Every permutation.** System specs for happy paths. Unit tests for edge cases.