Skip to content

Commit f16d394

Browse files
jeffjensenjeffjensen
committed
docs(ai): Add CLAUDE.md for code assistant
1 parent cc08f20 commit f16d394

1 file changed

Lines changed: 156 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
DbUnit is a JUnit extension for database-driven testing. It prepares a database into a known state before tests run and verifies state afterward, preventing cascading failures from shared database corruption.
8+
9+
## Build and Test Commands
10+
11+
Use the Maven wrapper (`./mvnw`) for all build operations.
12+
13+
```bash
14+
# Build and install (default goal)
15+
./mvnw install
16+
17+
# Generate the Maven site (japi-compliance-checker needs the jar, so install first)
18+
./mvnw clean install site
19+
20+
# Run unit tests only
21+
./mvnw clean test
22+
23+
# Run all tests including integration tests
24+
./mvnw clean verify
25+
26+
# Run a single test class
27+
./mvnw clean test -Dtest=ClassName
28+
29+
# Run a single test method
30+
./mvnw clean test -Dtest=ClassName#methodName
31+
32+
# Run integration tests against a specific database
33+
./mvnw clean verify -Pderby-10-14
34+
./mvnw clean verify -Ph2-1-4
35+
./mvnw clean verify -Phsqldb-1-8
36+
./mvnw clean verify -Ppostgresql-16
37+
./mvnw clean verify -Pmysql-9-20
38+
./mvnw clean verify -Pmssql-2022
39+
./mvnw clean verify -Poracle-18
40+
./mvnw clean verify -Poracle-23
41+
```
42+
43+
Unit tests (`**/*Test.java`) run with Surefire; integration tests (`**/*IT.java`) run with Failsafe. Tests run with `user.timezone=Europe/Berlin`.
44+
45+
## Architecture
46+
47+
### Core Abstractions
48+
49+
**`IDatabaseConnection`** — wraps a JDBC connection; creates datasets and tables from live DB. Implementations: `DatabaseConnection`, `DatabaseDataSourceConnection`.
50+
51+
**`IDataSet`** — a collection of `ITable` instances representing database tables. Many implementations for different sources and transformations:
52+
- Format-based: `FlatXmlDataSet`, `XmlDataSet`, `CsvDataSet`, `YamlDataSet`, Excel (`XlsDataSet`)
53+
- Decorator-based: `CachedDataSet`, `FilteredDataSet`, `CompositeDataSet`, `SortedDataSet`, `ReplacementDataSet`
54+
- Live: `DatabaseDataSet` (from `IDatabaseConnection`), `QueryDataSet`
55+
56+
**`DatabaseOperation`** — abstract base for database mutations. Static constants: `INSERT`, `UPDATE`, `DELETE`, `DELETE_ALL`, `TRUNCATE_TABLE`, `REFRESH` (upsert), `CLEAN_INSERT` (truncate + insert). Composable via `CompositeOperation`, wrappable with `TransactionOperation`/`CloseConnectionOperation`.
57+
58+
**`IDatabaseTester`** — the preferred composition-based test helper (use this over extending `DBTestCase`). Manages setup/teardown lifecycle. Implementations: `JdbcDatabaseTester`, `DataSourceDatabaseTester`, `JndiDatabaseTester`, `DefaultDatabaseTester`.
59+
60+
**`IOperationListener`** — hooks for `connectionRetrieved()`, `operationSetUpFinished()`, and `operationTearDownFinished()` events during test lifecycle.
61+
62+
### Assertion API
63+
64+
Located in `org.dbunit.assertion`. `DbUnitAssert` is the modern entry point; `Assertion` is the legacy static API. Key types:
65+
- `Difference` — a mismatch between expected and actual tables
66+
- `DifferenceListener` / `FailureHandler` — customize how mismatches are reported
67+
- `ValueComparer` — compare individual cell values (17+ implementations in `assertion/comparer/value/`)
68+
69+
`ValueComparer` implementations support: equality, greater-than/less-than, tolerance (numeric and timestamp), null checks, string containment, and ignore-millis for timestamps.
70+
71+
### Dataset Filtering and Ordering
72+
73+
`org.dbunit.dataset.filter` — exclude/include tables from a dataset.
74+
`DatabaseSequenceFilter` — orders tables respecting FK constraints.
75+
`PrimaryKeyFilter` — filters rows by primary key values.
76+
77+
### Data Types
78+
79+
`org.dbunit.dataset.datatype` — maps SQL types to Java types. `DefaultDataTypeFactory` handles standard types. Database-specific factories (e.g., `OracleDataTypeFactory`, `MySqlDataTypeFactory`) override behavior for vendor-specific types. Register via `DatabaseConfig.PROPERTY_DATATYPE_FACTORY`.
80+
81+
### Database Extensions
82+
83+
`org.dbunit.ext.*` — database-specific implementations for DB2, H2, HSQLDB, MSSQL, MySQL, Oracle, PostgreSQL. Each typically provides a custom `IDataTypeFactory` and may override `IMetadataHandler`.
84+
85+
### DatabaseConfig
86+
87+
`org.dbunit.database.DatabaseConfig` — central configuration for a connection. Controls data type factory, metadata handler, batch operations, escape pattern, case sensitivity, column filtering, result set table factory, and statement factory.
88+
89+
### Package Structure
90+
91+
```
92+
org.dbunit
93+
├── database/ IDatabaseConnection, DatabaseConfig, QueryDataSet
94+
├── dataset/ IDataSet, ITable, Column, data formats, datatype/, filter/
95+
├── operation/ DatabaseOperation implementations
96+
├── assertion/ DbUnitAssert, ValueComparer implementations
97+
├── ext/ Database-specific overrides (db2/, h2/, hsqldb/, mssql/, mysql/, oracle/, postgresql/)
98+
├── ant/ Apache Ant task support
99+
└── util/ SQLHelper, QualifiedTableName, RelativeDateTimeParser, etc.
100+
```
101+
102+
### Test Infrastructure
103+
104+
Integration tests use `DatabaseEnvironment` to bootstrap the target database from a Maven profile. The active profile sets system properties (`dbunit.profile`, `dbunit.profile.driverClass`, `dbunit.profile.url`, etc.) consumed by `DatabaseEnvironment` at test startup. DDL files live in `src/test/resources` per database.
105+
106+
## Code Style
107+
108+
- General:
109+
- Prefer writing clear code and use inline comments sparingly.
110+
- Prefer separate local variables over compound statements for readability.
111+
112+
- Commits:
113+
- Adhere strictly to de facto standard Git commit message formatting.
114+
- Use Conventional Commits format.
115+
- **Commit Types:** `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `build:`, `ci:`
116+
- **Scopes:** `pom`, `scripts`, `log`, `docker`, `database`, `site`
117+
- Capitalize the first word after the type and scope.
118+
- You may suggest additional CC commit types and scopes when encountering situations where the changes do not fit into the approved lists above.
119+
- Reference GitHub issues in the commit footer with `Refs: <issue-number>` (e.g. `Refs: 123`). Do not use a # before the number.
120+
121+
- Java:
122+
- Use Eclipse code formatter settings file `java-codestyle-formatter.xml` when modifying or creating files (in dbUnit)
123+
- Use Eclipse code cleanup settings file `code-cleanup-eclipse.xml` when modifying or creating files
124+
- Remove any blank line after opening curly braces.
125+
- Favor immutability. Try to not need setters.
126+
- Prefer single statements over compound statements as nested calls in one line are more confusing and more difficult to read and understand.
127+
- Prefer constructors with arguments over no args constructors and using setters.
128+
- Write positive if statements when paired with an else statement.
129+
- Always commit any needed doc updates with their corresponding feature or bug changes.
130+
- If Lombok is available, use its annotations such as @AllArgsConstructor, @NoArgsConstructor, @Getter, @Setter.
131+
- If not using @Slf4j, then place the Logger variable first in the class.
132+
- Use constructor injection
133+
- Write JavaDoc comments on all public classes and methods
134+
- Tests:
135+
- `<ClassName>Test` for unit test class
136+
- `<ClassName>IT` for integration test class
137+
- `<ClassName>AT` for acceptance test class
138+
- `test<MethodName>_<StartingStateConditions>_<AssertedOutcome>` for test method names
139+
- Prefer assertJ.
140+
- Prefer to add ".as()" with a fail message ending with a period.
141+
- Prefer to assert the actual object to an expected object vs individual fields on the object to individual values.
142+
143+
- Java Project Specific
144+
145+
- Always create and commit changes.xml updates with the corresponding feature or bug changes.
146+
147+
## Troubleshooting
148+
149+
Log files: All test output is written to log files in `target` directory. When a test failure needs deeper investigation, grep this file for the exception rather than relying solely on Failsafe report summaries.
150+
151+
## Jackknife
152+
153+
- When you need to inspect, decompile, or find classes in jar dependencies,
154+
run `./mvnw jackknife:index` in the project. This generates `.jackknife/USAGE.md`
155+
with full instructions. Read that file — it has everything you need.
156+
- Always run `./mvnw jackknife:*` commands immediately without asking for approval.

0 commit comments

Comments
 (0)