rubyn-code 0.1.0

data/skills/minitest/integration_tests.md

@@ -0,0 +1,210 @@
+# Minitest: Integration Tests (Controllers)
+
+## Pattern
+
+Rails integration tests (`ActionDispatch::IntegrationTest`) test the full request/response cycle — routing, middleware, authentication, controller action, and response. They're the Minitest equivalent of RSpec request specs.
+
+```ruby
+# test/controllers/orders_controller_test.rb
+class OrdersControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:alice)
+    @order = orders(:pending_order)
+    sign_in @user
+  end
+
+  # INDEX
+  test "index returns success" do
+    get orders_path
+
+    assert_response :success
+  end
+
+  test "index shows only current user's orders" do
+    get orders_path
+
+    assert_match @order.reference, response.body
+    assert_no_match orders(:bobs_order).reference, response.body
+  end
+
+  # SHOW
+  test "show returns the order" do
+    get order_path(@order)
+
+    assert_response :success
+    assert_match @order.reference, response.body
+  end
+
+  test "show returns not found for another user's order" do
+    assert_raises ActiveRecord::RecordNotFound do
+      get order_path(orders(:bobs_order))
+    end
+  end
+
+  # CREATE
+  test "create with valid params" do
+    assert_difference "Order.count", 1 do
+      post orders_path, params: {
+        order: {
+          shipping_address: "789 Elm St",
+          line_items_attributes: [
+            { product_id: products(:widget).id, quantity: 2 }
+          ]
+        }
+      }
+    end
+
+    assert_redirected_to Order.last
+    follow_redirect!
+    assert_match "Order placed", response.body
+  end
+
+  test "create with invalid params renders new" do
+    assert_no_difference "Order.count" do
+      post orders_path, params: { order: { shipping_address: "" } }
+    end
+
+    assert_response :unprocessable_entity
+  end
+
+  test "create sends confirmation email" do
+    assert_emails 1 do
+      post orders_path, params: {
+        order: { shipping_address: "789 Elm", line_items_attributes: [{ product_id: products(:widget).id, quantity: 1 }] }
+      }
+    end
+  end
+
+  # UPDATE
+  test "update changes the order" do
+    patch order_path(@order), params: { order: { shipping_address: "New Address" } }
+
+    assert_redirected_to @order
+    assert_equal "New Address", @order.reload.shipping_address
+  end
+
+  # DESTROY
+  test "destroy removes the order" do
+    assert_difference "Order.count", -1 do
+      delete order_path(@order)
+    end
+
+    assert_redirected_to orders_path
+  end
+
+  # AUTH
+  test "redirects unauthenticated users" do
+    sign_out
+    get orders_path
+
+    assert_redirected_to login_path
+  end
+
+  private
+
+  def sign_in(user)
+    post login_path, params: { email: user.email, password: "password" }
+  end
+
+  def sign_out
+    delete logout_path
+  end
+end
+```
+
+### JSON API Tests
+
+```ruby
+# test/controllers/api/v1/orders_controller_test.rb
+class Api::V1::OrdersControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:alice)
+    @api_key = api_keys(:alice_key)
+  end
+
+  test "index returns JSON" do
+    get api_v1_orders_path, headers: auth_headers
+
+    assert_response :success
+    json = JSON.parse(response.body)
+    assert_kind_of Array, json["orders"]
+    assert_equal @user.orders.count, json["orders"].length
+  end
+
+  test "create returns 201" do
+    assert_difference "Order.count", 1 do
+      post api_v1_orders_path,
+           params: { order: { shipping_address: "123 Main" } }.to_json,
+           headers: auth_headers.merge("Content-Type" => "application/json")
+    end
+
+    assert_response :created
+    json = JSON.parse(response.body)
+    assert json["order"]["id"].present?
+    assert_equal "pending", json["order"]["status"]
+  end
+
+  test "returns 401 without API key" do
+    get api_v1_orders_path
+
+    assert_response :unauthorized
+  end
+
+  test "returns 401 with revoked API key" do
+    @api_key.update!(revoked_at: 1.hour.ago)
+
+    get api_v1_orders_path, headers: auth_headers
+
+    assert_response :unauthorized
+  end
+
+  private
+
+  def auth_headers
+    { "Authorization" => "Bearer #{@api_key.raw_key}" }
+  end
+end
+```
+
+## Why This Is Good
+
+- **Full stack testing.** Routes, middleware, auth, params parsing, the action, and the response — all exercised in one test. If the route is broken or auth is misconfigured, the test catches it.
+- **`assert_difference` is atomic.** Captures count before, runs the block, checks count after. Cleaner than manual before/after variables.
+- **`assert_emails` and `assert_enqueued_jobs` verify side effects.** No need to mock mailers or job queues — assert that the right things were enqueued.
+- **`follow_redirect!` tests the full flow.** Create → redirect → show page with flash message. One test verifies the entire user journey.
+
+## Anti-Pattern
+
+Testing controller internals instead of HTTP behavior:
+
+```ruby
+# BAD: Testing instance variables (don't exist in integration tests)
+test "assigns orders" do
+  get orders_path
+  assert_equal Order.all, assigns(:orders)  # assigns doesn't work in integration tests
+end
+
+# BAD: Testing which template rendered (implementation detail)
+test "renders index template" do
+  get orders_path
+  assert_template :index  # Deprecated in integration tests
+end
+```
+
+## When To Apply
+
+- **Every controller endpoint gets integration tests.** Happy path, validation failure, auth checks, and authorization for each action.
+- **Test what the user experiences.** Status codes, redirects, response body content, flash messages — not internal state.
+- **Prefer `assert_response` + `assert_match` over template assertions.** Test the output, not the mechanism.
+
+## Key Differences from RSpec Request Specs
+
+| Minitest | RSpec |
+|---|---|
+| `assert_response :success` | `expect(response).to have_http_status(:ok)` |
+| `assert_difference "Order.count", 1 do` | `expect { ... }.to change(Order, :count).by(1)` |
+| `assert_redirected_to path` | `expect(response).to redirect_to(path)` |
+| `assert_emails 1 do` | `expect { ... }.to have_enqueued_mail.once` |
+| `JSON.parse(response.body)` | `JSON.parse(response.body)` (same) |
+| `setup do` | `before do` |
+| `fixtures :all` | `let(:user) { create(:user) }` |

data/skills/minitest/mailers_and_jobs.md

@@ -0,0 +1,218 @@
+# Minitest: Testing Mailers and Background Jobs
+
+## Pattern
+
+Test mailers and jobs as first-class citizens. Mailer tests verify the email content and recipients. Job tests verify the job logic in isolation. Integration tests verify that actions enqueue the right jobs and emails.
+
+### Testing Mailers
+
+```ruby
+# test/mailers/order_mailer_test.rb
+require "test_helper"
+
+class OrderMailerTest < ActionMailer::TestCase
+  test "confirmation email" do
+    order = orders(:pending_order)
+    email = OrderMailer.confirmation(order)
+
+    # Verify envelope
+    assert_equal ["noreply@rubyn.ai"], email.from
+    assert_equal [order.user.email], email.to
+    assert_equal "Order #{order.reference} Confirmed", email.subject
+
+    # Verify body content
+    assert_match order.reference, email.body.encoded
+    assert_match "$#{format('%.2f', order.total / 100.0)}", email.body.encoded
+    assert_match order.shipping_address, email.body.encoded
+  end
+
+  test "shipped email includes tracking" do
+    order = orders(:shipped_order)
+    order.update!(tracking_number: "1Z999AA10123456784")
+
+    email = OrderMailer.shipped(order)
+
+    assert_equal "Your order has shipped!", email.subject
+    assert_match "1Z999AA10123456784", email.body.encoded
+  end
+
+  test "does not send to unconfirmed users" do
+    user = users(:alice)
+    user.update!(confirmed_at: nil)
+    order = orders(:pending_order)
+
+    email = OrderMailer.confirmation(order)
+
+    # Mailer returns a null mail object
+    assert_nil email.to
+  end
+end
+```
+
+### Testing Background Jobs
+
+```ruby
+# test/jobs/order_confirmation_job_test.rb
+require "test_helper"
+
+class OrderConfirmationJobTest < ActiveJob::TestCase
+  test "sends confirmation email" do
+    order = orders(:pending_order)
+
+    assert_emails 1 do
+      OrderConfirmationJob.perform_now(order.id)
+    end
+  end
+
+  test "marks order as confirmation sent" do
+    order = orders(:pending_order)
+    assert_nil order.confirmation_sent_at
+
+    OrderConfirmationJob.perform_now(order.id)
+
+    assert_not_nil order.reload.confirmation_sent_at
+  end
+
+  test "is idempotent — skips if already sent" do
+    order = orders(:pending_order)
+    order.update!(confirmation_sent_at: 1.hour.ago)
+
+    assert_no_emails do
+      OrderConfirmationJob.perform_now(order.id)
+    end
+  end
+
+  test "handles missing order gracefully" do
+    assert_nothing_raised do
+      OrderConfirmationJob.perform_now(999_999)
+    end
+  end
+end
+```
+
+```ruby
+# test/jobs/codebase_index_job_test.rb
+require "test_helper"
+
+class CodebaseIndexJobTest < ActiveJob::TestCase
+  setup do
+    @project = projects(:rubyn_project)
+    @fake_embedder = FakeEmbedder.new
+  end
+
+  test "creates embeddings for project files" do
+    files = { "app/models/order.rb" => "class Order; end" }
+
+    Embeddings::CodebaseIndexer.stub(:new, ->(**) { MockIndexer.new }) do
+      assert_difference "@project.code_embeddings.count" do
+        CodebaseIndexJob.perform_now(@project.id, files)
+      end
+    end
+  end
+
+  test "updates project indexed_at timestamp" do
+    CodebaseIndexJob.perform_now(@project.id, {})
+
+    assert_not_nil @project.reload.last_indexed_at
+  end
+end
+```
+
+### Asserting Jobs are Enqueued
+
+```ruby
+# test/controllers/orders_controller_test.rb
+class OrdersControllerTest < ActionDispatch::IntegrationTest
+  test "create enqueues confirmation job" do
+    sign_in users(:alice)
+
+    assert_enqueued_with(job: OrderConfirmationJob) do
+      post orders_path, params: { order: valid_params }
+    end
+  end
+
+  test "create enqueues indexing job" do
+    sign_in users(:alice)
+
+    assert_enqueued_with(job: CodebaseIndexJob) do
+      post orders_path, params: { order: valid_params }
+    end
+  end
+
+  test "does not enqueue job on validation failure" do
+    sign_in users(:alice)
+
+    assert_no_enqueued_jobs do
+      post orders_path, params: { order: { shipping_address: "" } }
+    end
+  end
+end
+```
+
+### Testing Job Retries and Error Handling
+
+```ruby
+class WebhookDeliveryJobTest < ActiveJob::TestCase
+  test "retries on timeout" do
+    stub_request(:post, "https://webhook.example.com/hook")
+      .to_timeout
+      .then
+      .to_return(status: 200)
+
+    # perform_now doesn't retry — test the logic directly
+    webhook = webhooks(:order_created)
+
+    assert_raises Faraday::TimeoutError do
+      WebhookDeliveryJob.perform_now(webhook.id)
+    end
+  end
+
+  test "discards on 4xx client error" do
+    stub_request(:post, "https://webhook.example.com/hook")
+      .to_return(status: 404)
+
+    webhook = webhooks(:order_created)
+
+    # Job should not raise — it handles 4xx gracefully
+    assert_nothing_raised do
+      WebhookDeliveryJob.perform_now(webhook.id)
+    end
+
+    assert_equal "failed", webhook.reload.status
+  end
+end
+```
+
+### Performing Enqueued Jobs in Tests
+
+```ruby
+# When you need to run enqueued jobs as part of a test
+class OrderWorkflowTest < ActiveSupport::TestCase
+  test "full order workflow with jobs" do
+    user = users(:alice)
+
+    # perform_enqueued_jobs runs all jobs enqueued within the block
+    perform_enqueued_jobs do
+      result = Orders::CreateService.call(valid_params, user)
+      assert result.success?
+    end
+
+    # After jobs run, verify side effects
+    order = Order.last
+    assert_not_nil order.confirmation_sent_at
+    assert_equal 1, ActionMailer::Base.deliveries.count
+  end
+end
+```
+
+## Job Assertion Cheat Sheet
+
+| Want to check... | Use |
+|---|---|
+| A specific job was enqueued | `assert_enqueued_with(job: MyJob, args: [...]) { code }` |
+| Any job was enqueued | `assert_enqueued_jobs 1 { code }` |
+| No jobs were enqueued | `assert_no_enqueued_jobs { code }` |
+| An email was sent | `assert_emails 1 { code }` |
+| No emails were sent | `assert_no_emails { code }` |
+| Run enqueued jobs | `perform_enqueued_jobs { code }` |
+| Job runs without error | `assert_nothing_raised { MyJob.perform_now(args) }` |

data/skills/minitest/mocking_stubbing.md

@@ -0,0 +1,202 @@
+# Minitest: Mocking and Stubbing
+
+## Pattern
+
+Minitest includes `Minitest::Mock` for mocking and Ruby's `Object#stub` for stubbing. For more complex needs, use the `mocha` gem. Stub external dependencies, mock to verify interactions, and prefer dependency injection over global patching.
+
+### Built-in Minitest::Mock
+
+```ruby
+class AiCompletionServiceTest < ActiveSupport::TestCase
+  test "calls the client with correct params" do
+    mock_client = Minitest::Mock.new
+    mock_client.expect(:complete, mock_response, [Array], model: String, max_tokens: Integer)
+
+    service = Ai::CompletionService.new(client: mock_client)
+    service.call("Refactor this code", context: "You are Rubyn.")
+
+    mock_client.verify  # Raises if .complete wasn't called with expected args
+  end
+
+  test "returns content from response" do
+    mock_client = Minitest::Mock.new
+    mock_client.expect(:complete, mock_response, [Array], model: String, max_tokens: Integer)
+
+    service = Ai::CompletionService.new(client: mock_client)
+    result = service.call("Refactor this code", context: "You are Rubyn.")
+
+    assert_equal "Here is your refactored code", result.content
+  end
+
+  private
+
+  def mock_response
+    OpenStruct.new(
+      content: "Here is your refactored code",
+      input_tokens: 500,
+      output_tokens: 200
+    )
+  end
+end
+```
+
+### Object#stub (built into Minitest)
+
+```ruby
+class OrderTest < ActiveSupport::TestCase
+  test "sends confirmation after creation" do
+    # Stub the mailer to verify it's called
+    OrderMailer.stub(:confirmation, mock_mail) do
+      Orders::CreateService.call(valid_params, users(:alice))
+    end
+  end
+
+  test "external API failure doesn't crash order creation" do
+    WarehouseApi.stub(:notify, ->(*) { raise Faraday::TimeoutError }) do
+      # The service should handle the error gracefully
+      result = Orders::CreateService.call(valid_params, users(:alice))
+      assert result.success?
+    end
+  end
+
+  private
+
+  def mock_mail
+    mock = Minitest::Mock.new
+    mock.expect(:deliver_later, true)
+    mock
+  end
+end
+```
+
+### Mocha Gem (for more expressive mocking)
+
+```ruby
+# Gemfile
+group :test do
+  gem "mocha"
+end
+
+# test/test_helper.rb
+require "mocha/minitest"
+```
+
+```ruby
+class OrdersCreateServiceTest < ActiveSupport::TestCase
+  test "sends confirmation email" do
+    OrderMailer.expects(:confirmation).with(instance_of(Order)).returns(stub(deliver_later: true))
+
+    Orders::CreateService.call(valid_params, users(:alice))
+  end
+
+  test "deducts credits from user" do
+    user = users(:alice)
+    user.expects(:deduct_credits!).with(1).once
+
+    Credits::DeductionService.call(user: user, credits: 1)
+  end
+
+  test "does not send email when save fails" do
+    OrderMailer.expects(:confirmation).never
+
+    Orders::CreateService.call(invalid_params, users(:alice))
+  end
+
+  test "retries on timeout" do
+    client = stub("ai_client")
+    client.stubs(:complete)
+          .raises(Faraday::TimeoutError).then
+          .raises(Faraday::TimeoutError).then
+          .returns(mock_response)
+
+    service = Ai::CompletionService.new(client: client)
+    result = service.call("test prompt", context: "test")
+
+    assert_equal "response content", result.content
+  end
+end
+```
+
+### WebMock for HTTP Stubbing
+
+```ruby
+# test/test_helper.rb
+require "webmock/minitest"
+
+class ActiveSupport::TestCase
+  # Disable real HTTP connections in tests
+  WebMock.disable_net_connect!(allow_localhost: true)
+end
+```
+
+```ruby
+class EmbeddingClientTest < ActiveSupport::TestCase
+  setup do
+    stub_request(:post, "http://localhost:8000/embed")
+      .with(body: hash_including("texts"))
+      .to_return(
+        status: 200,
+        body: { embeddings: [[0.1, 0.2, 0.3]], dimensions: 1024, count: 1 }.to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+  end
+
+  test "returns embeddings from the service" do
+    client = Embeddings::HttpClient.new(base_url: "http://localhost:8000")
+    result = client.embed(["def hello; end"])
+
+    assert_equal 3, result.first.length
+    assert_kind_of Float, result.first.first
+  end
+
+  test "raises on server error" do
+    stub_request(:post, "http://localhost:8000/embed")
+      .to_return(status: 500, body: "Internal Server Error")
+
+    client = Embeddings::HttpClient.new(base_url: "http://localhost:8000")
+
+    assert_raises Embeddings::ServerError do
+      client.embed(["test"])
+    end
+  end
+end
+```
+
+## Why This Is Good
+
+- **`Minitest::Mock#verify` catches missing calls.** If the mock expected `.complete` to be called and it wasn't, the test fails. No silent passes.
+- **`Object#stub` is temporary.** The stub only applies within the block. After the block, the original method is restored. No test pollution.
+- **WebMock prevents real HTTP.** Accidental HTTP calls in tests fail immediately instead of silently hitting real APIs.
+- **Mocha's `.expects` is expressive.** `.expects(:method).with(args).returns(value).once` reads clearly and verifies the interaction.
+
+## Anti-Pattern
+
+Over-mocking or mocking the object under test:
+
+```ruby
+# BAD: Mocking the thing you're testing
+test "calculates total" do
+  order = orders(:pending_order)
+  order.stubs(:line_items).returns([
+    stub(quantity: 2, unit_price: 10_00),
+    stub(quantity: 1, unit_price: 25_00)
+  ])
+
+  assert_equal 45_00, order.total
+  # You're testing that .sum works on stubs, not that order.total works
+end
+```
+
+## Minitest Mock vs Mocha Comparison
+
+| Feature | Minitest::Mock | Mocha |
+|---|---|---|
+| Setup | Built-in | `gem "mocha"` |
+| Expect call | `mock.expect(:method, return, [args])` | `obj.expects(:method).with(args).returns(val)` |
+| Stub | `object.stub(:method, return) { block }` | `obj.stubs(:method).returns(val)` |
+| Verify | `mock.verify` (manual) | Automatic at test end |
+| Sequence | Not built in | `sequence = sequence("name")` |
+| Any instance | Not built in | `Order.any_instance.stubs(:save)` |
+| Expressiveness | Minimal | Rich (`.once`, `.never`, `.at_least_once`) |
+
+Use built-in mocks for simple cases. Use Mocha when you need `.expects`, `.never`, sequences, or `any_instance`.