rubyn-code 0.1.0

data/skills/rails/testing_strategy.md

@@ -0,0 +1,258 @@
+# Rails: Testing Strategy (What to Test Where)
+
+## Pattern
+
+Test each layer of your Rails app at the right level of abstraction. Unit tests for logic, integration tests for HTTP, system tests for user journeys. The pyramid: many unit tests, fewer integration tests, few system tests.
+
+### The Testing Pyramid for Rails
+
+```
+        /  System Tests  \        ← 10-30 tests: Critical user journeys (browser)
+       / Integration Tests \      ← 50-200 tests: Every endpoint (HTTP)
+      /    Service Specs    \     ← 50-200 tests: Business logic (Ruby)
+     /     Model Specs       \    ← 100-500 tests: Validations, scopes, methods
+    /   Factories + Fixtures   \  ← Support: Test data infrastructure
+```
+
+### What to Test at Each Layer
+
+#### Models — Validations, Scopes, Instance Methods
+
+```ruby
+# spec/models/order_spec.rb (RSpec) or test/models/order_test.rb (Minitest)
+# Test: validations, scopes, calculated fields, state predicates
+# Don't test: associations (Rails tests these), framework behavior
+
+# Validations
+it "requires shipping address" do
+  order = build(:order, shipping_address: nil)
+  expect(order).not_to be_valid
+  expect(order.errors[:shipping_address]).to include("can't be blank")
+end
+
+# Scopes — need database records
+describe ".recent" do
+  let!(:new_order) { create(:order, created_at: 1.day.ago) }
+  let!(:old_order) { create(:order, created_at: 60.days.ago) }
+
+  it "returns orders from the last 30 days" do
+    expect(Order.recent).to include(new_order)
+    expect(Order.recent).not_to include(old_order)
+  end
+end
+
+# Instance methods — prefer build_stubbed
+describe "#total" do
+  it "sums line item amounts" do
+    order = build_stubbed(:order)
+    allow(order).to receive(:line_items).and_return([
+      build_stubbed(:line_item, quantity: 2, unit_price: 10_00),
+      build_stubbed(:line_item, quantity: 1, unit_price: 25_00)
+    ])
+    expect(order.total).to eq(45_00)
+  end
+end
+```
+
+#### Service Objects — Business Logic
+
+```ruby
+# spec/services/orders/create_service_spec.rb
+# Test: success/failure paths, side effects, error handling
+# Don't test: HTTP (that's integration tests), rendering
+
+describe Orders::CreateService do
+  let(:user) { create(:user) }
+
+  it "creates an order and enqueues confirmation" do
+    result = described_class.call(valid_params, user)
+
+    expect(result).to be_success
+    expect(result.order).to be_persisted
+    expect(OrderConfirmationJob).to have_been_enqueued.with(result.order.id)
+  end
+
+  it "returns failure for invalid params" do
+    result = described_class.call({ shipping_address: "" }, user)
+
+    expect(result).to be_failure
+    expect(result.error).to include("Shipping address")
+  end
+
+  it "does not enqueue jobs on failure" do
+    described_class.call({ shipping_address: "" }, user)
+    expect(OrderConfirmationJob).not_to have_been_enqueued
+  end
+end
+```
+
+#### Controllers / Endpoints — HTTP Integration
+
+```ruby
+# spec/requests/orders_spec.rb
+# Test: status codes, redirects, response body, authentication, authorization
+# Don't test: business logic (that's in service specs)
+
+describe "POST /orders" do
+  let(:user) { create(:user) }
+  before { sign_in user }
+
+  context "with valid params" do
+    it "creates and redirects" do
+      expect {
+        post orders_path, params: { order: valid_params }
+      }.to change(Order, :count).by(1)
+
+      expect(response).to redirect_to(Order.last)
+    end
+  end
+
+  context "with invalid params" do
+    it "renders form with errors" do
+      post orders_path, params: { order: { shipping_address: "" } }
+      expect(response).to have_http_status(:unprocessable_entity)
+    end
+  end
+
+  context "without authentication" do
+    before { sign_out }
+
+    it "redirects to login" do
+      post orders_path, params: { order: valid_params }
+      expect(response).to redirect_to(new_user_session_path)
+    end
+  end
+end
+```
+
+#### API Endpoints — JSON Integration
+
+```ruby
+# spec/requests/api/v1/orders_spec.rb
+describe "GET /api/v1/orders" do
+  let(:user) { create(:user) }
+  let(:headers) { auth_headers(user) }
+
+  it "returns orders as JSON" do
+    create_list(:order, 3, user: user)
+
+    get "/api/v1/orders", headers: headers
+
+    expect(response).to have_http_status(:ok)
+    json = JSON.parse(response.body)
+    expect(json["orders"].length).to eq(3)
+    expect(json["orders"].first).to include("id", "reference", "status")
+    expect(json["orders"].first).not_to include("password_digest", "api_cost_usd")
+  end
+end
+```
+
+#### Mailers — Content and Delivery
+
+```ruby
+# spec/mailers/order_mailer_spec.rb
+# Test: recipients, subject, body content
+# Don't test: delivery mechanism (Rails handles that)
+
+describe OrderMailer do
+  describe "#confirmation" do
+    let(:order) { build_stubbed(:order, reference: "ORD-001") }
+    let(:mail) { described_class.confirmation(order) }
+
+    it "sends to the order's user" do
+      expect(mail.to).to eq([order.user.email])
+    end
+
+    it "includes the order reference" do
+      expect(mail.body.encoded).to include("ORD-001")
+    end
+  end
+end
+```
+
+#### Jobs — Logic and Idempotency
+
+```ruby
+# spec/jobs/order_confirmation_job_spec.rb
+# Test: the job's perform logic, idempotency, error handling
+# Don't test: that ActiveJob works (framework responsibility)
+
+describe OrderConfirmationJob do
+  let(:order) { create(:order) }
+
+  it "sends confirmation email" do
+    expect { described_class.perform_now(order.id) }
+      .to change { ActionMailer::Base.deliveries.count }.by(1)
+  end
+
+  it "is idempotent" do
+    order.update!(confirmation_sent_at: 1.hour.ago)
+
+    expect { described_class.perform_now(order.id) }
+      .not_to change { ActionMailer::Base.deliveries.count }
+  end
+end
+```
+
+#### System Tests — User Journeys (Few, Critical)
+
+```ruby
+# spec/system/checkout_spec.rb
+# Test: full user journey through the browser
+# Don't test: every edge case (that's model + service specs)
+
+it "places an order from the product page" do
+  sign_in create(:user)
+  visit products_path
+
+  click_button "Add to Cart"
+  click_link "Checkout"
+  fill_in "Shipping address", with: "123 Main St"
+  click_button "Place Order"
+
+  expect(page).to have_content("Order placed")
+end
+```
+
+### What NOT to Test
+
+```ruby
+# DON'T test framework behavior
+it "has many line items" do
+  expect(Order.reflect_on_association(:line_items).macro).to eq(:has_many)
+end
+# Rails already tests that has_many works. Test the behavior, not the declaration.
+
+# DON'T test trivial methods
+it "returns the name" do
+  user = build(:user, name: "Alice")
+  expect(user.name).to eq("Alice")
+end
+# This tests that attr_reader works. It always works.
+
+# DON'T test private methods directly
+it "builds the cache key" do
+  expect(service.send(:build_cache_key, order)).to eq("orders:42")
+end
+# Test through the public interface. If the private method matters, it'll affect the output.
+```
+
+### Speed Budget
+
+| Layer | Target per test | Count target | Total time target |
+|---|---|---|---|
+| Model specs | 1-5ms | 100-500 | < 5 seconds |
+| Service specs | 5-20ms | 50-200 | < 5 seconds |
+| Request specs | 10-50ms | 50-200 | < 10 seconds |
+| Mailer specs | 5-10ms | 10-30 | < 1 second |
+| Job specs | 5-20ms | 10-50 | < 2 seconds |
+| System specs | 1-5s | 10-30 | < 60 seconds |
+| **Full suite** | | **300-1000** | **< 90 seconds** |
+
+If your suite exceeds these targets, profile with `--profile` and optimize the slowest tests first. The usual culprits: unnecessary `create` calls, missing `build_stubbed`, system tests that should be request tests.
+
+## Why This Matters
+
+Testing at the wrong layer wastes time. A validation test in a system spec takes 2 seconds. In a model spec, 2 milliseconds. That's a 1000x difference. Multiply by 100 tests and it's the difference between a 3-second suite and a 3-minute suite.
+
+Test logic where it lives. Test HTTP at the HTTP layer. Test UI only for the critical paths.

data/skills/rails/validations.md

@@ -0,0 +1,206 @@
+# Rails: Validations
+
+## Pattern
+
+Keep validations on the model for data integrity rules that must always be enforced. Use custom validators for complex or reusable validation logic. Use form objects for context-specific validations that only apply in certain flows.
+
+```ruby
+class User < ApplicationRecord
+  # Simple, always-enforced validations
+  validates :email, presence: true,
+                    uniqueness: { case_sensitive: false },
+                    format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :name, presence: true, length: { maximum: 100 }
+  validates :role, inclusion: { in: %w[user admin] }
+
+  # Normalize before validating
+  before_validation :normalize_email
+
+  private
+
+  def normalize_email
+    self.email = email&.downcase&.strip
+  end
+end
+```
+
+```ruby
+class Order < ApplicationRecord
+  validates :shipping_address, presence: true
+  validates :total, numericality: { greater_than_or_equal_to: 0 }
+  validates :status, inclusion: { in: %w[pending confirmed shipped delivered cancelled] }
+
+  # Custom validation method for complex business rules
+  validate :line_items_must_be_present, on: :create
+  validate :total_matches_line_items, on: :create
+
+  private
+
+  def line_items_must_be_present
+    errors.add(:base, "Order must have at least one item") if line_items.empty?
+  end
+
+  def total_matches_line_items
+    expected = line_items.sum { |li| li.quantity * li.unit_price }
+    errors.add(:total, "doesn't match line items") unless total == expected
+  end
+end
+```
+
+Custom validator class for reusable validations:
+
+```ruby
+# app/validators/url_validator.rb
+class UrlValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if value.blank?
+
+    uri = URI.parse(value)
+    unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+      record.errors.add(attribute, options[:message] || "must be a valid URL")
+    end
+  rescue URI::InvalidURIError
+    record.errors.add(attribute, options[:message] || "must be a valid URL")
+  end
+end
+
+# Usage in any model
+class Company < ApplicationRecord
+  validates :website, url: true
+  validates :blog_url, url: { message: "must be a valid blog URL" }, allow_blank: true
+end
+```
+
+## Why This Is Good
+
+- **Data integrity at the model level.** No matter how a User is created (form, API, console, seed, test), the email will be present, unique, and formatted correctly. This is the last line of defense before the database.
+- **Normalized before validation.** Downcasing the email before validating uniqueness prevents "Alice@Example.com" and "alice@example.com" from being treated as different emails.
+- **Custom validator classes are reusable.** `UrlValidator` works on any model, any attribute. Write it once, use it everywhere with `validates :field, url: true`.
+- **`on: :create` limits when validation runs.** Line items must be present when creating an order, but updating the shipping address later shouldn't fail because you didn't re-validate line items.
+- **Errors are specific and attributable.** `errors.add(:total, "doesn't match")` ties the error to the field, enabling per-field error display in forms.
+
+## Anti-Pattern
+
+Scattering validations across callbacks, controllers, and duplicating database constraints:
+
+```ruby
+class User < ApplicationRecord
+  validates :email, presence: true
+
+  before_save :check_email_format
+  after_validation :verify_email_dns
+  before_create :ensure_unique_email
+
+  private
+
+  def check_email_format
+    unless email =~ /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+      errors.add(:email, "format is invalid")
+      throw(:abort)
+    end
+  end
+
+  def verify_email_dns
+    # Slow DNS lookup on every validation
+    domain = email.split("@").last
+    unless Resolv::DNS.new.getresources(domain, Resolv::DNS::Resource::IN::MX).any?
+      errors.add(:email, "domain doesn't accept email")
+    end
+  end
+
+  def ensure_unique_email
+    if User.exists?(email: email)
+      errors.add(:email, "already taken")
+      throw(:abort)
+    end
+  end
+end
+```
+
+```ruby
+# Also in the controller — duplicating model validation
+class UsersController < ApplicationController
+  def create
+    if params[:user][:email].blank?
+      flash[:error] = "Email is required"
+      render :new and return
+    end
+
+    unless params[:user][:email] =~ /\A[\w+\-.]+@/
+      flash[:error] = "Email format is invalid"
+      render :new and return
+    end
+
+    @user = User.new(user_params)
+    # ...
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Validation split across callbacks.** `before_save`, `after_validation`, and `before_create` all check the email. A developer reading the model has to trace through 3 callbacks to understand the full validation story. All of this belongs in `validates` declarations.
+- **`throw(:abort)` in callbacks.** This halts the save silently. The caller gets `false` from `save` but the error might not be on the errors object if the throw happens in `before_save` after validation already passed.
+- **DNS lookup on every validation.** Every `valid?` call triggers a network request. This slows tests, breaks offline development, and adds a failure mode to every form submission.
+- **Race condition in `ensure_unique_email`.** Between the `exists?` check and the `save`, another request can create the same email. Use a `validates :email, uniqueness: true` plus a database unique index for real protection.
+- **Duplicated validation in the controller.** The controller checks email presence and format, then the model checks again. When the rules change, you update one place and forget the other.
+
+## When To Apply
+
+- **Model validations for invariants.** Rules that must ALWAYS be true: email format, presence of required fields, numericality, inclusion in allowed values, uniqueness.
+- **Custom validator classes for reusable rules.** URL format, phone number format, postal code format — anything used across multiple models.
+- **`validate` methods for complex business rules** that involve relationships between attributes or associated records.
+- **Always back uniqueness validations with a database unique index.** The validation provides a nice error message; the index prevents race conditions.
+
+## When NOT To Apply
+
+- **Don't validate in controllers.** The model is the single source of truth for data validity. Controllers check the result of `save`/`valid?` and respond accordingly.
+- **Don't use `validates_associated` carelessly.** It validates every associated record on every save, which can cascade into slow, unexpected validation chains.
+- **Don't put context-specific validations on the model.** If a field is required during registration but not during profile update, use a form object — not `validates :field, presence: true, on: :create`.
+- **Don't validate external data in model validations.** DNS lookups, API calls, and other network requests don't belong in validations. They're slow, unreliable, and break tests.
+
+## Edge Cases
+
+**Conditional validations — `if:` and `unless:`:**
+Use sparingly. A few conditional validations are fine. If the model has 5+ conditions, that's a sign you need form objects for different contexts.
+
+```ruby
+validates :shipping_address, presence: true, unless: :digital_product?
+validates :download_url, presence: true, if: :digital_product?
+```
+
+**Validation contexts (`:on`):**
+Built-in contexts are `:create` and `:update`. You can define custom contexts, but form objects are usually cleaner:
+
+```ruby
+# Model with custom context
+validates :terms, acceptance: true, on: :registration
+
+# Triggered explicitly
+user.valid?(:registration)
+
+# Better: use a form object instead
+class RegistrationForm
+  validates :terms, acceptance: true
+end
+```
+
+**Database constraints as backup:**
+Model validations provide user-friendly errors. Database constraints prevent data corruption. Use both:
+
+```ruby
+# Migration
+add_index :users, :email, unique: true
+change_column_null :users, :email, false
+
+# Model
+validates :email, presence: true, uniqueness: true
+```
+
+**`errors.add` to `:base` vs to an attribute:**
+Add to `:base` when the error isn't attributable to a single field. Add to the attribute when it is.
+
+```ruby
+errors.add(:base, "Order total exceeds credit limit")  # Cross-field concern
+errors.add(:email, "is already registered")              # Single field concern
+```