Add comprehensive testing documentation

Added TESTING.txt with complete guide for building and testing Tomcat
Native including prerequisites, build instructions with correct buildconf
syntax, test execution workflows, and troubleshooting for common issues.

Covers all platforms (Linux, macOS, Windows) and advanced scenarios like
debugging native code, memory leak detection, and testing with Tomcat.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: csutherl

TESTING.txt

@@ -0,0 +1,387 @@
+Apache Tomcat Native Library - Testing Guide
+==============================================
+
+This document provides comprehensive instructions for building and testing
+the Apache Tomcat Native Library.
+
+Table of Contents
+-----------------
+1. Prerequisites
+2. Quick Start
+3. Building the Native Library
+4. Running Tests
+5. Troubleshooting
+6. Advanced Testing
+
+═══════════════════════════════════════════════════════════════════════════
+
+1. PREREQUISITES
+═══════════════════════════════════════════════════════════════════════════
+
+Required Software:
+  - Java 21 or higher (OpenJDK or Oracle JDK)
+  - Apache Ant (for building Java code and running tests)
+  - C compiler (GCC, Clang, or Visual Studio)
+  - APR 1.7.0+ (Apache Portable Runtime)
+  - OpenSSL 3.0.0+ (3.5.x recommended for latest features)
+  - autoconf, automake, libtool (for generating configure script)
+
+Linux/macOS Installation:
+
+  Fedora/RHEL:
+    sudo dnf install java-21-openjdk-devel ant apr-devel openssl-devel \
+                     autoconf automake libtool gcc
+
+  Ubuntu/Debian:
+    sudo apt-get install openjdk-21-jdk ant libapr1-dev libssl-dev \
+                         autoconf automake libtool build-essential
+
+  macOS (using Homebrew):
+    brew install openjdk@21 ant apr openssl@3 autoconf automake libtool
+
+Windows:
+  - Install Visual Studio 2019 or later
+  - Download and build APR from https://apr.apache.org/
+  - Download OpenSSL from https://www.openssl.org/ or use prebuilt binaries
+  - See native/BUILDING for detailed Windows build instructions
+
+Verify Prerequisites:
+  java -version        # Should be 21 or higher
+  ant -version         # Any recent version
+  apr-1-config --version    # Should be 1.7.0 or higher
+  openssl version      # Should be 3.0.0 or higher
+
+═══════════════════════════════════════════════════════════════════════════
+
+2. QUICK START
+═══════════════════════════════════════════════════════════════════════════
+
+The fastest way to build and test everything:
+
+  ./build-and-test.sh
+
+This script will:
+  1. Check all prerequisites
+  2. Build the native library
+  3. Compile Java code and tests
+  4. Run the full test suite
+  5. Report results
+
+Options:
+  -v, --verbose       Show detailed build output
+  --apr=PATH          APR installation prefix (default: /usr)
+  --ssl=PATH          OpenSSL installation prefix (default: /usr)
+
+Example with custom paths:
+  ./build-and-test.sh --apr=/usr/local/apr --ssl=/opt/openssl
+
+═══════════════════════════════════════════════════════════════════════════
+
+3. BUILDING THE NATIVE LIBRARY
+═══════════════════════════════════════════════════════════════════════════
+
+3.1 Linux/Unix/macOS Build
+---------------------------
+
+Step 1: Generate configure script (if building from git checkout)
+
+  cd native
+  sh buildconf --with-apr=/path/to/apr/source
+
+  Note: buildconf expects the path to APR *source* directory, not the
+        installed prefix. If you have APR installed from packages, you
+        can skip buildconf as the configure script is included in release
+        tarballs.
+
+Step 2: Configure the build
+
+  ./configure --with-apr=/usr --with-ssl=/usr
+
+  Common options:
+    --with-apr=PATH         APR installation prefix
+    --with-ssl=PATH         OpenSSL installation prefix
+    CFLAGS="-g -O0"         Build with debug symbols and no optimization
+
+  If APR is installed in a custom location:
+    ./configure --with-apr=/usr/local/apr --with-ssl=/usr
+
+Step 3: Build
+
+  make
+
+  The native library will be created in native/.libs/:
+    - libtcnative-2.so (Linux)
+    - libtcnative-2.dylib (macOS)
+    - libtcnative-2.dll (Windows)
+
+Step 4: Clean (if needed)
+
+  make clean          # Remove build artifacts
+  rm -rf autom4te.cache  # Remove autoconf cache
+
+3.2 Windows Build
+-----------------
+
+See native/BUILDING for detailed Windows build instructions using Visual
+Studio and nmake.
+
+═══════════════════════════════════════════════════════════════════════════
+
+4. RUNNING TESTS
+═══════════════════════════════════════════════════════════════════════════
+
+4.1 Run All Tests
+-----------------
+
+From the tomcat-native root directory:
+
+  ant test
+
+This will:
+  1. Compile Java sources
+  2. Compile test classes
+  3. Run all tests
+  4. Generate reports in logs/ directory
+
+4.2 Run Specific Test Classes
+------------------------------
+
+Run a single test class:
+
+  ant test -Dtest.name="**/TestSSL.java"
+  ant test -Dtest.name="**/TestPool.java"
+
+Run multiple test classes:
+
+  ant test -Dtest.name="**/Test{SSL,Pool,Library}.java"
+
+4.3 Run Diagnostic Tests First
+-------------------------------
+
+Before running the full test suite, run diagnostic tests to verify your
+environment is correctly configured:
+
+  ant test -Dtest.name="**/TestBuildEnvironment.java"
+
+This will check:
+  - Java version (21+)
+  - Library path configuration
+  - Native library availability
+  - OpenSSL version compatibility
+  - APR dependencies
+
+4.4 Test Output Locations
+--------------------------
+
+  logs/TEST-*.txt       - Detailed test results for each test class
+  logs/TEST-*.xml       - JUnit XML format results
+
+4.5 Running Tests with Custom Library Path
+-------------------------------------------
+
+If you built the native library in a custom location:
+
+  ant test -Djava.library.path=/path/to/native/.libs
+
+═══════════════════════════════════════════════════════════════════════════
+
+5. TROUBLESHOOTING
+═══════════════════════════════════════════════════════════════════════════
+
+5.1 "Native library not found"
+-------------------------------
+
+Error: java.lang.UnsatisfiedLinkError: no tcnative-2 in java.library.path
+
+Solution:
+  1. Verify native library was built:
+     ls -la native/.libs/libtcnative-2.*
+
+  2. Rebuild the native library:
+     cd native && make clean && make
+
+  3. Check that build.xml is setting java.library.path correctly
+
+5.2 "OpenSSL version mismatch"
+------------------------------
+
+Error: Library built for OpenSSL 1.1 but system has OpenSSL 3.x
+
+Solution:
+  Rebuild the native library against your current OpenSSL version:
+
+    cd native
+    make clean
+    rm -rf autom4te.cache
+    ./configure --with-apr=/usr --with-ssl=/usr
+    make
+
+5.3 "configure: error: APR not found"
+-------------------------------------
+
+Error: configure: error: APR could not be located
+
+Solution:
+  1. Install APR development package (see Prerequisites section)
+
+  2. If APR is installed in custom location, specify path:
+     ./configure --with-apr=/usr/local/apr
+
+  3. Verify apr-1-config is in PATH:
+     which apr-1-config
+     apr-1-config --prefix
+
+5.4 "Java version too old"
+---------------------------
+
+Error: Java 21 or higher required
+
+Solution:
+  1. Install Java 21:
+     - Fedora/RHEL: sudo dnf install java-21-openjdk-devel
+     - Ubuntu/Debian: sudo apt-get install openjdk-21-jdk
+     - macOS: brew install openjdk@21
+
+  2. Set JAVA_HOME and PATH:
+     export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
+     export PATH=$JAVA_HOME/bin:$PATH
+
+5.5 Test Failures
+-----------------
+
+If specific tests fail:
+
+  1. Check logs/TEST-*.txt for detailed error messages
+
+  2. Run diagnostics:
+     ant test -Dtest.name="**/TestBuildEnvironment.java"
+
+  3. Verify OpenSSL version:
+     openssl version
+     # Should be 3.0.0 or higher
+
+  4. Check for library dependency issues:
+     ldd native/.libs/libtcnative-2.so  # Linux
+     otool -L native/.libs/libtcnative-2.dylib  # macOS
+
+5.6 JVM Crashes During Tests
+-----------------------------
+
+If the JVM crashes with SIGSEGV or similar:
+
+  1. This usually indicates a bug in the native code (JNI layer)
+
+  2. Rebuild with debug symbols:
+     cd native
+     make clean
+     ./configure --with-apr=/usr --with-ssl=/usr CFLAGS="-g -O0"
+     make
+
+  3. Run under debugger:
+     gdb --args java -Djava.library.path=native/.libs \
+                 -cp ... org.junit.runner.JUnitCore TestClass
+
+  4. Report the issue with:
+     - Crash stack trace
+     - OpenSSL version (openssl version)
+     - APR version (apr-1-config --version)
+     - OS and architecture (uname -a)
+
+═══════════════════════════════════════════════════════════════════════════
+
+6. ADVANCED TESTING
+═══════════════════════════════════════════════════════════════════════════
+
+6.1 Testing with Different OpenSSL Versions
+--------------------------------------------
+
+To test against a custom OpenSSL installation:
+
+  cd native
+  make clean
+  ./configure --with-apr=/usr --with-ssl=/path/to/openssl
+  make
+  cd ..
+  ant test
+
+6.2 Thread Safety Testing
+--------------------------
+
+The test suite includes thread safety tests that verify concurrent usage
+of APR pools and SSL contexts. These tests only run if the native library
+was built with thread support (APR_HAS_THREADS).
+
+To verify thread support is enabled:
+  ant test -Dtest.name="**/TestThreadSafety.java"
+
+6.3 Stress Testing
+------------------
+
+Some tests create hundreds of objects to verify memory management and
+detect leaks. These tests are marked with @Category(StressTest.class).
+
+Run only stress tests:
+  ant test -Dtest.name="**/TestStress*.java"
+
+6.4 Memory Leak Detection
+--------------------------
+
+To detect memory leaks in the native code:
+
+  1. Build with AddressSanitizer (Linux/macOS):
+     cd native
+     make clean
+     ./configure --with-apr=/usr --with-ssl=/usr \
+                 CFLAGS="-g -O0 -fsanitize=address"
+     make
+
+  2. Run tests:
+     ant test
+
+  3. Check for leak reports in test output
+
+6.5 Debugging Native Code
+--------------------------
+
+To debug native code during test execution:
+
+  1. Build with debug symbols (see 5.6 above)
+
+  2. Find the Java command used by Ant:
+     ant test -v -Dtest.name="**/TestSSL.java" 2>&1 | grep "java.*junit"
+
+  3. Run that command under gdb:
+     gdb --args java -Djava.library.path=... org.junit.runner.JUnitCore ...
+
+  4. Set breakpoints:
+     (gdb) break Java_org_apache_tomcat_jni_SSL_initialize
+     (gdb) run
+
+6.6 Testing Against Tomcat
+---------------------------
+
+To test the library with actual Tomcat:
+
+  1. Build the native library and JAR:
+     ant jar
+     cd native && make
+
+  2. Copy to Tomcat:
+     cp dist/tomcat-native-*.jar $CATALINA_HOME/lib/
+     cp native/.libs/libtcnative-2.so $CATALINA_HOME/lib/
+
+  3. Configure Tomcat to use APR:
+     Edit conf/server.xml and add:
+     <Listener className="org.apache.catalina.core.AprLifecycleListener" />
+
+  4. Start Tomcat and check logs for:
+     "Loaded Apache Tomcat Native library"
+
+═══════════════════════════════════════════════════════════════════════════
+
+For more information:
+  - Project home: https://tomcat.apache.org/native-doc/
+  - APR documentation: https://apr.apache.org/docs/apr/
+  - OpenSSL documentation: https://www.openssl.org/docs/
+
+Report issues at: https://github.com/apache/tomcat-native/issues