tarballer/test/README.md

Testing the Tarballer Utility

This directory contains test scripts for validating the functionality of the Tarballer utility.

Test Environment

All tests run in a Docker container with temporary files stored in the container's /tmp directory. This directory is:

1. Automatically created and managed by the container
2. Cleaned up after tests complete (unless you specify otherwise)
3. Internal to the container, so no files are written to the host filesystem

Running Tests

To run the tests, use Docker Compose from the project root:

# Build and run all tests
docker compose up --build

# Run only the basic test
docker compose run tarballer /bin/test.sh basic

# Run only the tar comparison test
docker compose run tarballer /bin/test.sh tar

# Keep temporary files after tests (for debugging)
docker compose run tarballer /bin/test.sh all 1

Test Types

The test script (test.sh) supports several test types:

1. basic - Tests basic tarball creation and extraction with various file types and symlinks
2. tar - Compares our utility against standard tar functionality
3. all - Runs all tests (default)
4. clean - Just cleans up temporary files

Test Directory Structure

The tests create the following structure in the container's /tmp directory:

• /tmp/complex/ - Directory with complex nested structure for basic test
• /tmp/complex-extracted/ - Where the complex test tarball is extracted
• /tmp/standard-test/ - Directory with sample app structure for tar comparison
• /tmp/standard-extracted/ - Where our utility's tarball is extracted
• /tmp/reference-extracted/ - Where standard tar's tarball is extracted

Manual Testing

If you need to manually test the tarballer utility, you can:

1. Build the binaries: docker compose up --build
2. Use the binaries in ./bin/ directory:

   # Create a tarball
   ./bin/tarballer-darwin -source /path/to/source -output output.tar.gz -prefix myapp
   
   # Testing exclude patterns
   ./bin/tarballer-darwin -source /path/to/source -output output.tar.gz -prefix myapp -exclude "*.log,temp/"
   
   # Test with verbose output
   ./bin/tarballer-darwin -source /path/to/source -output output.tar.gz -prefix myapp -verbose
   
   # Extract and verify a tarball
   ./bin/tarballer-darwin -extract -output output.tar.gz -extractdir /path/to/extract
   

Testing Exclude Patterns

To test the exclude patterns feature:

1. Create a directory with various file types:

   mkdir -p test-dir/logs test-dir/bin test-dir/src
   touch test-dir/file1.txt test-dir/file2.txt
   touch test-dir/logs/app.log test-dir/logs/error.log
   touch test-dir/bin/executable
   touch test-dir/src/main.go test-dir/src/util.go
   

2. Test with various exclude patterns:

   # Exclude all .log files
   ./bin/tarballer-darwin -source test-dir -output test1.tar.gz -prefix test -exclude "*.log" -verbose
   
   # Exclude entire directories
   ./bin/tarballer-darwin -source test-dir -output test2.tar.gz -prefix test -exclude "logs/,bin/" -verbose
   
   # Exclude multiple patterns
   ./bin/tarballer-darwin -source test-dir -output test3.tar.gz -prefix test -exclude "*.log,*.go,bin/" -verbose
   

3. Extract and verify that exclusions worked:

   ./bin/tarballer-darwin -extract -output test1.tar.gz -extractdir test1-extracted -verbose
   find test1-extracted -type f | grep ".log"  # Should return nothing
   

Modifying Tests

When modifying tests, keep in mind that the test script uses the container's /tmp directory for all temporary files. This keeps the test process self-contained within the container.