rubyn-code 0.1.0

data/skills/minitest/service_tests_and_performance.md

@@ -0,0 +1,246 @@
+# Minitest: Testing Service Objects
+
+## Pattern
+
+Test service objects by calling `.call` with real or fixture data. Assert on the result object, side effects (DB changes, jobs enqueued, emails sent), and error conditions. Inject doubles for external dependencies.
+
+```ruby
+# test/services/orders/create_service_test.rb
+require "test_helper"
+
+class Orders::CreateServiceTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:alice)
+    @product = products(:widget)
+  end
+
+  test "creates an order with valid params" do
+    result = Orders::CreateService.call(valid_params, @user)
+
+    assert result.success?
+    assert_instance_of Order, result.order
+    assert_equal "pending", result.order.status
+    assert_equal @user, result.order.user
+  end
+
+  test "creates a database record" do
+    assert_difference "Order.count", 1 do
+      Orders::CreateService.call(valid_params, @user)
+    end
+  end
+
+  test "sends confirmation email" do
+    assert_emails 1 do
+      Orders::CreateService.call(valid_params, @user)
+    end
+  end
+
+  test "enqueues warehouse notification" do
+    assert_enqueued_with(job: WarehouseNotificationJob) do
+      Orders::CreateService.call(valid_params, @user)
+    end
+  end
+
+  test "returns failure for invalid params" do
+    result = Orders::CreateService.call({ shipping_address: "" }, @user)
+
+    refute result.success?
+    assert result.order.errors[:shipping_address].any?
+  end
+
+  test "does not create record on failure" do
+    assert_no_difference "Order.count" do
+      Orders::CreateService.call({ shipping_address: "" }, @user)
+    end
+  end
+
+  test "does not send email on failure" do
+    assert_no_emails do
+      Orders::CreateService.call({ shipping_address: "" }, @user)
+    end
+  end
+
+  private
+
+  def valid_params
+    {
+      shipping_address: "123 Main St",
+      line_items_attributes: [
+        { product_id: @product.id, quantity: 2 }
+      ]
+    }
+  end
+end
+```
+
+Testing services with external dependencies:
+
+```ruby
+# test/services/embeddings/codebase_indexer_test.rb
+require "test_helper"
+
+class Embeddings::CodebaseIndexerTest < ActiveSupport::TestCase
+  setup do
+    @project = projects(:rubyn_project)
+    @fake_embedder = FakeEmbedder.new
+    @indexer = Embeddings::CodebaseIndexer.new(embedding_client: @fake_embedder)
+  end
+
+  test "creates code embeddings for each chunk" do
+    file_content = <<~RUBY
+      class Order < ApplicationRecord
+        def total
+          line_items.sum(&:subtotal)
+        end
+      end
+    RUBY
+
+    assert_difference "@project.code_embeddings.count" do
+      @indexer.index_file(@project, "app/models/order.rb", file_content)
+    end
+  end
+
+  test "stores the file path on each embedding" do
+    @indexer.index_file(@project, "app/models/order.rb", "class Order; end")
+
+    embedding = @project.code_embeddings.last
+    assert_equal "app/models/order.rb", embedding.file_path
+  end
+
+  test "stores a file hash for change detection" do
+    content = "class Order; end"
+    @indexer.index_file(@project, "app/models/order.rb", content)
+
+    embedding = @project.code_embeddings.last
+    assert_equal Digest::SHA256.hexdigest(content), embedding.file_hash
+  end
+
+  test "skips unchanged files" do
+    content = "class Order; end"
+    @indexer.index_file(@project, "app/models/order.rb", content)
+
+    assert_no_difference "@project.code_embeddings.count" do
+      @indexer.index_file(@project, "app/models/order.rb", content)
+    end
+  end
+end
+
+# test/support/fake_embedder.rb
+class FakeEmbedder
+  DIMENSIONS = 1024
+
+  def embed(texts)
+    texts.map { Array.new(DIMENSIONS) { rand(-1.0..1.0) } }
+  end
+
+  def embed_query(text)
+    Array.new(DIMENSIONS) { rand(-1.0..1.0) }
+  end
+end
+```
+
+# Minitest: Test Performance
+
+## Pattern
+
+Keep the suite fast: use fixtures, parallelize, avoid unnecessary DB writes, and profile regularly.
+
+```ruby
+# test/test_helper.rb
+class ActiveSupport::TestCase
+  # Run tests in parallel across CPU cores
+  parallelize(workers: :number_of_processors)
+
+  # Use transactions (default) — fastest cleanup strategy
+  # Each test rolls back, no data persists between tests
+  self.use_transactional_tests = true
+
+  fixtures :all
+end
+```
+
+### Profile slow tests
+
+```bash
+# Find the 10 slowest tests
+bundle exec rails test --verbose 2>&1 | sort -t= -k2 -rn | head -10
+
+# Or use minitest-reporters for detailed timing
+```
+
+```ruby
+# Gemfile
+group :test do
+  gem "minitest-reporters"
+end
+
+# test/test_helper.rb
+require "minitest/reporters"
+Minitest::Reporters.use! [
+  Minitest::Reporters::DefaultReporter.new,
+  Minitest::Reporters::MeanTimeReporter.new  # Tracks average test times
+]
+```
+
+### Speed tips
+
+```ruby
+# FAST: Use fixtures (zero per-test cost)
+test "something with alice" do
+  assert users(:alice).valid?
+end
+
+# SLOW: Creating records per test
+test "something with a user" do
+  user = User.create!(email: "test@example.com", name: "Test", password: "password")
+  assert user.valid?
+end
+
+# FAST: Test pure logic without DB
+test "money arithmetic" do
+  price = Money.new(10_00)
+  tax = price * 0.08
+
+  assert_equal Money.new(80), tax
+end
+
+# FAST: Build without saving when testing validations
+test "requires email" do
+  user = User.new(email: nil)
+  refute user.valid?
+end
+
+# FAST: Stub slow external calls
+test "handles API timeout" do
+  WarehouseApi.stub(:notify, ->(*) { raise Faraday::TimeoutError }) do
+    result = Orders::ShipService.call(orders(:pending_order))
+    refute result.success?
+  end
+end
+```
+
+### Parallel test configuration
+
+```ruby
+# For system tests or tests that need separate DB state
+class ActiveSupport::TestCase
+  parallelize(workers: :number_of_processors)
+
+  # If parallel tests have DB issues, use:
+  parallelize_setup do |worker|
+    ActiveStorage::Blob.service.root = "#{ActiveStorage::Blob.service.root}-#{worker}"
+  end
+end
+```
+
+## Speed Hierarchy
+
+1. **Pure Ruby assertions** (no DB) — microseconds
+2. **Fixture reads** — microseconds (data already loaded)
+3. **`User.new` + `.valid?`** — milliseconds (no DB write)
+4. **Single `create!`** — ~1-5ms
+5. **Factory with associations** — ~5-50ms (cascading creates)
+6. **Integration test** — ~10-100ms (full request cycle)
+7. **System test with browser** — ~500ms-5s
+
+Optimize by pushing tests as high on this list as possible. Don't use an integration test when a unit test will do. Don't create records when fixtures exist.

data/skills/minitest/structure_and_conventions.md

@@ -0,0 +1,169 @@
+# Minitest: Test Structure and Conventions
+
+## Pattern
+
+Minitest ships with Ruby — no extra gems needed. It provides two styles: `Minitest::Test` (classic xUnit) and `Minitest::Spec` (describe/it blocks). Both are fast, simple, and explicit. Choose one style per project and stick with it.
+
+### Classic Style (Minitest::Test)
+
+```ruby
+# test/models/order_test.rb
+require "test_helper"
+
+class OrderTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:alice)
+    @order = orders(:pending_order)
+  end
+
+  test "calculates total from line items" do
+    line_item = LineItem.create!(order: @order, product: products(:widget), quantity: 2, unit_price: 10_00)
+
+    assert_equal 20_00, @order.reload.total
+  end
+
+  test "requires a shipping address" do
+    order = Order.new(user: @user, shipping_address: nil)
+
+    assert_not order.valid?
+    assert_includes order.errors[:shipping_address], "can't be blank"
+  end
+
+  test "pending? returns true for pending orders" do
+    assert_predicate @order, :pending?
+  end
+
+  test "pending? returns false for shipped orders" do
+    @order.update!(status: :shipped)
+
+    refute_predicate @order, :pending?
+  end
+
+  test ".recent returns orders from the last 30 days" do
+    old_order = Order.create!(user: @user, shipping_address: "123 Main", created_at: 60.days.ago)
+
+    recent = Order.recent
+
+    assert_includes recent, @order
+    refute_includes recent, old_order
+  end
+end
+```
+
+### Spec Style (Minitest::Spec)
+
+```ruby
+# test/models/order_spec.rb
+require "test_helper"
+
+describe Order do
+  let(:user) { users(:alice) }
+  let(:order) { orders(:pending_order) }
+
+  describe "#total" do
+    it "calculates from line items" do
+      LineItem.create!(order: order, product: products(:widget), quantity: 2, unit_price: 10_00)
+
+      _(order.reload.total).must_equal 20_00
+    end
+  end
+
+  describe "validations" do
+    it "requires shipping address" do
+      order = Order.new(user: user, shipping_address: nil)
+
+      _(order).wont_be :valid?
+      _(order.errors[:shipping_address]).must_include "can't be blank"
+    end
+  end
+
+  describe ".recent" do
+    it "excludes orders older than 30 days" do
+      old_order = Order.create!(user: user, shipping_address: "123 Main", created_at: 60.days.ago)
+
+      _(Order.recent).must_include order
+      _(Order.recent).wont_include old_order
+    end
+  end
+end
+```
+
+### The test_helper.rb
+
+```ruby
+# test/test_helper.rb
+ENV["RAILS_ENV"] ||= "test"
+require_relative "../config/environment"
+require "rails/test_help"
+require "minitest/autorun"
+require "minitest/pride"      # Colorful output
+require "webmock/minitest"    # Stub HTTP requests
+
+class ActiveSupport::TestCase
+  # Run tests in parallel
+  parallelize(workers: :number_of_processors)
+
+  # Use fixtures
+  fixtures :all
+
+  # Shared helpers available in all tests
+  def sign_in(user)
+    post login_path, params: { email: user.email, password: "password" }
+  end
+
+  def json_response
+    JSON.parse(response.body, symbolize_names: true)
+  end
+end
+
+class ActionDispatch::IntegrationTest
+  # Helpers for integration tests
+  def auth_headers(user)
+    { "Authorization" => "Bearer #{user.api_keys.first.raw_key}" }
+  end
+end
+```
+
+## Why This Is Good
+
+- **Ships with Ruby.** No Gemfile additions, no version conflicts, no `bundle install` waiting. It's always there.
+- **Fast by default.** Minitest is ~5x faster to boot than RSpec. On a 500-test suite, this can save 3-5 seconds per run.
+- **Plain Ruby.** Tests are classes with methods. No DSL magic, no `let` memoization surprises, no hidden context. Everything is explicit.
+- **Fixtures over factories.** Rails fixtures load once, wrap in transactions, and are instant. No N factory creates per test.
+- **Parallel by default.** `parallelize(workers: :number_of_processors)` runs tests across CPU cores out of the box.
+
+## Anti-Pattern
+
+Overly complex test setup that mimics RSpec patterns instead of using Minitest idioms:
+
+```ruby
+# BAD: Fighting Minitest to write RSpec-style tests
+class OrderTest < ActiveSupport::TestCase
+  # Don't try to replicate RSpec's let/subject/context nesting
+  def setup
+    @company = Company.create!(name: "Acme")
+    @user = User.create!(email: "test@example.com", company: @company)
+    @product = Product.create!(name: "Widget", price: 10_00, company: @company)
+    @order = Order.create!(user: @user, shipping_address: "123 Main")
+    @line_item = LineItem.create!(order: @order, product: @product, quantity: 2, unit_price: 10_00)
+  end
+
+  # Every test pays for all 5 creates even if it only needs @user
+end
+```
+
+## Why This Is Bad
+
+- **Setup creates everything for every test.** A validation test that only needs an Order still creates Company, User, Product, and LineItem.
+- **Fixtures solve this.** Define the data once in YAML, load it once per suite, wrap in transactions. Zero per-test cost.
+
+## When To Apply
+
+- **Every Ruby or Rails project.** Minitest is the Rails default. New projects should start with it unless the team has strong RSpec preferences.
+- **When test speed matters.** Minitest boots faster and runs faster. For CI-heavy teams, this compounds.
+- **When simplicity matters.** Junior developers and contributors learn Minitest in minutes. It's just Ruby.
+
+## When NOT To Apply
+
+- **The team already uses RSpec.** Don't switch mid-project. The cost of rewriting tests exceeds any speed benefit.
+- **You need advanced matchers.** RSpec's `have_attributes`, `change { }.by`, `contain_exactly` are more expressive for complex assertions. Minitest can do the same but with more verbose code.

data/skills/minitest/system_tests.md

@@ -0,0 +1,237 @@
+# Minitest: System Tests (Capybara)
+
+## Pattern
+
+System tests drive a real browser to test full user journeys — clicking links, filling forms, asserting visible content. They're the most expensive tests but provide the highest confidence that the app works end-to-end.
+
+```ruby
+# test/system/orders_test.rb
+require "application_system_test_case"
+
+class OrdersTest < ApplicationSystemTestCase
+  setup do
+    @user = users(:alice)
+    sign_in_as @user
+  end
+
+  test "viewing the orders list" do
+    visit orders_path
+
+    assert_text "Your Orders"
+    assert_text orders(:pending_order).reference
+  end
+
+  test "creating a new order" do
+    visit new_order_path
+
+    fill_in "Shipping address", with: "789 Elm St, Austin, TX"
+    select "Widget", from: "Product"
+    fill_in "Quantity", with: "3"
+
+    click_button "Place Order"
+
+    assert_text "Order placed"
+    assert_text "789 Elm St"
+    assert_text "Widget"
+  end
+
+  test "editing an existing order" do
+    visit order_path(orders(:pending_order))
+
+    click_link "Edit"
+
+    fill_in "Shipping address", with: "Updated Address"
+    click_button "Save"
+
+    assert_text "Updated"
+    assert_text "Updated Address"
+  end
+
+  test "cancelling an order" do
+    visit order_path(orders(:pending_order))
+
+    accept_confirm "Are you sure?" do
+      click_button "Cancel Order"
+    end
+
+    assert_text "Order cancelled"
+    assert_text "Cancelled"
+  end
+
+  test "searching orders" do
+    visit orders_path
+
+    fill_in "Search", with: orders(:pending_order).reference
+    click_button "Search"
+
+    assert_text orders(:pending_order).reference
+    assert_no_text orders(:shipped_order).reference
+  end
+
+  test "pagination" do
+    # Create enough orders to trigger pagination
+    30.times { |i| Order.create!(user: @user, reference: "ORD-#{i}", shipping_address: "Test", status: :pending, total: 10_00) }
+
+    visit orders_path
+
+    assert_selector ".order-row", count: 25  # First page
+    click_link "Next"
+    assert_selector ".order-row"  # Second page has remaining orders
+  end
+
+  private
+
+  def sign_in_as(user)
+    visit login_path
+    fill_in "Email", with: user.email
+    fill_in "Password", with: "password"
+    click_button "Sign In"
+    assert_text "Signed in"
+  end
+end
+```
+
+### Setup
+
+```ruby
+# test/application_system_test_case.rb
+require "test_helper"
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  # Headless Chrome — fast, no browser window pops up
+  driven_by :selenium, using: :headless_chrome, screen_size: [1400, 900]
+
+  # Use visible Chrome for debugging
+  # driven_by :selenium, using: :chrome, screen_size: [1400, 900]
+
+  def take_debug_screenshot
+    take_screenshot  # Saves to tmp/screenshots/
+  end
+end
+```
+
+### Testing Turbo/Hotwire Interactions
+
+```ruby
+class TurboOrdersTest < ApplicationSystemTestCase
+  setup do
+    sign_in_as users(:alice)
+  end
+
+  test "inline editing with Turbo Frames" do
+    visit orders_path
+
+    within "##{dom_id(orders(:pending_order))}" do
+      click_link "Edit"
+
+      # The form appears INSIDE the frame (no page navigation)
+      fill_in "Shipping address", with: "New Address"
+      click_button "Save"
+    end
+
+    # The frame updates in-place
+    assert_text "New Address"
+    assert_no_selector "form"  # Form is gone, replaced with display
+  end
+
+  test "live search with debounce" do
+    visit orders_path
+
+    fill_in "Search", with: orders(:pending_order).reference
+
+    # Wait for Turbo Frame to update (debounced search)
+    assert_text orders(:pending_order).reference
+    assert_no_text orders(:shipped_order).reference
+  end
+
+  test "flash messages appear and dismiss" do
+    visit new_order_path
+    fill_in "Shipping address", with: "123 Main St"
+    click_button "Place Order"
+
+    assert_text "Order placed"
+
+    # Flash auto-dismisses after a few seconds (Stimulus controller)
+    sleep 4
+    assert_no_text "Order placed"
+  end
+end
+```
+
+### Capybara Matchers Cheat Sheet
+
+```ruby
+# Finding elements
+assert_text "Expected text"                          # Anywhere on page
+assert_no_text "Should not appear"
+assert_selector "h1", text: "Orders"                 # CSS selector with text
+assert_selector ".order-row", count: 5               # Exact count
+assert_selector "#order_123"                         # By ID
+assert_link "Edit"                                   # Link text
+assert_button "Submit"                               # Button text
+assert_field "Email", with: "alice@example.com"      # Input with value
+
+# Scoping
+within "#order-form" do
+  fill_in "Address", with: "123 Main"
+  click_button "Save"
+end
+
+within_table "orders" do
+  assert_text "ORD-001"
+end
+
+# Waiting (Capybara auto-waits by default)
+assert_text "Loading complete"  # Waits up to Capybara.default_max_wait_time
+
+# Force wait for async operations
+assert_selector ".result", wait: 10  # Wait up to 10 seconds
+
+# JavaScript interactions
+accept_confirm { click_button "Delete" }
+dismiss_confirm { click_button "Delete" }
+accept_alert { click_link "Dangerous action" }
+
+page.execute_script("window.scrollTo(0, document.body.scrollHeight)")
+```
+
+## Why This Is Good
+
+- **Tests what users see.** "Fill in email, click sign in, see dashboard" — this is the user's actual experience. If this test passes, the feature works.
+- **Catches integration bugs.** JavaScript errors, broken Turbo Frames, missing CSRF tokens, CSS hiding elements — system tests catch what unit tests miss.
+- **Capybara auto-waits.** `assert_text` waits for the text to appear (up to the max wait time). No manual `sleep` needed for most async operations.
+
+## Anti-Pattern
+
+Too many system tests or testing logic that belongs in unit tests:
+
+```ruby
+# BAD: Testing validation messages in a system test
+test "shows error for blank email" do
+  visit registration_path
+  fill_in "Email", with: ""
+  click_button "Sign Up"
+  assert_text "Email can't be blank"
+end
+# This takes 2-3 seconds. A model test takes 2ms.
+```
+
+## When To Apply
+
+- **Critical user journeys only.** Sign up, sign in, checkout, key CRUD flows. 10-20 system tests, not 200.
+- **JavaScript-dependent features.** Turbo Frames, Stimulus controllers, live search, modals.
+- **Smoke tests.** One test per major page to verify it loads without errors.
+
+## When NOT To Apply
+
+- **Validation logic.** Test in model specs (milliseconds vs seconds).
+- **API endpoints.** Test with integration tests — no browser needed.
+- **Every edge case.** System tests for happy paths, unit tests for edge cases.
+- **CI with limited resources.** System tests are 10-100x slower. Keep the count low.
+
+## Speed Tips
+
+- Use `headless_chrome` (no GUI overhead)
+- Minimize `sleep` calls — rely on Capybara's auto-waiting
+- Share login state across tests in the same class (use `setup`)
+- Keep system test count under 50 for fast CI