|
1 | 1 | # ApprovalTests.Java Agent Instructions |
2 | 2 |
|
3 | | -## Project Overview |
4 | | - |
5 | | -ApprovalTests.Java is a snapshot-based testing library that simplifies assertions by comparing expected output to approved files. The library supports JUnit 3/4/5 and TestNG, and works with JDK 1.8-25. |
| 3 | +## Build & Test |
| 4 | +- **Full build:** `./build_and_test` (takes 1-2 min; auto-formats code via Maven formatter plugin) |
| 5 | +- **Single test:** `mvn test -pl approvaltests-tests -Dtest=ClassName#methodName` |
| 6 | +- Tests run with `en_US` locale (surefire config). Java target is 1.8. |
6 | 7 |
|
7 | 8 | ## Architecture |
| 9 | +Multi-module Maven project: **approvaltests** (core library), **approvaltests-util** (shared utilities), **approvaltests-tests** and **approvaltests-util-tests** (tests). Core API: `org.approvaltests.Approvals` with `verify()`, `verifyAll()`, `verifyAsJson()`. Pattern: Writers (generate output) → Namers (file naming) → Reporters (show diffs on failure). |
8 | 10 |
|
9 | | -This is a multi-module Maven project with the following key modules: |
10 | | - |
11 | | -- **approvaltests**: Main library containing core functionality (`Approvals.java`, writers, reporters, namers) |
12 | | -- **approvaltests-util**: Shared utilities and helper classes (used as a dependency by approvaltests) |
13 | | -- **approvaltests-tests**: Integration tests and examples |
14 | | -- **approvaltests-util-tests**: Tests for utility classes |
15 | | -- **counter_display**: Sample application |
16 | | -- **html_locker**: Additional tooling |
17 | | - |
18 | | -The core API is in `org.approvaltests.Approvals` class, which provides static methods like `verify()`, `verifyAll()`, `verifyAsJson()`. The library uses a pattern of Writers (generate output), Namers (determine file names), and Reporters (show differences when tests fail). |
19 | | - |
20 | | -## Common Commands |
21 | | - |
22 | | -### Build and Test |
23 | | -```bash |
24 | | -# Build and test via Mise (requires mise installed) |
25 | | -./build_and_test |
26 | | -``` |
27 | | - |
28 | | -**Note:** The project uses [Mise](https://mise.jdx.dev/) for task automation. The `.mise.toml` file defines tasks like `build_and_test` and `format`. Java version is specified in `.java-version` file. |
29 | | - |
30 | | -## Key Files and Concepts |
31 | | - |
32 | | -- **Approved files**: `*.approved.*` files must be committed to source control. These are automatically treated as binary in git via `.gitattributes` (`*.approved.* binary diff`) |
33 | | -- **Received files**: `*.received.*` files generated during test failures, showing actual output vs approved. These should not be committed |
34 | | -- **Reporters**: Tools that show diffs when tests fail (IntelliJ, Beyond Compare, etc.). Located in `org.approvaltests.reporters` |
35 | | -- **Namers**: Determine approval file naming based on test method/class. Located in `org.approvaltests.namer` |
36 | | -- **Writers**: Generate the actual content to be approved. Located in `org.approvaltests.writers` |
37 | | - |
38 | | -## Running Single Tests |
39 | | - |
40 | | -Individual test methods can be run using standard Maven/IDE approaches: |
41 | | -```bash |
42 | | -mvn test -Dtest=ClassName#methodName |
43 | | -``` |
44 | | - |
45 | | -**Note:** Tests run with `en_US` locale by default (configured in surefire plugin) to ensure consistent output across different environments. |
| 11 | +## Key Rules |
| 12 | +- **NEVER** approve a test (update `.approved.*` files) automatically — always prompt the user. Commit `.approved.*` files; never commit `.received.*` files. |
| 13 | +- Make file changes directly without asking permission (repo is under git, user can revert). |
| 14 | +- The build auto-formats code — do not worry about formatting. |
46 | 15 |
|
47 | 16 | ## Code Style |
48 | | - |
49 | | -There is an automatic code formatter that is used every time you build the project. |
| 17 | +- Allman brace style (opening brace on new line). camelCase methods, PascalCase classes. |
| 18 | +- Uses custom `org.lambda` utilities over Java Streams in core code. |
| 19 | +- Heavy use of `public static` overloaded methods for the main API. |
| 20 | +- Do not add unnecessary comments. Follow existing patterns in neighboring files. |
0 commit comments