Skip to content

Add integration tests analysis and TestContainers migration guide #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Add integration tests analysis and TestContainers migration guide #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6c9c452
Initial plan
Copilot Dec 31, 2025
584a8eb
Add comprehensive integration tests analysis and TestContainers migra…
Copilot Dec 31, 2025
66e4feb
Add integration tests quick reference and update documentation index
Copilot Dec 31, 2025
5c88189
Add analysis folder README with navigation guide
Copilot Dec 31, 2025
804d31d
Clarify Oracle licensing - Oracle Free/XE is free for testing
Copilot Dec 31, 2025
181be3a
Clarify SQL Server and DB2 licensing - both have free editions for te…
Copilot Dec 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion documents/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,9 @@ Located in [configuration/](configuration/):
- [OJP JDBC Configuration](configuration/ojp-jdbc-configuration.md) - JDBC driver configuration
- [OJP Server Configuration](configuration/ojp-server-configuration.md) - Server configuration

## Database Setup Guides
## Testing

### Database Setup Guides

Located in [environment-setup/](environment-setup/):
- [Run Local Databases](environment-setup/run-local-databases.md) - Quick setup for local testing
Expand All @@ -53,6 +55,14 @@ Located in [environment-setup/](environment-setup/):
- [Oracle Testing Guide](environment-setup/oracle-testing-guide.md)
- [SQL Server Testing Guide](environment-setup/sqlserver-testing-guide.md)

### Integration Tests Analysis

Located in [analysis/](analysis/):
- [Integration Tests Quick Reference](analysis/INTEGRATION_TESTS_QUICK_REFERENCE.md) - Quick lookup table of all tests
- [Integration Tests Analysis](analysis/INTEGRATION_TESTS_ANALYSIS.md) - Comprehensive analysis of all integration tests
- [TestContainers Migration Guide](analysis/TESTCONTAINERS_MIGRATION_GUIDE.md) - Step-by-step guide for migrating tests to TestContainers
- [SQL Server TestContainer Guide](SQLSERVER_TESTCONTAINER_GUIDE.md) - SQL Server TestContainers implementation reference

## Framework Integration

Located in [java-frameworks/](java-frameworks/):
Expand Down Expand Up @@ -141,6 +151,7 @@ All documentation is organized under the `documents/` folder with the following
```
documents/
├── ADRs/ # Architecture Decision Records
├── analysis/ # Analysis documents and migration guides
├── code-contributions/ # Contributing guides
├── configuration/ # Configuration documentation
├── contributor-badges/ # Recognition program
Expand Down
209 changes: 209 additions & 0 deletions documents/analysis/INTEGRATION_TESTS_ANALYSIS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
# Integration Tests Analysis

**Date:** December 31, 2024
**Purpose:** Comprehensive analysis of all integration tests in the OJP project, identifying which tests use TestContainers and which do not.

## Executive Summary

- **Total Integration Tests:** 30
- **Tests Using TestContainers:** 5 (SQL Server only)
- **Tests NOT Using TestContainers:** 25 (Oracle, DB2, PostgreSQL, MySQL, MariaDB, CockroachDB, H2, Multinode)

## Tests Using TestContainers

The following **5 tests** have been migrated to use TestContainers with SQL Server:

### SQL Server Integration Tests

| Test Class | Purpose | Uses TestContainers |
|-----------|---------|-------------------|
| `SQLServerBinaryStreamIntegrationTest.java` | Tests SQL Server-specific binary stream handling (VARBINARY, IMAGE types) | ✅ Yes |
| `SQLServerBlobIntegrationTest.java` | Tests SQL Server BLOB operations and large binary data | ✅ Yes |
| `SQLServerMultipleTypesIntegrationTest.java` | Tests multiple SQL Server data types | ✅ Yes |
| `SQLServerReadMultipleBlocksOfDataIntegrationTest.java` | Tests reading large result sets in SQL Server | ✅ Yes |
| `SqlServerXAIntegrationTest.java` | Tests XA distributed transactions in SQL Server | ✅ Yes |

**Implementation Details:**
- Uses `@ArgumentsSource(SQLServerConnectionProvider.class)` annotation
- Uses `@EnabledIf("openjproxy.jdbc.testutil.SQLServerTestContainer#isEnabled")` for conditional execution
- Container: `mcr.microsoft.com/mssql/server:2022-latest`
- Shared singleton container across all tests for efficiency
- Automatic XA stored procedures installation
- Test user and database setup (`testuser`, `defaultdb`)

**Key Files:**
- `SQLServerTestContainer.java` - Singleton container manager
- `SQLServerConnectionProvider.java` - JUnit ArgumentsProvider for dynamic connection details

## Tests NOT Using TestContainers

The following **25 tests** currently use CSV files for connection configuration and require external database instances:

### Oracle Integration Tests (7 tests)

| Test Class | CSV File | Purpose |
|-----------|----------|---------|
| `OracleBinaryStreamIntegrationTest.java` | `oracle_connections.csv` | Tests Oracle RAW and BLOB binary stream handling |
| `OracleBlobIntegrationTest.java` | `oracle_connections.csv` | Tests Oracle BLOB operations |
| `OracleMultipleTypesIntegrationTest.java` | `oracle_connections.csv` | Tests multiple Oracle data types |
| `OracleReadMultipleBlocksOfDataIntegrationTest.java` | `oracle_connections_with_record_counts.csv` | Tests reading large result sets in Oracle |
| `OracleXAIntegrationTest.java` | `oracle_xa_connection.csv` | Tests XA distributed transactions in Oracle |
| `BlobIntegrationTest.java` (partial) | `h2_mysql_mariadb_oracle_connections.csv` | Tests BLOB operations across multiple databases |
| `BasicCrudIntegrationTest.java` (partial) | `h2_postgres_mysql_mariadb_oracle_sqlserver_connections.csv` | Tests basic CRUD operations |

**System Property:** `enableOracleTests=true/false`

### DB2 Integration Tests (4 tests)

| Test Class | CSV File | Purpose |
|-----------|----------|---------|
| `Db2BinaryStreamIntegrationTest.java` | `db2_connection.csv` | Tests DB2 binary stream handling |
| `Db2BlobIntegrationTest.java` | `db2_connection.csv` | Tests DB2 BLOB operations |
| `Db2MultipleTypesIntegrationTest.java` | `db2_connection.csv` | Tests multiple DB2 data types |
| `Db2ReadMultipleBlocksOfDataIntegrationTest.java` | `db2_connections_with_record_counts.csv` | Tests reading large result sets in DB2 |

**System Property:** `enableDb2Tests=true/false`

### PostgreSQL Integration Tests (4 tests)

| Test Class | CSV File | Purpose |
|-----------|----------|---------|
| `PostgresMultipleTypesIntegrationTest.java` | `postgres_connection.csv` | Tests multiple PostgreSQL data types |
| `PostgresXAIntegrationTest.java` | `postgres_xa_connection.csv` | Tests XA distributed transactions in PostgreSQL |
| `BinaryStreamIntegrationTest.java` (partial) | `h2_postgres_connections.csv` | Tests binary stream handling |
| `ReadMultipleBlocksOfDataIntegrationTest.java` (partial) | `h2_postgres_connections_with_record_counts.csv` | Tests reading large result sets |

**System Property:** `enablePostgresTests=true/false`

### MySQL/MariaDB Integration Tests (4 tests)

| Test Class | CSV File | Purpose |
|-----------|----------|---------|
| `MySQLMultipleTypesIntegrationTest.java` | `mysql_mariadb_connection.csv` | Tests multiple MySQL data types |
| `MySQLSpecificFeaturesIntegrationTest.java` | `mysql_mariadb_connection.csv` | Tests MySQL-specific features |
| `BlobIntegrationTest.java` (partial) | `h2_mysql_mariadb_oracle_connections.csv` | Tests BLOB operations |
| `BasicCrudIntegrationTest.java` (partial) | `h2_postgres_mysql_mariadb_oracle_sqlserver_connections.csv` | Tests basic CRUD operations |

**System Properties:**
- `enableMySQLTests=true/false`
- `enableMariaDBTests=true/false`

### CockroachDB Integration Tests (4 tests)

| Test Class | CSV File | Purpose |
|-----------|----------|---------|
| `CockroachDBBinaryStreamIntegrationTest.java` | `cockroachdb_connection.csv` | Tests CockroachDB binary stream handling |
| `CockroachDBBlobIntegrationTest.java` | `cockroachdb_connection.csv` | Tests CockroachDB BLOB operations |
| `CockroachDBMultipleTypesIntegrationTest.java` | `cockroachdb_connection.csv` | Tests multiple CockroachDB data types |
| `CockroachDBReadMultipleBlocksOfDataIntegrationTest.java` | `cockroachdb_connection.csv` | Tests reading large result sets in CockroachDB |

**System Property:** `enableCockroachDBTests=true/false`

### H2 Integration Tests (5 tests)

| Test Class | CSV File | Purpose |
|-----------|----------|---------|
| `H2MultipleTypesIntegrationTest.java` | `h2_connection.csv` | Tests multiple H2 data types |
| `BinaryStreamIntegrationTest.java` (partial) | `h2_postgres_connections.csv` | Tests binary stream handling |
| `BlobIntegrationTest.java` (partial) | `h2_mysql_mariadb_oracle_connections.csv` | Tests BLOB operations |
| `ReadMultipleBlocksOfDataIntegrationTest.java` (partial) | `h2_postgres_connections_with_record_counts.csv` | Tests reading large result sets |
| `BasicCrudIntegrationTest.java` (partial) | `h2_postgres_mysql_mariadb_oracle_sqlserver_connections.csv` | Tests basic CRUD operations |

**System Property:** `enableH2Tests=true/false`

### Multinode Integration Tests (2 tests)

| Test Class | CSV File | Purpose |
|-----------|----------|---------|
| `MultinodeIntegrationTest.java` | `multinode_connection.csv` | Tests multi-node OJP server configuration |
| `MultinodeXAIntegrationTest.java` | `multinode_connection.csv` | Tests XA transactions across multiple OJP nodes |

**Note:** These tests verify OJP multi-node functionality, not specific database features.

### Other Integration Tests (1 test)

| Test Class | Configuration | Purpose |
|-----------|--------------|---------|
| `MultiDataSourceIntegrationTest.java` | Hardcoded H2 URLs | Tests multi-datasource functionality with H2 in-memory databases |

**System Property:** `enableH2Tests=true/false` (or runs by default when no other DB tests are enabled)

## Database Coverage Summary

| Database | Total Tests | Uses TestContainers | Uses CSV Files | TestContainers Available |
|----------|-------------|-------------------|---------------|------------------------|
| SQL Server | 5 | 5 | 0 | ✅ Yes (implemented, Developer Edition free for testing) |
| Oracle | 7 | 0 | 7 | ✅ Yes (Oracle Free/XE is free for testing) |
| DB2 | 4 | 0 | 4 | ✅ Yes (Community Edition free for testing) |
| PostgreSQL | 4 | 0 | 4 | ✅ Yes (easy migration) |
| MySQL | 4 | 0 | 4 | ✅ Yes (easy migration) |
| MariaDB | ~2 | 0 | ~2 | ✅ Yes (easy migration) |
| CockroachDB | 4 | 0 | 4 | ✅ Yes (easy migration) |
| H2 | 5 | 0 | 5 | ⚠️ N/A (embedded, no container needed) |
| Multinode | 2 | 0 | 2 | ⚠️ Special case (tests OJP architecture) |

## Migration Priority Recommendations

### High Priority (Easy & High Value)
1. **PostgreSQL** - 4 tests, excellent TestContainers support, widely used
2. **MySQL** - 4 tests, excellent TestContainers support, widely used
3. **MariaDB** - 2-4 tests, excellent TestContainers support, MySQL compatible

### Medium Priority (Moderate Complexity)
4. **CockroachDB** - 4 tests, TestContainers support available, PostgreSQL compatible
5. **Oracle** - 7 tests, TestContainers support available (Oracle Free/XE is free for testing)

### Low Priority (Special Cases)
6. **DB2** - 4 tests, TestContainers support available (Community Edition free for testing)
7. **H2** - 5 tests, embedded database, TestContainers not beneficial
8. **Multinode** - 2 tests, require special OJP server setup, not database-specific

## Current TestContainers Dependencies

From `ojp-jdbc-driver/pom.xml`:

```xml
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>mssqlserver</artifactId>
<version>1.20.4</version>
<scope>test</scope>
</dependency>
```

## Benefits of TestContainers Migration

1. **No External Dependencies** - No need to maintain external database instances
2. **Consistency** - Same database version and configuration for all developers and CI/CD
3. **Isolation** - Each test run uses fresh, isolated database instances
4. **Speed** - Parallel test execution with isolated containers
5. **Simplicity** - Automatic container lifecycle management
6. **CI/CD Ready** - Easy integration with GitHub Actions and other CI systems
7. **Version Control** - Database version is defined in code, not documentation

## Current Limitations

### Tests Using CSV Files
- **Manual Setup Required** - Developers need to set up external databases
- **Configuration Drift** - Different developers may have different database versions/configurations
- **CI/CD Complexity** - Requires external database services or setup in CI pipelines
- **Resource Management** - Tests cannot clean up after themselves as easily
- **Documentation Overhead** - Need to maintain CSV files with connection details

### CSV Configuration Files Location
All CSV files are located in: `ojp-jdbc-driver/src/test/resources/`

Example CSV files:
- `oracle_connections.csv`
- `db2_connection.csv`
- `postgres_connection.csv`
- `mysql_mariadb_connection.csv`
- `cockroachdb_connection.csv`
- `h2_connection.csv`
- And various combined CSV files for multi-database tests

## See Also

- [TESTCONTAINERS_MIGRATION_GUIDE.md](./TESTCONTAINERS_MIGRATION_GUIDE.md) - Step-by-step guide to migrate tests to TestContainers
- [../SQLSERVER_TESTCONTAINER_GUIDE.md](../SQLSERVER_TESTCONTAINER_GUIDE.md) - SQL Server TestContainers implementation details
- [TestContainers Documentation](https://www.testcontainers.org/) - Official TestContainers documentation
124 changes: 124 additions & 0 deletions documents/analysis/INTEGRATION_TESTS_QUICK_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# Integration Tests Quick Reference

Quick reference table for all integration tests in the OJP project.

## Legend
- ✅ = Uses TestContainers
- ❌ = Uses CSV files (external database required)
- 🔧 = Ready to migrate to TestContainers
- 📝 = Special case / Not applicable for TestContainers

## All Integration Tests (30 total)

| # | Test Class | Database | Uses TestContainers | Migration Status | System Property |
|---|-----------|----------|-------------------|------------------|-----------------|
| 1 | `SQLServerBinaryStreamIntegrationTest.java` | SQL Server | ✅ | Complete | `enableSqlServerTests` |
| 2 | `SQLServerBlobIntegrationTest.java` | SQL Server | ✅ | Complete | `enableSqlServerTests` |
| 3 | `SQLServerMultipleTypesIntegrationTest.java` | SQL Server | ✅ | Complete | `enableSqlServerTests` |
| 4 | `SQLServerReadMultipleBlocksOfDataIntegrationTest.java` | SQL Server | ✅ | Complete | `enableSqlServerTests` |
| 5 | `SqlServerXAIntegrationTest.java` | SQL Server | ✅ | Complete | `enableSqlServerTests` |
| 6 | `OracleBinaryStreamIntegrationTest.java` | Oracle | ❌ 🔧 | Not migrated | `enableOracleTests` |
| 7 | `OracleBlobIntegrationTest.java` | Oracle | ❌ 🔧 | Not migrated | `enableOracleTests` |
| 8 | `OracleMultipleTypesIntegrationTest.java` | Oracle | ❌ 🔧 | Not migrated | `enableOracleTests` |
| 9 | `OracleReadMultipleBlocksOfDataIntegrationTest.java` | Oracle | ❌ 🔧 | Not migrated | `enableOracleTests` |
| 10 | `OracleXAIntegrationTest.java` | Oracle | ❌ 🔧 | Not migrated | `enableOracleTests` |
| 11 | `Db2BinaryStreamIntegrationTest.java` | DB2 | ❌ 🔧 | Not migrated | `enableDb2Tests` |
| 12 | `Db2BlobIntegrationTest.java` | DB2 | ❌ 🔧 | Not migrated | `enableDb2Tests` |
| 13 | `Db2MultipleTypesIntegrationTest.java` | DB2 | ❌ 🔧 | Not migrated | `enableDb2Tests` |
| 14 | `Db2ReadMultipleBlocksOfDataIntegrationTest.java` | DB2 | ❌ 🔧 | Not migrated | `enableDb2Tests` |
| 15 | `PostgresMultipleTypesIntegrationTest.java` | PostgreSQL | ❌ 🔧 | **High Priority** | `enablePostgresTests` |
| 16 | `PostgresXAIntegrationTest.java` | PostgreSQL | ❌ 🔧 | **High Priority** | `enablePostgresTests` |
| 17 | `BinaryStreamIntegrationTest.java` | PostgreSQL/H2 | ❌ 🔧 | **High Priority** | `enablePostgresTests` / `enableH2Tests` |
| 18 | `ReadMultipleBlocksOfDataIntegrationTest.java` | PostgreSQL/H2 | ❌ 🔧 | **High Priority** | `enablePostgresTests` / `enableH2Tests` |
| 19 | `MySQLMultipleTypesIntegrationTest.java` | MySQL | ❌ 🔧 | **High Priority** | `enableMySQLTests` |
| 20 | `MySQLSpecificFeaturesIntegrationTest.java` | MySQL | ❌ 🔧 | **High Priority** | `enableMySQLTests` |
| 21 | `BlobIntegrationTest.java` | MySQL/MariaDB/Oracle/H2 | ❌ 🔧 | **High Priority** | Multiple |
| 22 | `CockroachDBBinaryStreamIntegrationTest.java` | CockroachDB | ❌ 🔧 | Medium Priority | `enableCockroachDBTests` |
| 23 | `CockroachDBBlobIntegrationTest.java` | CockroachDB | ❌ 🔧 | Medium Priority | `enableCockroachDBTests` |
| 24 | `CockroachDBMultipleTypesIntegrationTest.java` | CockroachDB | ❌ 🔧 | Medium Priority | `enableCockroachDBTests` |
| 25 | `CockroachDBReadMultipleBlocksOfDataIntegrationTest.java` | CockroachDB | ❌ 🔧 | Medium Priority | `enableCockroachDBTests` |
| 26 | `H2MultipleTypesIntegrationTest.java` | H2 | ❌ 📝 | N/A (embedded) | `enableH2Tests` |
| 27 | `BasicCrudIntegrationTest.java` | Multiple DBs | ❌ 🔧 | Partial (SQL Server done) | Multiple |
| 28 | `MultiDataSourceIntegrationTest.java` | H2 | ❌ 📝 | N/A (special case) | `enableH2Tests` |
| 29 | `MultinodeIntegrationTest.java` | Multinode | ❌ 📝 | N/A (OJP architecture test) | N/A |
| 30 | `MultinodeXAIntegrationTest.java` | Multinode | ❌ 📝 | N/A (OJP architecture test) | N/A |

## Summary by Database

| Database | Total Tests | Using TestContainers | Using CSV | Migration Ready |
|----------|-------------|---------------------|-----------|-----------------|
| **SQL Server** | 5 | 5 (100%) | 0 | ✅ Complete |
| **Oracle** | 7 | 0 (0%) | 7 | 🔧 Ready |
| **DB2** | 4 | 0 (0%) | 4 | 🔧 Ready |
| **PostgreSQL** | 4 | 0 (0%) | 4 | 🔧 **High Priority** |
| **MySQL** | 4 | 0 (0%) | 4 | 🔧 **High Priority** |
| **MariaDB** | ~2 | 0 (0%) | ~2 | 🔧 **High Priority** |
| **CockroachDB** | 4 | 0 (0%) | 4 | 🔧 Medium Priority |
| **H2** | 5 | 0 (0%) | 5 | 📝 N/A (embedded) |
| **Multinode** | 2 | 0 (0%) | 2 | 📝 N/A (special) |

## Migration Priority

### 🔴 High Priority (Should migrate next)
1. **PostgreSQL** (4 tests) - Excellent TestContainers support, widely used
2. **MySQL** (4 tests) - Excellent TestContainers support, widely used
3. **MariaDB** (~2 tests) - Excellent TestContainers support, MySQL compatible

### 🟡 Medium Priority
4. **CockroachDB** (4 tests) - Good TestContainers support, PostgreSQL compatible
5. **Oracle** (7 tests) - Good TestContainers support (Oracle Free/XE is free for testing)

### ⚪ Low Priority / Special Cases
6. **DB2** (4 tests) - TestContainers support available (Community Edition free for testing)
7. **H2** (5 tests) - Embedded database, TestContainers not beneficial
8. **Multinode** (2 tests) - Tests OJP server architecture, not database-specific

## CSV Configuration Files

All CSV files are in: `ojp-jdbc-driver/src/test/resources/`

| CSV File | Used By | Databases |
|----------|---------|-----------|
| `oracle_connections.csv` | Oracle tests | Oracle |
| `oracle_connections_with_record_counts.csv` | Oracle tests | Oracle |
| `oracle_xa_connection.csv` | Oracle XA tests | Oracle |
| `db2_connection.csv` | DB2 tests | DB2 |
| `db2_connections_with_record_counts.csv` | DB2 tests | DB2 |
| `postgres_connection.csv` | PostgreSQL tests | PostgreSQL |
| `postgres_xa_connection.csv` | PostgreSQL XA tests | PostgreSQL |
| `h2_postgres_connections.csv` | Cross-DB tests | H2, PostgreSQL |
| `h2_postgres_connections_with_record_counts.csv` | Cross-DB tests | H2, PostgreSQL |
| `mysql_mariadb_connection.csv` | MySQL/MariaDB tests | MySQL, MariaDB |
| `h2_mysql_mariadb_oracle_connections.csv` | Cross-DB tests | H2, MySQL, MariaDB, Oracle |
| `cockroachdb_connection.csv` | CockroachDB tests | CockroachDB |
| `h2_cockroachdb_connections.csv` | Cross-DB tests | H2, CockroachDB |
| `h2_connection.csv` | H2 tests | H2 |
| `sqlserver_connections.csv` | SQL Server tests (deprecated) | SQL Server |
| `sqlserver_xa_connection.csv` | SQL Server XA tests (deprecated) | SQL Server |
| `h2_postgres_mysql_mariadb_oracle_sqlserver_connections.csv` | Cross-DB tests | Multiple |
| `multinode_connection.csv` | Multinode tests | N/A |

**Note:** SQL Server CSV files are now deprecated as all SQL Server tests use TestContainers.

## Running Tests

### With TestContainers (SQL Server)
```bash
# Requires Docker running
mvn test -pl ojp-jdbc-driver -DenableSqlServerTests=true -Dtest="SQLServer*"
```

### With CSV Files (External Database Required)
```bash
# Requires external database setup
mvn test -pl ojp-jdbc-driver -DenablePostgresTests=true -Dtest="Postgres*"
mvn test -pl ojp-jdbc-driver -DenableMySQLTests=true -Dtest="MySQL*"
mvn test -pl ojp-jdbc-driver -DenableOracleTests=true -Dtest="Oracle*"
# etc.
```

## See Also

- [INTEGRATION_TESTS_ANALYSIS.md](./INTEGRATION_TESTS_ANALYSIS.md) - Detailed analysis
- [TESTCONTAINERS_MIGRATION_GUIDE.md](./TESTCONTAINERS_MIGRATION_GUIDE.md) - Step-by-step migration guide
- [../SQLSERVER_TESTCONTAINER_GUIDE.md](../SQLSERVER_TESTCONTAINER_GUIDE.md) - SQL Server reference implementation
Loading