frankgh commented on code in PR #255: URL: https://github.com/apache/cassandra-sidecar/pull/255#discussion_r2577087550
########## 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 Review Comment: This is documented below under `Quick Test Commands`. But I will mention how to skip container 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]
