anima-core 0.2.1 → 1.0.0

data/skills/rspec/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: rspec
+description: "RSpec testing with FactoryBot — matchers, test doubles, shared examples. Activate when writing specs, fixing failing tests, working with describe/it/expect blocks, editing *_spec.rb files, planning test strategy, or discussing unit/integration tests."
+---
+
+# RSpec Testing
+
+This skill provides comprehensive guidance for writing effective RSpec tests in Ruby and Rails applications. Use for writing new specs, fixing failing tests, understanding matchers, using test doubles, and following RSpec best practices.
+
+## Quick Reference
+
+### Basic Structure
+
+```ruby
+RSpec.describe Order do
+  subject(:order) { described_class.new(items) }
+  let(:items) { [item1, item2] }
+  let(:item1) { double("item", price: 10) }
+  let(:item2) { double("item", price: 20) }
+
+  describe "#total" do
+    it "sums item prices" do
+      expect(order.total).to eq(30)
+    end
+  end
+
+  context "with discount" do
+    let(:order) { described_class.new(items, discount: 5) }
+
+    it "applies discount" do
+      expect(order.total).to eq(25)
+    end
+  end
+end
+```
+
+### Key Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| `describe` / `context` | Group related examples |
+| `it` / `specify` | Define individual test cases |
+| `let` | Lazy-evaluated, memoized helper |
+| `let!` | Eager-evaluated helper (runs before each example) |
+| `subject` | Primary object under test |
+| `before` / `after` | Setup and teardown hooks |
+| `expect` | Make assertions |
+
+## Writing Good Specs
+
+### Use Named Subject for Method Tests
+
+```ruby
+describe "#calculate_total" do
+  subject(:total) { order.calculate_total }
+
+  it "returns sum of items" do
+    expect(total).to eq(100)
+  end
+end
+```
+
+### Context Blocks for Different States
+
+```ruby
+describe "#withdraw" do
+  context "with sufficient funds" do
+    let(:account) { build(:account, balance: 100) }
+
+    it "reduces balance" do
+      expect { account.withdraw(50) }.to change(account, :balance).by(-50)
+    end
+  end
+
+  context "with insufficient funds" do
+    let(:account) { build(:account, balance: 10) }
+
+    it "raises error" do
+      expect { account.withdraw(50) }.to raise_error(InsufficientFunds)
+    end
+  end
+end
+```
+
+## Common Matchers
+
+### Equality
+
+```ruby
+expect(x).to eq(y)          # ==
+expect(x).to eql(y)         # eql? (type-sensitive)
+expect(x).to be(y)          # equal? (identity)
+```
+
+### Truthiness
+
+```ruby
+expect(x).to be_truthy      # not nil or false
+expect(x).to be_falsey      # nil or false
+expect(x).to be_nil
+expect(x).to be true        # exactly true
+```
+
+### Comparisons
+
+```ruby
+expect(x).to be > 3
+expect(x).to be_between(1, 10).inclusive
+expect(x).to be_within(0.1).of(3.14)
+```
+
+### Collections
+
+```ruby
+expect(arr).to include(1, 2)
+expect(arr).to contain_exactly(3, 2, 1)  # order-independent
+expect(arr).to all(be_positive)
+expect(str).to start_with("hello")
+expect(hash).to have_key(:name)
+```
+
+### Changes
+
+```ruby
+expect { x += 1 }.to change { x }.by(1)
+expect { x += 1 }.to change { x }.from(0).to(1)
+expect { user.save }.to change(User, :count).by(1)
+```
+
+### Errors
+
+```ruby
+expect { raise "boom" }.to raise_error
+expect { raise ArgumentError, "bad" }.to raise_error(ArgumentError, /bad/)
+```
+
+### Predicates (Dynamic)
+
+```ruby
+expect([]).to be_empty      # [].empty?
+expect(user).to be_valid    # user.valid?
+expect(hash).to have_key(k) # hash.has_key?(k)
+```
+
+## Test Doubles
+
+### Types
+
+```ruby
+# Basic double (strict)
+user = double("user", name: "Bob")
+
+# Verifying doubles (recommended)
+user = instance_double("User", name: "Bob")  # validates instance methods
+api = class_double("Api", fetch: data)       # validates class methods
+logger = object_double(Rails.logger)         # validates object methods
+
+# Spy (null object for after-the-fact verification)
+notifier = spy("notifier")
+```
+
+### Stubbing
+
+```ruby
+allow(user).to receive(:name).and_return("Bob")
+allow(Api).to receive(:fetch).and_return(data)
+allow(obj).to receive(:method) { computed_value }
+```
+
+### Expectations
+
+```ruby
+expect(user).to receive(:save).and_return(true)
+expect(Api).to receive(:post).with(hash_including(id: 1))
+
+# Spy pattern (verify after action)
+notifier = spy("notifier")
+service.call(notifier)
+expect(notifier).to have_received(:notify).with("done")
+```
+
+### Argument Matchers
+
+```ruby
+expect(obj).to receive(:call).with(anything)
+expect(obj).to receive(:call).with(kind_of(Integer))
+expect(obj).to receive(:call).with(hash_including(a: 1))
+expect(obj).to receive(:call).with(array_including(1, 2))
+```
+
+## Rails Specs
+
+| Spec Type | Use For | Key Helpers |
+|-----------|---------|-------------|
+| `type: :model` | Business logic, scopes, validations | `build`, `create`, associations |
+| `type: :request` | Controller actions (preferred) | `get`, `post`, `response`, `have_http_status` |
+| `type: :system` | Browser/UI testing | `visit`, `fill_in`, `click_button`, `have_text` |
+| `type: :job` | Background jobs | `have_enqueued_job`, `perform_now` |
+| `type: :mailer` | Email delivery | `have_enqueued_mail`, `deliver_now` |
+| `type: :routing` | Route resolution | `route_to`, `be_routable` |
+
+See `examples/rails/` for complete spec templates.
+
+## Best Practices
+
+### Do
+
+- Use `described_class` instead of hardcoding class name
+- Use `let` for test data, `let!` when database records must exist before test
+- Use **named subject** when referencing in tests: `subject(:user) { ... }`
+- Use context blocks to organize different scenarios
+- Use verifying doubles (`instance_double`) over plain `double`
+- Name examples with verbs: `it "creates user"` not `it "should create user"`
+- Keep examples focused on one behavior
+- Use factories over fixtures for flexible test data
+- Prefer `build_stubbed` or `build` over `create` when database not needed
+
+### Don't
+
+- Don't use instance variables (`@user`) - use `let` for type safety
+- Don't use `before` just to trigger `let` evaluation - use `let!` instead:
+  ```ruby
+  # BAD - before just to initialize
+  let(:user) { create(:user) }
+  before { user }
+
+  # GOOD - let! for eager evaluation
+  let!(:user) { create(:user) }
+  ```
+  Use `before` for side-effects like `sign_in(user)` or `driven_by(:rack_test)`
+- Don't use `let!` when `let` suffices (wastes resources)
+- Don't test Rails framework (validations work, focus on business logic)
+- Don't stub the object under test
+- Avoid `any_instance_of` - prefer stubbing `ClassName.new` to return a double (see `references/mocks.md`)
+- Don't use `receive_message_chain` (violates Law of Demeter)
+- Don't write examples without descriptions
+- Shared examples work best for testing concerns across including classes. For unique behaviors, prefer repetition over abstraction
+
+### Factory Bot
+
+```ruby
+# Build strategies
+user = build(:user)              # In-memory, not persisted
+user = create(:user)             # Persisted to database
+user = build_stubbed(:user)      # Fake persisted (fastest)
+attrs = attributes_for(:user)    # Hash of attributes
+
+# With traits and attributes
+user = create(:user, :admin, :verified, name: "Bob")
+
+# Lists
+users = create_list(:user, 5, :admin)
+```
+
+**Strategy Selection**:
+- `build_stubbed` - Unit tests without database (fastest)
+- `build` - Validation tests, method tests
+- `create` - Database queries, scopes, associations
+- `attributes_for` - Controller params
+
+See `references/factory_bot.md` for traits, sequences, associations, and callbacks.
+
+## Configuration
+
+Essential settings for `spec_helper.rb` and `rails_helper.rb`:
+
+| Setting | Purpose |
+|---------|---------|
+| `verify_partial_doubles = true` | Validates stubbed methods exist |
+| `filter_run_when_matching :focus` | Run only focused specs (`fit`, `fdescribe`) |
+| `order = :random` | Randomize spec order to catch dependencies |
+| `use_transactional_fixtures = true` | Rollback database after each spec |
+| `infer_spec_type_from_file_location!` | Auto-detect spec type from path |
+
+See `examples/core/configuration.rb` for complete setup.
+
+## Before You Write
+
+**What are you about to do?**
+
+```
+├── Creating or modifying a factory?
+│   └── Read `references/factory_bot.md`
+│
+├── Writing a new spec file?
+│   ├── Model/service/PORO → Read `references/core.md`
+│   ├── Request/controller → Read `references/rails.md`
+│   └── System/feature/job/mailer → Read `references/rails.md`
+│
+├── Using test doubles, stubs, or mocks?
+│   └── Read `references/mocks.md`
+│
+├── Writing custom or complex matchers?
+│   └── Read `references/matchers.md`
+│
+└── Fixing a failing spec?
+    ├── Factory-related error → Read `references/factory_bot.md`
+    ├── Mock/stub error → Read `references/mocks.md`
+    ├── Matcher error → Read `references/matchers.md`
+    └── Rails-specific error → Read `references/rails.md`
+```
+
+**Need code examples?**
+
+```
+├── Basic spec structure, hooks, shared examples
+│   └── See `examples/core/`
+│
+├── Matcher usage patterns
+│   └── See `examples/matchers/`
+│
+├── Test doubles and stubbing
+│   └── See `examples/mocks/`
+│
+├── Rails spec templates (model, request, system, job, mailer)
+│   └── See `examples/rails/`
+│
+└── Factory definitions with traits and associations
+    └── See `examples/factory_bot/`
+```
+
+### Running Specs
+
+```bash
+rspec                           # all specs
+rspec spec/models               # directory
+rspec spec/user_spec.rb         # file
+rspec spec/user_spec.rb:23      # line
+rspec --format doc              # documentation format
+rspec --only-failures           # re-run failures
+rspec --profile 10              # show slowest
+```
+
+### Debugging
+
+```bash
+rspec --seed 12345              # reproduce random order
+rspec --fail-fast               # stop on first failure
+rspec --backtrace               # full backtrace
+```

data/skills/rspec/examples/core/basic_structure.rb

@@ -0,0 +1,69 @@
+# RSpec Core: Basic Structure Examples
+# Source: rspec-core gem features/example_groups/basic_structure.feature
+
+# Basic describe/context/it structure
+RSpec.describe Order do
+  context "with no items" do
+    let(:order) { build(:order) }
+
+    it "has zero total" do
+      expect(order.total).to eq(0)
+    end
+  end
+
+  context "with one item" do
+    let(:order) { build(:order) }
+    let(:item) { build(:item, price: 10) }
+
+    before { order.add_item(item) }
+
+    it "has item price as total" do
+      expect(order.total).to eq(10)
+    end
+  end
+end
+
+# Method-focused describe blocks
+RSpec.describe Calculator do
+  subject(:calculator) { build(:calculator) }
+
+  describe "#add" do
+    subject(:result) { calculator.add(2, 3) }
+
+    it "sums two numbers" do
+      expect(result).to eq(5)
+    end
+  end
+
+  describe ".from_string" do
+    subject(:calc) { described_class.from_string("2+3") }
+
+    it "parses expression" do
+      expect(calc.result).to eq(5)
+    end
+  end
+end
+
+# Nested contexts for state variations
+RSpec.describe BankAccount do
+  describe "#withdraw" do
+    subject(:account) { build(:bank_account, balance:) }
+
+    context "with sufficient funds" do
+      let(:balance) { 100 }
+
+      it "reduces balance" do
+        account.withdraw(50)
+        expect(account.balance).to eq(50)
+      end
+    end
+
+    context "with insufficient funds" do
+      let(:balance) { 10 }
+
+      it "raises InsufficientFundsError" do
+        expect { account.withdraw(50) }.to raise_error(InsufficientFundsError)
+      end
+    end
+  end
+end

data/skills/rspec/examples/core/configuration.rb

@@ -0,0 +1,126 @@
+# RSpec Core: Configuration Examples
+# Source: rspec-core gem spec/spec_helper.rb, features/configuration/*.feature
+
+# Full spec_helper.rb configuration
+RSpec.configure do |config|
+  # Expectations configuration
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+    expectations.max_formatted_output_length = 1000
+  end
+
+  # Mocks configuration
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  # Execution order
+  config.order = :random
+  Kernel.srand config.seed
+
+  # Failure handling
+  config.fail_fast = false  # or number like 3
+
+  # Focus filtering - run only focused tests when any exist
+  config.filter_run_when_matching :focus
+
+  # Persist example status for --only-failures
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Output formatting
+  config.default_formatter = "doc" if config.files_to_run.one?
+
+  # Profile slow examples
+  config.profile_examples = 10
+
+  # Disable monkey patching (no should syntax)
+  config.disable_monkey_patching!
+
+  # Warnings
+  config.raise_errors_for_deprecations!
+end
+
+# Including modules conditionally
+RSpec.configure do |config|
+  # Include everywhere
+  config.include FactoryBot::Syntax::Methods
+
+  # Include only in specific types
+  config.include Devise::Test::ControllerHelpers, type: :controller
+  config.include Devise::Test::IntegrationHelpers, type: :request
+  config.include Capybara::DSL, type: :feature
+
+  # Include based on metadata
+  config.include ApiHelpers, :api
+  config.include AuthHelpers, :authorized
+end
+
+# Extending example groups
+RSpec.configure do |config|
+  config.extend ControllerMacros, type: :controller
+end
+
+# Custom type inference
+RSpec.configure do |config|
+  config.infer_spec_type_from_file_location!
+
+  config.define_derived_metadata(file_path: %r{/spec/api/}) do |metadata|
+    metadata[:type] = :request
+  end
+end
+
+# Shared context auto-inclusion
+RSpec.configure do |config|
+  config.include_context "authenticated user", :authenticated
+  config.include_context "with admin", :admin
+end
+
+# Filter by Ruby version
+RSpec.configure do |config|
+  config.filter_run_excluding ruby: ->(version) {
+    case version.to_s
+    when "!jruby"
+      RUBY_ENGINE == "jruby"
+    when /^> (.*)/
+      !(RUBY_VERSION.to_s > $1)
+    else
+      !(RUBY_VERSION.to_s =~ /^#{version}/)
+    end
+  }
+end
+
+# Example:
+it "uses Ruby 3.2 feature", ruby: "> 3.2" do
+end
+
+# Alias it_behaves_like for readability
+RSpec.configure do |config|
+  config.alias_it_behaves_like_to :it_has_behavior
+  config.alias_it_behaves_like_to :it_should_behave_like
+end
+
+# Around hooks for specific metadata
+RSpec.configure do |config|
+  config.around(:example, :freeze_time) do |example|
+    travel_to(Time.zone.local(2024, 1, 1)) do
+      example.run
+    end
+  end
+
+  config.around(:example, :isolated_directory) do |example|
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) { example.run }
+    end
+  end
+end
+
+# .rspec file example
+# --format documentation
+# --color
+# --require spec_helper
+# --order random
+# --profile 10
+
+# .rspec-local (gitignored, personal preferences)
+# --fail-fast
+# --format progress

data/skills/rspec/examples/core/hooks.rb

@@ -0,0 +1,126 @@
+# RSpec Core: Hooks Examples
+# Source: rspec-core gem features/hooks/before_and_after_hooks.feature
+
+# before(:example) - runs before each example
+# NOTE: Use let/let! instead of before + instance variables
+RSpec.describe Thing do
+  let(:thing) { build(:thing) }
+
+  it "has 0 widgets initially" do
+    expect(thing.widgets.count).to eq(0)
+  end
+
+  it "can accept widgets" do
+    thing.widgets << build(:widget)
+    expect(thing.widgets.count).to eq(1)
+  end
+
+  it "does not share state across examples" do
+    expect(thing.widgets.count).to eq(0)  # Fresh thing via let
+  end
+end
+
+# Hook scopes - configuration level
+# NOTE: Suite/context level hooks are configured globally
+RSpec.configure do |config|
+  config.before(:suite) do
+    # Run once before all specs (database setup, etc.)
+    DatabaseCleaner.strategy = :transaction
+  end
+
+  config.after(:suite) do
+    # Run once after all specs (cleanup)
+  end
+end
+
+# Conditional hooks with metadata
+RSpec.configure do |config|
+  config.before(:example, :authorized) do
+    sign_in_as(:authorized_user)
+  end
+
+  config.before(:example, db: :clean) do
+    DatabaseCleaner.clean
+  end
+end
+
+RSpec.describe AdminController, :authorized do
+  let(:admin) { create(:user, :admin) }
+
+  it "allows access" do  # sign_in_as runs automatically
+    get :index
+    expect(response).to be_successful
+  end
+end
+
+# around hooks - wrap example execution
+RSpec.describe "Database transaction" do
+  around(:example) do |example|
+    DatabaseCleaner.cleaning do
+      example.run
+    end
+  end
+
+  let(:user) { create(:user) }
+
+  it "runs inside transaction" do
+    expect(user).to be_persisted
+    # Transaction rolled back after example
+  end
+end
+
+# around with before/after - execution order
+RSpec.describe "Hook order" do
+  # Output order:
+  # 1. around: before
+  # 2. before
+  # 3. example
+  # 4. after
+  # 5. around: after
+
+  around(:example) do |example|
+    puts "around: before"
+    example.run
+    puts "around: after"
+  end
+
+  before(:example) { puts "before" }
+  after(:example) { puts "after" }
+
+  it "runs in order" do
+    puts "example"
+  end
+end
+
+# before(:context) - shared expensive setup
+# NOTE: let/subject/mocks NOT available in before(:context)
+# Use instance variables ONLY when before(:context) is required
+RSpec.describe "Expensive shared setup" do
+  before(:context) do
+    # This is the ONE exception where instance variables are acceptable
+    # because let is not supported in before(:context)
+    @shared_resource = ExpensiveResource.create
+  end
+
+  after(:context) do
+    @shared_resource.cleanup
+  end
+
+  it "uses shared resource" do
+    expect(@shared_resource).to be_ready
+  end
+
+  it "reuses same resource" do
+    expect(@shared_resource).to be_ready
+  end
+end
+
+# Preferred alternative: use let! with memoization at context level
+RSpec.describe "Preferred shared setup" do
+  # If possible, restructure to avoid before(:context)
+  let!(:resource) { create(:expensive_resource) }
+
+  it "uses resource" do
+    expect(resource).to be_ready
+  end
+end