Cursor rule

1---
2description: Backend Java tests, controller-level behavior tests, JUnit, @Nested, MakeMe builders, @Transactional, parameterized tests
3globs: backend/src/test/**/*.java
4alwaysApply: false
5---
6# Backend Testing Rules
7 
8Use this rule when creating or updating backend Java tests.
9 
10## Commands
11 
12Run backend verification from the repo root:
13 
14```bash
15CURSOR_DEV=true nix develop -c pnpm backend:verify
16```
17 
18When no database migration is involved, this is faster:
19 
20```bash
21CURSOR_DEV=true nix develop -c pnpm backend:test_only
22```
23 
24Always run all backend unit tests instead of a selected file or test case.
25 
26## Core Principles
27 
281. Test behavior, not implementation. Verify system behavior through pre/post state transitions and keep tests resilient to internal structure changes.
292. Prefer controller or other stable-boundary tests for behavior users see through HTTP. These tests often do not reference the internal class you edited.
303. Do not mirror the package tree with one test class per production class. One observable test can cover several layers.
314. Test services and algorithms directly only when they are an independent, intentional contract, such as pure logic or algorithms.
325. Keep tests small and focused: one behavior per test and descriptive names that explain the behavior.
33 
34Controller-style example:
35 
36```java
37@Test
38void shouldBeAbleToSaveNoteWhenValid() throws UnexpectedNoAccessRightException {
39  Note note = makeMe.aNote().creatorAndOwner(userModel).please();
40  final NoteRealm noteRealm = controller.show(note);
41  assertThat(noteRealm.getId(), equalTo(note.getId()));
42}
43```
44 
45Independent algorithm example:
46 
47```java
48@ParameterizedTest
49@CsvSource({
50  "moon,     partner of earth,          partner of earth",
51  "Sedition, word sedition means this,  word [...] means this"
52})
53void clozeDescription(String title, String markdown, String expectedClozeDescription) {
54  assertThat(
55      new ClozedString(clozeReplacement, markdown).hide(new NoteTitle(title)).maskedContentAsMarkdown(),
56      containsString(expectedClozeDescription));
57}
58```
59 
60## Database Tests
61 
62- Tests use actual database interactions with `@Transactional`.
63- This gives confidence in database operations and repository behavior.
64 
65```java
66@SpringBootTest
67@ActiveProfiles("test")
68@Transactional
69class RestNoteControllerTests {
70  // ...
71}
72```
73 
74## MakeMe Builders
75 
76- Use the central `makeMe` factory to create test data.
77- Each entity has its own builder, such as `NoteBuilder` or `ConversationBuilder`.
78- Use method chaining for readability.
79- End with `please()` to build the object.
80- Use `please(boolean needPersist)` to control database persistence.
81- Builders handle relationships and dependencies automatically.
82 
83```java
84Note note = makeMe.aNote()
85                 .creatorAndOwner(userModel)
86                 .titleConstructor("title")
87                 .content("description")
88                 .please();
89```
90 
91## Test Organization
92 
93- Group related tests with `@Nested`.
94- Use `@BeforeEach` for common setup, keeping setup minimal and relevant to the group.
95- Initialize test data using MakeMe builders.
96- Use mocking sparingly, mainly for external services.
97- Mock `OpenAIClient` structured Responses output with `OpenAiStructuredResponseMock` in controller tests.
98 
99```java
100@Nested
101class CreateNoteTest {
102  Note parent;
103  NoteCreationDTO noteCreation;
104 
105  @BeforeEach
106  void setup() {
107    // ...
108  }
109 
110  @Test
111  void shouldBeAbleToSaveNoteWhenValid() {
112    // ...
113  }
114}
115```
116 
117## Assertions
118 
119- Use `assertThat` with descriptive matchers for readable failures.
120- Test both happy paths and error cases.
121- Use `assertThrows` for exception testing.
122- Use `@ParameterizedTest` for multiple scenarios with less code.
123- Each test should create its own data and avoid sharing mutable state.
124 
125```java
126assertThat(noteRealm.getNote().getTopicConstructor(), equalTo(note.getTopicConstructor()));
127assertThat(noteRealm.getFromBazaar(), is(true));
128```
129 
130```java
131assertThrows(
132    UnexpectedNoAccessRightException.class,
133    () -> controller.show(note));
134```
135