frankgh commented on code in PR #255: URL: https://github.com/apache/cassandra-sidecar/pull/255#discussion_r2577070289
########## TESTING.md: ########## @@ -0,0 +1,362 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +# Testing Guide for Apache Cassandra Sidecar + +This document provides a comprehensive guide to running tests for the Apache Cassandra Sidecar project. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Test Types](#test-types) +- [Running Tests](#running-tests) +- [Test Configuration](#test-configuration) +- [Development Testing](#development-testing) +- [Continuous Integration](#continuous-integration) +- [Troubleshooting](#troubleshooting) + +## Prerequisites + +### Required Software + +1. **Java 11 or higher** (OpenJDK or Oracle) +2. **Docker** for running integration tests that leverage the S3MockContainer to test the S3 client. Unless your test requires the S3 Mock Container, please create a unit or integration test. +3. **Git** for cloning repositories + +### Build Prerequisites + +Before running tests, you must build the required Cassandra dtest jars: + +```bash +./scripts/build-dtest-jars.sh +``` + +This script builds dtest jars for the supported Cassandra versions. +You can customize which versions to build: + +- **REPO**: Cassandra git repository (default: `https://github.com/apache/cassandra.git`) +- **BRANCHES**: Space-delimited list of branches (default: `"cassandra-4.0 cassandra-4.1 cassandra-5.0 trunk"`) + +Example with custom branches: +```bash +BRANCHES="cassandra-4.1 trunk" ./scripts/build-dtest-jars.sh +``` + +### Network Setup for Multi-Node Tests + +For multi-node in-jvm dtests, network aliases must be configured. +Tests assume each node's IP address is `127.0.0.x`, where `x` is the node ID. + +#### macOS Network Aliases + +Create temporary aliases for nodes 2-20: +```bash +for i in {2..20}; do sudo ifconfig lo0 alias "127.0.0.${i}"; done +``` + +#### Linux Network Aliases + +Create temporary aliases for nodes 2-20: +```bash +for i in {2..20}; do sudo ip addr add "127.0.0.${i}/8" dev lo; done +``` + +## Test Types + +### Unit Tests + +Unit tests verify individual components in isolation. They are fast-running +and don't require external dependencies. + +**Location**: `src/test/java/` in each module + +**Running unit tests**: +```bash +# Run all unit tests +./gradlew test + +# Run unit tests for a specific module +./gradlew :client:test +./gradlew :server:test +``` + +### Integration Tests + +Integration tests verify component interactions and require running +Cassandra instances. They are divided into two categories: + +#### Lightweight Integration Tests +- Basic functionality tests +- Faster execution +- **Tag**: None (default) + +#### Heavyweight Integration Tests +- Complex scenarios +- Multi-node cluster tests +- Longer execution times +- **Tag**: `@Tag("heavy")` + +**Location**: `src/integrationTest/` in test modules + +**Running integration tests**: +```bash +# Run all integration tests +./gradlew integrationTest + +# Run only lightweight integration tests +./gradlew integrationTestLightWeight + +# Run only heavyweight integration tests +./gradlew integrationTestHeavyWeight + +# Run integration tests for specific module +./gradlew :integration-tests:integrationTest + +# Run integration tests for specific module +./gradlew :server:integrationTest +``` + +### Container Tests + +Container-based tests run in Docker environments for additional isolation. For example, +tests for the Restore from S3 feature leverage the testcontainer-based S3 service +(`com.adobe.testing.s3mock.testcontainers.S3MockContainer`). Only tests that require +testcontainer-like functionality should live under `src/containerTest/`; otherwise, +a unit or in JVM dtest integration test should suffice. + +**Location**: `src/containerTest/` in relevant modules + +### Test Fixtures + +Test fixtures provide shared test utilities and data across modules. + +**Location**: `src/testFixtures/` in modules with `java-test-fixtures` plugin + +## Running Tests + +### Quick Test Commands + +```bash +# Run all tests (unit + integration) +./gradlew check + +# Run only unit tests +./gradlew test + +# Run only integration tests +./gradlew integrationTest + +# Skip integration tests +./gradlew check -x integrationTest + +# Run with specific Cassandra versions +./gradlew test -Dcassandra.sidecar.versions_to_test=4.1,5.1 +``` + +### Test Execution Configuration + +Integration tests support several environment variables: + +| Variable | Default | Description | +|----------------------------------|---------|------------------------------------------------------------| +| `INTEGRATION_MAX_HEAP_SIZE` | `3000M` | Maximum heap size for integration tests, per parallel fork | +| `INTEGRATION_MAX_PARALLEL_FORKS` | `4` | Number of parallel test forks | +| `INTEGRATION_MTLS_ENABLED` | `true` | Enable mTLS for integration tests | + +Example: +```bash +INTEGRATION_MAX_HEAP_SIZE=4000M INTEGRATION_MAX_PARALLEL_FORKS=2 ./gradlew integrationTest +``` + +### Gradle Properties + +You can also skip integration tests using Gradle properties: + +```bash +# Via command line +./gradlew check -x integrationTest + +# Via environment variable +export skipIntegrationTest=true +./gradlew check +``` + +## Test Configuration + +### Cassandra Version Testing + +The test framework supports multiple Cassandra versions simultaneously. Configure versions via: + +**System Property**: +```bash +-Dcassandra.sidecar.versions_to_test=4.0,4.1,5.1 +``` + +**Default versions**: `4.1,5.1` (as defined in `TestVersionSupplier.java`) + +### Test Logging + +Integration tests use a dedicated logback configuration: +- **File**: `server/src/test/resources/logback-in-jvm-dtest.xml` +- **Level**: Configurable per test class + +### JVM Options + +Tests running on Java 11+ automatically receive optimized JVM arguments defined in `gradle/common/java11Options.gradle`. + +## Development Testing + +### Running Tests During Development + +For faster development cycles: + +```bash +# Run with code checks disabled +./gradlew run + +# Run specific test class +./gradlew test --tests "org.apache.cassandra.sidecar.HealthServiceTest" + +# Run specific integration test class +./gradlew :integration-tests:integrationTestLightWeight --tests "org.apache.cassandra.sidecar.routes.RoutesIntegrationTest" + +# Or run a heavy-weight test class +./gradlew :server:integrationTestHeavyWeight --tests "org.apache.cassandra.sidecar.routes.tokenrange.LeavingTest" + +# Debug test execution +./gradlew test --debug-jvm + +# Run tests continuously +./gradlew test --continuous +``` + +### Test Reports + +Test reports are generated in: +- **Unit tests**: `build/test-results/` +- **Integration tests**: `build/test-results/integration/` +- **HTML reports**: Available in respective `reports/` directories + +### Code Coverage + +Jacoco coverage reports are automatically generated after tests: + +```bash +# Generate coverage report +./gradlew jacocoTestReport + +# View coverage report +open build/reports/jacoco/test/html/index.html +``` + +## Continuous Integration + +### CircleCI Integration + +The project uses CircleCI for automated testing. To set up CircleCI on your fork: + +1. Use CircleCI's "Add Projects" function +2. Choose manual configuration (don't replace the existing config) +3. CircleCI will automatically use the in-project configuration + +### Code Quality Checks + +Before tests run, the following quality checks execute: +- **Checkstyle**: Code style verification +- **SpotBugs**: Static analysis for bugs +- **RAT**: License header verification + +```bash +# Run code quality checks only +./gradlew codeCheckTasks + +# Skip code quality checks +./gradlew test -x codeCheckTasks +``` + +## Troubleshooting + +### Common Issues + +#### "DTest jar not found" +**Solution**: Run `./scripts/build-dtest-jars.sh` to build required dependencies. + +#### "Network interface not available" +**Solution**: Set up network aliases as described in [Network Setup](#network-setup-for-multi-node-tests). + +#### "OutOfMemoryError during integration tests" Review Comment: I guess it depends on how many instances of cassandra are spun up for the test. But I agree that defaults should be sufficient for all our tests -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
