Bash Uploader

Introduction

The OtterWise Bash Uploader is a lightweight script that can be used in any CI environment to process and upload code coverage data to OtterWise. It's designed to be flexible, privacy-focused, and easy to integrate with your existing workflows.

This script handles several important tasks:

• Detecting your CI environment automatically (GitHub Actions, CircleCI, ChipperCI, etc.)
• Finding coverage reports in standard locations
• Gathering git information without requiring additional API access
• Removing code from coverage reports to maintain privacy
• Generating and sending patch information to track coverage changes
• Supporting multiple coverage formats and testing frameworks

Basic Usage

The simplest way to use the bash uploader is to download and run it directly in your CI pipeline:

bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh)

This command will download and execute the latest version of the bash uploader. The script will look for coverage reports in common locations and attempt to automatically detect your CI environment.

Privacy and Security

The OtterWise bash uploader is designed with privacy in mind:

• No source code transmission: The uploader strips all actual source code from coverage reports before sending them
• Local git operations: All git diff information is processed locally; only anonymized patch information is sent (showing only + and - symbols, not actual code)
• Optional verbosity control: Use the --quiet flag to prevent sensitive information from appearing in CI logs
• No API dependencies: The script uses only git commands and doesn't require access to GitHub or other provider APIs

CI Environment Detection

The bash uploader automatically detects and configures itself for various CI providers:

• GitHub Actions: Automatically detects repository, branch, and PR information
• CircleCI: Extracts workflow and job details
• ChipperCI: Optimized for Laravel's preferred CI service
• Travis CI: Supports legacy Travis builds
• AppVeyor: Extracts build and job information
• Jenkins: Detects common Jenkins environment variables

Coming soon: Support for GitLab CI, TeamCity, Heroku CI, Azure Pipelines, and Bitbucket CI.

Configuration Options

The OtterWise uploader has numerous options to customize its behavior:

Basic Options

Advanced Options

Example Usage Scenarios

Basic Usage with Default Settings

# Using environment variable for authentication
export OTTERWISE_TOKEN=your-repo-token
bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh)

Specifying a Custom Coverage File Location

bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh) \
  --repo-token your-repo-token \
  --file ./path/to/custom/coverage.xml

Using with Multiple Coverage Types

bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh) \
  --repo-token your-repo-token \
  --file ./coverage/clover.xml \
  --type-coverage-file ./pest-type-coverage.json \
  --mutation-file ./infection.json

Using Flags for Monorepos or Multiple Test Suites

# Run for backend tests
bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh) \
  --repo-token your-repo-token \
  --file ./backend/coverage/clover.xml \
  --flag backend

# Run separately for frontend tests
bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh) \
  --repo-token your-repo-token \
  --file ./frontend/coverage/lcov.info \
  --flag frontend

Automatic Coverage File Detection

If you don't specify a coverage file location, the uploader will automatically look for coverage reports in standard locations:

1. build/logs/clover.xml (PHPUnit and Pest default)
2. otterwise-coverage.xml (Custom file specifically for OtterWise)
3. build/logs/cobertura.xml (Python and Java coverage tools)
4. coverage/lcov.info (JavaScript/TypeScript coverage tools)

Additionally, the script will automatically look for type coverage in standard locations when applicable.

Troubleshooting

If you encounter issues with the bash uploader, try these troubleshooting steps:

Common Issues and Solutions

Debugging

To get more detailed information about what the uploader is doing, remove the --quiet flag or add verbose logging:

# Run without --quiet to see full debug output
bash <(curl -s https://raw.githubusercontent.com/getOtterWise/bash-uploader/main/uploader.sh) --repo-token your-repo-token

Supported Coverage Formats

The bash uploader works with the following coverage report formats:

• Clover XML (PHPUnit, Pest, and other PHP testing frameworks)
• LCOV (JavaScript, TypeScript, and front-end frameworks)
• Cobertura XML (Python, Java, and other languages)

For more details about supported formats and what data is extracted from each, see the Supported Formats page.

Advanced Metadata Collection

Beyond basic code coverage, the OtterWise bash uploader can collect and report additional metrics:

• Type Coverage: From Pest PHP's type coverage plugin
• Mutation Testing: From tools like Infection PHP

These additional metrics help create a more comprehensive view of your code quality beyond simple line coverage.

CI-Specific Integration Guides

While the bash uploader works with any CI system, we have detailed integration guides for popular CI providers:

• GitHub Actions Integration Guide
• ChipperCI Integration Guide

For further assistance, contact OtterWise support or check our example repository which contains fully working CI configuration examples.