Cursor rule

1---
2description: Comprehensive testing standards and patterns for Compozy Go development - enforces mandatory t.Run patterns, testify usage, and mock standards
3globs:
4alwaysApply: false
5---
6# Testing Standards for Compozy Go Development
7 
8<critical>
9**MANDATORY REQUIREMENTS:**
10- **ALWAYS** check dependent files APIs before write tests to avoid write wrong code
11- **ALWAYS** verify against PRD and tech specs - NEVER make assumptions
12- **NEVER** use workarounds, especially in tests - implement proper solutions
13- **MUST** follow all established project standards:
14    - Architecture patterns: `.cursor/rules/architecture.mdc`
15    - Go coding standards: `.cursor/rules/go-coding-standards.mdc`
16    - Testing requirements: `.cursor/rules/testing-standards.mdc`
17    - API standards: `.cursor/rules/api-standards.mdc`
18    - Security & quality: `.cursor/rules/quality-security.mdc`
19- **MUST** run `make lint` and `make test` before completing ANY subtask
20- **MUST** follow `.cursor/rules/task-review.mdc` workflow for parent tasks
21**Enforcement:** Violating these standards results in immediate task rejection.
22</critical>
23 
24## Core Testing Requirements
25 
26<requirements type="mandatory">
27**MANDATORY testing patterns for all Go code:**
28- Use `t.Run("Should describe expected behavior")` pattern for all tests
29- Use `stretchr/testify` for assertions and mocks
30- Follow table-driven test patterns when appropriate
31- Achieve >85% coverage for business logic packages
32</requirements>
33 
34## Testing Requirements
35 
36<requirements type="mandatory">
37- **ALL tests MUST use `t.Run("Should...")` pattern** - no direct test implementation without t.Run wrapper
38- Test function names: `func TestModuleName_MethodName(t *testing.T)`
39- Each test case within t.Run with descriptive "Should..." names
40- MUST use `stretchr/testify` for assertions and mocks
41- **STANDARDIZE ON TESTIFY MOCK:** Replace existing custom mocks with `testify/mock` implementations
42</requirements>
43 
44## Anti-Patterns to Avoid
45 
46<anti_patterns type="prohibited_patterns">
47**NEVER USE TESTIFY SUITE PATTERNS:**
48- ❌ **PROHIBITED:** `suite.Suite` embedding or any suite-based test structures
49- ❌ **PROHIBITED:** Suite methods like `s.Equal()`, `s.NoError()`, `s.True()`, `s.False()`, `s.T()`
50- ❌ **PROHIBITED:** `testsuite.WorkflowTestSuite` or similar suite embeddings
51- ❌ **PROHIBITED:** Suite lifecycle methods like `SetupTest()`, `TearDownTest()`, `AfterTest()`
52 
53**USE DIRECT ASSERTIONS INSTEAD:**
54- ✅ **REQUIRED:** `assert.Equal(t, expected, actual)`
55- ✅ **REQUIRED:** `require.NoError(t, err)`
56- ✅ **REQUIRED:** `assert.True(t, condition)`
57- ✅ **REQUIRED:** Individual test functions with `*testing.T` parameter
58</anti_patterns>
59 
60<anti_patterns type="bad_examples">
61```go
62// ❌ NEVER DO THIS - Suite pattern is prohibited
63type MyTestSuite struct {
64    suite.Suite
65    // other fields
66}
67 
68func (s *MyTestSuite) TestSomething() {
69    s.Equal("expected", "actual")  // ❌ WRONG
70    s.NoError(err)                 // ❌ WRONG
71    s.T().Run("test", func(t *testing.T) { ... }) // ❌ WRONG
72}
73 
74// ✅ DO THIS INSTEAD - Direct test functions
75func TestSomething_Method(t *testing.T) {
76    t.Run("Should behave correctly", func(t *testing.T) {
77        assert.Equal(t, "expected", "actual")  // ✅ CORRECT
78        require.NoError(t, err)                // ✅ CORRECT
79    })
80}
81```
82</anti_patterns>
83 
84## Table-Driven Tests
85 
86<guidelines type="table_tests">
87- AVOID table-driven tests for 2-3 cases
88- ONLY use when 5+ similar variations exist
89- Each table test case must still use "Should..." naming
90</guidelines>
91 
92## Test Organization
93 
94<organization_rules>
95- Place `*_test.go` files alongside implementation files
96- Each test MUST be independent and repeatable
97- Mock external dependencies **only when necessary** using `testify/mock`
98- Use project test helpers: `utils.SetupTest()`, `utils.SetupFixture()`
99- Test both success and error paths
100- Ensure test coverage for all exported functions
101</organization_rules>
102 
103## Mock Standards
104 
105<when_to_mock>
106**WHEN TO USE MOCKS:**
107- External services (HTTP clients, databases, file systems)
108- Dependencies that are slow, unreliable, or have side effects
109- Complex interfaces that would make tests brittle or slow
110- **NOT REQUIRED** for simple functions, pure logic, or internal utilities
111</when_to_mock>
112 
113<pattern type="mock_implementation">
114```go
115// Define mock interface
116type MockService struct {
117    mock.Mock
118}
119 
120func (m *MockService) DoSomething(ctx context.Context, param string) error {
121    args := m.Called(ctx, param)
122    return args.Error(0)
123}
124 
125// Usage in tests
126func TestComponent_Method(t *testing.T) {
127    t.Run("Should use mocked service", func(t *testing.T) {
128        mockService := new(MockService)
129        mockService.On("DoSomething", mock.Anything, "test").Return(nil)
130 
131        component := NewComponent(mockService)
132        err := component.Method("test")
133 
134        assert.NoError(t, err)
135        mockService.AssertExpectations(t)
136    })
137}
138```
139</pattern>
140 
141<refactoring_priorities>
142- Replace custom mocks with testify/mock implementations
143- Migrate interface-based mocks to use `mock.Mock` embedding
144- Standardize mock setup and assertion patterns across the codebase
145</refactoring_priorities>
146 
147<example type="test_structure">
148```go
149func TestService_Method(t *testing.T) {
150    t.Run("Should succeed with valid input", func(t *testing.T) {
151        // arrange, act, assert
152    })
153 
154    t.Run("Should handle error cases", func(t *testing.T) {
155        // test implementation
156    })
157}
158```
159</example>
160 
161## Test Patterns
162 
163<patterns type="testing_best_practices">
164- **Arrange-Act-Assert:** Structure all tests with clear setup, execution, and verification phases
165- **Independent Tests:** Each test should be able to run in isolation
166- **Descriptive Names:** Use "Should..." pattern to describe expected behavior
167- **Mock When Necessary:** Use testify/mock only for external dependencies or complex interfaces
168- **Context Propagation:** Pass context to functions that require it, even in tests
169- **Mock Assertions:** When using mocks, always call `mockService.AssertExpectations(t)` to verify all expected calls were made
170- **Mock Cleanup:** Use `mock.AnythingOfType()` and `mock.Anything` for flexible parameter matching
171</patterns>
172 
173## Test Coverage Requirements
174 
175<coverage_requirements type="unified">
176**Unified Coverage Standard:**
177- **Business Logic Packages**: All code in `engine/{agent,task,tool,workflow}/` must achieve ≥80% test coverage
178- **Exported Functions**: All exported functions across the codebase must have meaningful tests (not just presence tests)
179- **Coverage Focus**: Prioritize testing business logic paths over trivial getters/setters
180- **Quality Gate**: Use coverage reports to identify gaps in business logic, not just check for test existence
181</coverage_requirements>
182 
183## Architectural Testing
184 
185<architectural_testing type="mandatory">
186**MANDATORY: Architecture Constraint Validation**
187- **Dependency Direction**: Test that dependencies flow inward toward domain
188- **Layer Violations**: Prevent direct dependencies between Infrastructure and Domain layers
189- **Circular Dependencies**: Automated detection of package cycles
190- **Interface Compliance**: Verify adapters properly implement port interfaces
191 
192**Implementation Pattern:**
193```go
194func TestArchitecturalConstraints(t *testing.T) {
195    t.Run("Should enforce dependency direction", func(t *testing.T) {
196        // Test that engine/infra doesn't import engine/core directly
197        // Test that engine/core doesn't import any other engine packages
198    })
199 
200    t.Run("Should prevent circular dependencies", func(t *testing.T) {
201        // Use go list or similar to detect cycles
202    })
203}
204```
205</architectural_testing>
206