Cursor rule

1---
2description: 
3globs: test/**
4alwaysApply: false
5---
6Use this rule to learn how to write tests for the codebase.
7 
8Due to the open-source nature of this project, we have chosen Minitest + Fixtures for testing to maximize familiarity and predictability.
9 
10- **General testing rules**
11  - Always use Minitest and fixtures for testing, NEVER rspec or factories
12  - Keep fixtures to a minimum.  Most models should have 2-3 fixtures maximum that represent the "base cases" for that model.  "Edge cases" should be created on the fly, within the context of the test which it is needed.
13  - For tests that require a large number of fixture records to be created, use Rails helpers to help create the records needed for the test, then inline the creation. For example, [entries_test_helper.rb](mdc:test/support/entries_test_helper.rb) provides helpers to easily do this.
14 
15- **Write minimal, effective tests**
16  - Use system tests sparingly as they increase the time to complete the test suite
17  - Only write tests for critical and important code paths
18  - Write tests as you go, when required
19  - Take a practical approach to testing.  Tests are effective when their presence _significantly increases confidence in the codebase_.
20 
21  Below are examples of necessary vs. unnecessary tests:
22 
23```rb
24  # GOOD!!
25  # Necessary test - in this case, we're testing critical domain business logic
26  test "syncs balances" do
27    Holding::Syncer.any_instance.expects(:sync_holdings).returns([]).once
28 
29    @account.expects(:start_date).returns(2.days.ago.to_date)
30 
31    Balance::ForwardCalculator.any_instance.expects(:calculate).returns(
32      [
33        Balance.new(date: 1.day.ago.to_date, balance: 1000, cash_balance: 1000, currency: "USD"),
34        Balance.new(date: Date.current, balance: 1000, cash_balance: 1000, currency: "USD")
35      ]
36    )
37 
38    assert_difference "@account.balances.count", 2 do
39      Balance::Syncer.new(@account, strategy: :forward).sync_balances
40    end
41  end
42 
43  # BAD!!
44  # Unnecessary test - in this case, this is simply testing ActiveRecord's functionality
45  test "saves balance" do 
46    balance_record = Balance.new(balance: 100, currency: "USD")
47 
48    assert balance_record.save
49  end
50```
51 
52- **Test boundaries correctly**
53  - Distinguish between commands and query methods. Test output of query methods; test that commands were called with the correct params. See an example below:
54 
55```rb
56  class ExampleClass
57    def do_something
58      result = 2 + 2
59 
60      CustomEventProcessor.process_result(result)
61 
62      result
63    end
64  end
65 
66  class ExampleClass < ActiveSupport::TestCase
67    test "boundaries are tested correctly" do 
68      result = ExampleClass.new.do_something
69 
70      # GOOD - we're only testing that the command was received, not internal implementation details
71      # The actual tests for CustomEventProcessor belong in a different test suite!
72      CustomEventProcessor.expects(:process_result).with(4).once
73 
74      # GOOD - we're testing the implementation of ExampleClass inside its own test suite
75      assert_equal 4, result
76    end
77  end
78```
79 
80  - Never test the implementation details of one class in another classes test suite
81 
82- **Stubs and mocks**
83  - Use `mocha` gem
84  - Always prefer `OpenStruct` when creating mock instances, or in complex cases, a mock class
85  - Only mock what's necessary. If you're not testing return values, don't mock a return value.
86 
87