anima-core 0.3.0 → 1.0.0

data/skills/rspec/examples/matchers/collections.rb

@@ -0,0 +1,154 @@
+# RSpec Matchers: Collection Examples
+# Source: rspec-expectations gem features/built_in_matchers/include.feature,
+#         contain_exactly.feature, all.feature, have_attributes.feature
+
+# include - partial matching
+RSpec.describe "include matcher" do
+  describe "with arrays" do
+    it "checks single element" do
+      expect([1, 2, 3]).to include(1)
+    end
+
+    it "checks multiple elements" do
+      expect([1, 2, 3]).to include(1, 2)
+      expect([1, 2, 3]).to include(1, 2, 3)
+    end
+
+    it "works with composed matchers" do
+      expect([1, 3, 7]).to include(a_kind_of(Integer))
+      expect([1, 3, 7]).to include(be_odd.and be < 10)
+    end
+  end
+
+  describe "with strings" do
+    it "checks substring" do
+      expect("hello world").to include("world")
+      expect("hello world").to include("hello", "world")
+    end
+
+    it "works with regex" do
+      expect("hello world").to include(/wor.d/)
+    end
+  end
+
+  describe "with hashes" do
+    let(:hash) { { a: 1, b: 2, c: 3 } }
+
+    it "checks key existence" do
+      expect(hash).to include(:a)
+      expect(hash).to include(:a, :b)
+    end
+
+    it "checks key-value pairs" do
+      expect(hash).to include(a: 1)
+      expect(hash).to include(a: 1, b: 2)
+    end
+  end
+
+  describe "with counts" do
+    let(:items) { [{ type: :a }, { type: :b }, { type: :a }] }
+
+    it "specifies occurrence count" do
+      expect(items).to include(have_key(:type)).exactly(3).times
+      expect(items).to include(type: :a).twice
+      expect(items).to include(type: :b).once
+    end
+  end
+end
+
+# contain_exactly / match_array - order-independent full match
+RSpec.describe "contain_exactly matcher" do
+  it "matches regardless of order" do
+    expect([1, 2, 3]).to contain_exactly(3, 2, 1)
+    expect([1, 2, 3]).to contain_exactly(2, 3, 1)
+  end
+
+  it "requires all elements present" do
+    expect([1, 2, 3]).not_to contain_exactly(1, 2)      # Missing 3
+    expect([1, 2, 3]).not_to contain_exactly(1, 2, 3, 4) # Extra 4
+  end
+
+  it "works with composed matchers" do
+    expect(["barn", 2.45]).to contain_exactly(
+      a_value_within(0.1).of(2.5),
+      a_string_starting_with("bar")
+    )
+  end
+
+  it "has match_array alias" do
+    expect([1, 2, 3]).to match_array([3, 2, 1])
+  end
+end
+
+# start_with / end_with
+RSpec.describe "start_with/end_with matchers" do
+  describe "with strings" do
+    it "checks prefix/suffix" do
+      expect("hello world").to start_with("hello")
+      expect("hello world").to end_with("world")
+    end
+  end
+
+  describe "with arrays" do
+    it "checks first/last elements" do
+      expect([0, 1, 2, 3]).to start_with(0)
+      expect([0, 1, 2, 3]).to start_with(0, 1)
+      expect([0, 1, 2, 3]).to end_with(3)
+      expect([0, 1, 2, 3]).to end_with(2, 3)
+    end
+  end
+end
+
+# all - every element matches
+RSpec.describe "all matcher" do
+  it "requires all elements to match" do
+    expect([1, 3, 5]).to all(be_odd)
+    expect([1, 3, 5]).to all(be_an(Integer))
+    expect([1, 3, 5]).to all(be < 10)
+  end
+
+  it "works with compound matchers" do
+    expect([1, 3, 5]).to all(be_odd.and be_an(Integer))
+    expect([1, 4, 21]).to all(be_odd.or be < 10)
+  end
+
+  it "provides clear failure messages" do
+    # When one element fails, message shows which
+    expect(["foo", "bar", "baz"]).to all(be_a(String).and include("a"))
+  end
+end
+
+# have_attributes - object attribute matching
+RSpec.describe "have_attributes matcher" do
+  subject(:user) { build(:user, name: "Alice", age: 25) }
+
+  it "checks single attribute" do
+    expect(user).to have_attributes(name: "Alice")
+  end
+
+  it "checks multiple attributes" do
+    expect(user).to have_attributes(name: "Alice", age: 25)
+  end
+
+  it "works with composed matchers" do
+    expect(user).to have_attributes(name: a_string_starting_with("A"))
+    expect(user).to have_attributes(age: a_value > 18)
+  end
+end
+
+# Practical example: testing query results
+RSpec.describe User, ".active scope" do
+  let!(:active_users) { create_list(:user, 3, :active) }
+  let!(:inactive_user) { create(:user, :inactive) }
+
+  subject(:results) { described_class.active }
+
+  it "returns only active users" do
+    expect(results).to contain_exactly(*active_users)
+    expect(results).not_to include(inactive_user)
+  end
+
+  it "returns users with expected attributes" do
+    expect(results).to all(have_attributes(status: "active"))
+  end
+end

data/skills/rspec/examples/matchers/comparisons.rb

@@ -0,0 +1,79 @@
+# RSpec Matchers: Comparison Examples
+# Source: rspec-expectations gem features/built_in_matchers/comparisons.feature, be_within.feature
+
+# Operator comparisons
+RSpec.describe "comparison operators" do
+  it "supports numeric comparisons" do
+    expect(18).to be > 15
+    expect(18).to be >= 17
+    expect(18).to be <= 19
+    expect(18).to be < 20
+  end
+
+  it "supports string comparisons (alphabetical)" do
+    expect("Strawberry").to be < "Tomato"
+    expect("Strawberry").to be > "Apple"
+  end
+end
+
+# be_within - floating point tolerance
+RSpec.describe "be_within matcher" do
+  it "handles floating point precision" do
+    radius = 3
+    area = radius * radius * Math::PI
+
+    expect(area).to be_within(0.1).of(28.3)
+  end
+
+  it "specifies acceptable delta" do
+    expect(27.5).to be_within(0.5).of(27.9)
+    expect(27.5).to be_within(0.5).of(28.0)
+    expect(27.5).to be_within(0.5).of(27.0)
+  end
+
+  # Works with Time objects too
+  it "compares times with tolerance" do
+    now = Time.now
+    expect(now).to be_within(1.second).of(Time.now)
+  end
+end
+
+# be_between - range checking
+RSpec.describe "be_between matcher" do
+  it "defaults to inclusive" do
+    expect(5).to be_between(1, 10)
+    expect(1).to be_between(1, 10)   # Inclusive: includes 1
+    expect(10).to be_between(1, 10)  # Inclusive: includes 10
+  end
+
+  it "supports explicit inclusive" do
+    expect(5).to be_between(1, 10).inclusive
+  end
+
+  it "supports exclusive ranges" do
+    expect(5).to be_between(1, 10).exclusive
+    expect(1).not_to be_between(1, 10).exclusive  # Excludes boundaries
+    expect(10).not_to be_between(1, 10).exclusive
+  end
+end
+
+# Practical example
+RSpec.describe Order do
+  subject(:order) { build(:order, total: 150) }
+
+  describe "#shipping_rate" do
+    context "with standard order" do
+      it "returns rate within expected range" do
+        expect(order.shipping_rate).to be_between(5.0, 25.0)
+      end
+    end
+
+    context "with heavy order" do
+      subject(:order) { build(:order, :heavy, total: 500) }
+
+      it "returns higher rate" do
+        expect(order.shipping_rate).to be > 20.0
+      end
+    end
+  end
+end

data/skills/rspec/examples/matchers/composing.rb

@@ -0,0 +1,155 @@
+# RSpec Matchers: Composing Matchers Examples
+# Source: rspec-expectations gem features/composing_matchers.feature,
+#         compound_expectations.feature
+
+# Compound expectations with .and / &
+RSpec.describe "compound matchers with .and" do
+  it "combines matchers with .and" do
+    expect("hello world").to start_with("hello").and end_with("world")
+  end
+
+  it "uses & as alias" do
+    expect("hello world").to start_with("hello") & end_with("world")
+  end
+
+  it "chains multiple conditions" do
+    expect(5).to be_positive.and be < 10
+    expect([1, 2, 3]).to include(1).and include(3)
+  end
+end
+
+# Compound expectations with .or / |
+RSpec.describe "compound matchers with .or" do
+  it "passes if any matcher passes" do
+    color = %w[red green blue].sample
+    expect(color).to eq("red").or eq("green").or eq("blue")
+  end
+
+  it "uses | as alias" do
+    value = [true, false].sample
+    expect(value).to be(true) | be(false)
+  end
+end
+
+# Matcher aliases for composition
+RSpec.describe "composable matcher aliases" do
+  # Noun-phrase aliases read better in composed contexts:
+  # be_within       => a_value_within
+  # be_an_instance  => an_instance_of
+  # start_with      => a_string_starting_with
+  # include         => a_collection_including
+  # be_a            => a_kind_of
+
+  it "uses noun-phrase aliases in expect(...).to include" do
+    expect([1, 2.5, "foo"]).to include(
+      an_instance_of(Integer),
+      a_value_within(0.1).of(2.5),
+      a_string_starting_with("f")
+    )
+  end
+
+  it "uses noun-phrase aliases with contain_exactly" do
+    expect(["barn", 2.45]).to contain_exactly(
+      a_value_within(0.1).of(2.5),
+      a_string_starting_with("bar")
+    )
+  end
+end
+
+# Matchers as arguments
+RSpec.describe "matchers accepting matcher arguments" do
+  describe "with change" do
+    it "uses composed matchers for from/to" do
+      text = "foo bar"
+      expect { text = "baz qux" }
+        .to change { text }
+        .from(a_string_matching(/foo/))
+        .to(a_string_matching(/baz/))
+    end
+
+    it "uses composed matchers for delta" do
+      value = 0.0
+      expect { value += 1.05 }
+        .to change { value }
+        .by(a_value_within(0.1).of(1.0))
+    end
+  end
+
+  describe "with include" do
+    it "matches hash values with matchers" do
+      expect(a: "food", b: "good").to include(a: a_string_matching(/foo/))
+    end
+
+    it "matches hash keys with matchers" do
+      expect("food" => 1, "drink" => 2).to include(a_string_matching(/foo/))
+    end
+  end
+
+  describe "with match (nested structures)" do
+    it "validates deeply nested data" do
+      response = {
+        user: {
+          name: "Alice",
+          roles: ["admin", "editor"],
+          settings: { theme: "dark" }
+        }
+      }
+
+      expect(response).to match(
+        user: {
+          name: a_string_starting_with("A"),
+          roles: a_collection_including("admin"),
+          settings: { theme: a_kind_of(String) }
+        }
+      )
+    end
+  end
+end
+
+# Practical examples
+RSpec.describe API::Response do
+  subject(:response) { build(:api_response, :success) }
+
+  describe "response structure validation" do
+    it "has expected structure" do
+      expect(response.body).to match(
+        status: "success",
+        data: {
+          id: an_instance_of(Integer),
+          created_at: a_string_matching(/\d{4}-\d{2}-\d{2}/),
+          items: a_collection_including(
+            have_attributes(name: a_kind_of(String))
+          )
+        }
+      )
+    end
+  end
+end
+
+RSpec.describe User do
+  describe "#update" do
+    subject(:user) { create(:user, name: "Alice", updated_at: 1.day.ago) }
+
+    it "changes name and updated_at" do
+      expect { user.update(name: "Bob") }
+        .to change(user, :name)
+        .from(a_string_starting_with("A"))
+        .to(a_string_starting_with("B"))
+        .and change(user, :updated_at)
+    end
+  end
+end
+
+RSpec.describe "result validation" do
+  subject(:result) { build(:calculation_result) }
+
+  it "returns numeric value in expected range" do
+    expect(result.value)
+      .to be_a(Numeric)
+      .and be_within(0.01).of(expected_value)
+  end
+
+  it "has valid status" do
+    expect(result.status).to eq(:success).or eq(:partial)
+  end
+end

data/skills/rspec/examples/matchers/custom_matchers.rb

@@ -0,0 +1,197 @@
+# RSpec Matchers: Custom Matcher Examples
+# Source: rspec-expectations gem features/custom_matchers/define_matcher.feature
+
+# Basic custom matcher using DSL
+RSpec::Matchers.define :be_a_multiple_of do |expected|
+  match do |actual|
+    actual % expected == 0
+  end
+end
+
+RSpec.describe "be_a_multiple_of matcher" do
+  it "passes for multiples" do
+    expect(9).to be_a_multiple_of(3)
+    expect(12).to be_a_multiple_of(4)
+  end
+
+  it "fails for non-multiples" do
+    expect(9).not_to be_a_multiple_of(4)
+  end
+end
+
+# Custom matcher with messages and description
+RSpec::Matchers.define :be_in_range do |min, max|
+  match do |actual|
+    actual >= min && actual <= max
+  end
+
+  failure_message do |actual|
+    "expected #{actual} to be between #{min} and #{max}"
+  end
+
+  failure_message_when_negated do |actual|
+    "expected #{actual} not to be between #{min} and #{max}"
+  end
+
+  description do
+    "be in range #{min}..#{max}"
+  end
+end
+
+RSpec.describe "be_in_range matcher" do
+  it "passes for values in range" do
+    expect(5).to be_in_range(1, 10)
+  end
+
+  it "provides readable description" do
+    # In output: "should be in range 1..10"
+    expect(5).to be_in_range(1, 10)
+  end
+end
+
+# Custom matcher with chaining
+RSpec::Matchers.define :have_errors_on do |attribute|
+  chain :with_message do |message|
+    @expected_message = message
+  end
+
+  match do |model|
+    model.valid?
+    errors = model.errors[attribute]
+
+    if @expected_message
+      errors.include?(@expected_message)
+    else
+      errors.any?
+    end
+  end
+
+  failure_message do |model|
+    if @expected_message
+      "expected #{model.class} to have error '#{@expected_message}' on #{attribute}, " \
+        "but got: #{model.errors[attribute].inspect}"
+    else
+      "expected #{model.class} to have errors on #{attribute}"
+    end
+  end
+end
+
+RSpec.describe "have_errors_on matcher with chaining" do
+  subject(:user) { build(:user, email: nil) }
+
+  it "checks for any error on attribute" do
+    expect(user).to have_errors_on(:email)
+  end
+
+  it "checks for specific error message" do
+    expect(user).to have_errors_on(:email).with_message("can't be blank")
+  end
+end
+
+# Custom matcher with diffable output
+RSpec::Matchers.define :match_json_structure do |expected|
+  diffable  # Enables diff output on failure
+
+  match do |actual|
+    @actual_parsed = JSON.parse(actual)
+    structure_matches?(expected, @actual_parsed)
+  end
+
+  def structure_matches?(expected, actual)
+    case expected
+    when Hash
+      expected.all? { |k, v| actual.key?(k.to_s) && structure_matches?(v, actual[k.to_s]) }
+    when Array
+      expected.all? { |v| actual.any? { |a| structure_matches?(v, a) } }
+    when Class
+      actual.is_a?(expected)
+    else
+      true
+    end
+  end
+end
+
+# Custom matcher supporting block expectations
+RSpec::Matchers.define :complete_within do |timeout|
+  supports_block_expectations  # Required for expect { }
+
+  match do |block|
+    started = Time.now
+    block.call
+    Time.now - started < timeout
+  end
+
+  failure_message do
+    "expected block to complete within #{timeout} seconds"
+  end
+end
+
+RSpec.describe "complete_within matcher" do
+  it "passes for fast operations" do
+    expect { 1 + 1 }.to complete_within(1.second)
+  end
+end
+
+# Custom class-based matcher (from scratch)
+class BeValidJSON
+  include RSpec::Matchers::Composable
+
+  def matches?(actual)
+    @actual = actual
+    JSON.parse(actual)
+    true
+  rescue JSON::ParserError => e
+    @error = e
+    false
+  end
+
+  def failure_message
+    "expected valid JSON, got parse error: #{@error.message}"
+  end
+
+  def failure_message_when_negated
+    "expected invalid JSON, but it parsed successfully"
+  end
+
+  def description
+    "be valid JSON"
+  end
+end
+
+def be_valid_json
+  BeValidJSON.new
+end
+
+RSpec.describe "be_valid_json matcher" do
+  it "passes for valid JSON" do
+    expect('{"key": "value"}').to be_valid_json
+  end
+
+  it "fails for invalid JSON" do
+    expect("{invalid}").not_to be_valid_json
+  end
+end
+
+# Negated matcher using define_negated_matcher
+RSpec::Matchers.define_negated_matcher :exclude, :include
+
+RSpec.describe "negated matcher" do
+  it "reads more naturally" do
+    expect([1, 2, 3]).to exclude(4)
+    expect("hello").to exclude("xyz")
+  end
+end
+
+# Aliased matcher
+RSpec::Matchers.alias_matcher :a_user_with, :have_attributes
+
+RSpec.describe "aliased matcher" do
+  it "provides domain-specific language" do
+    users = [
+      build(:user, name: "Alice", role: :admin),
+      build(:user, name: "Bob", role: :member)
+    ]
+
+    expect(users).to include(a_user_with(name: "Alice", role: :admin))
+  end
+end

data/skills/rspec/examples/matchers/equality.rb

@@ -0,0 +1,58 @@
+# RSpec Matchers: Equality Examples
+# Source: rspec-expectations gem features/built_in_matchers/equality.feature
+
+# eq - value equality using ==
+RSpec.describe "eq matcher" do
+  it "compares using ==" do
+    expect(5).to eq(5)
+    expect("string").to eq("string")
+  end
+
+  it "allows type coercion" do
+    expect(5).to eq(5.0)  # Integer == Float
+  end
+
+  it "fails for different values" do
+    expect(5).not_to eq(6)
+  end
+end
+
+# eql - value equivalence using eql? (type-sensitive)
+RSpec.describe "eql matcher" do
+  it "compares using eql?" do
+    expect(5).to eql(5)
+  end
+
+  it "is type-sensitive" do
+    expect(5).not_to eql(5.0)  # Integer.eql?(Float) => false
+  end
+end
+
+# equal/be - object identity using equal?
+RSpec.describe "equal/be matcher" do
+  let(:string) { "hello" }
+
+  it "passes for same object" do
+    expect(string).to equal(string)
+    expect(string).to be(string)  # be is alias for equal
+  end
+
+  it "fails for different objects with same value" do
+    expect("hello").not_to equal("hello")  # Different String objects
+    expect("hello").not_to be("hello")
+  end
+end
+
+# Practical example: memoization verification
+RSpec.describe User do
+  subject(:user) { build(:user) }
+
+  describe "#full_name" do
+    it "memoizes result" do
+      first_call = user.full_name
+      second_call = user.full_name
+
+      expect(first_call).to be(second_call)  # Same object returned
+    end
+  end
+end