Bashcov

Bashcov respects most .simplecov settings, but it overrides SimpleCov.command_name to ensure coverage results from different test suites do not overwrite each other.

By default, Bashcov generates a command name based on the executing Bash script and its arguments (e.g., running bashcov -- ./test_suite.sh --flags results in a command name of "/bin/bash ./test_suite.sh --flags").

If your test suite runs the exact same bashcov command multiple times, the generated names will be identical, causing SimpleCov to overwrite results. To prevent this, you can manually specify a unique command name using either the --command-name CLI flag or the BASHCOV_COMMAND_NAME environment variable.

# Using the CLI flag
bashcov --command-name "unique_test_run_1" -- ./test_suite.sh

# Using an environment variable
BASHCOV_COMMAND_NAME="unique_test_run_2" bashcov -- ./test_suite.sh

The Bashcov Nix package uses bundlerEnv to manage Ruby gem dependencies. This requires Gemfile.nix.lock and gemset.nix to be in sync with bashcov.gemspec. If bashcov.gemspec is updated (e.g., version bumps or dependency changes) without updating these assets, the Nix package will fail to build.

Use the following commands within the Nix development shell to maintain these assets:

• Unconditional update: update-deps (runs bundle lock then updates gemset.nix).
• Conservative update: update-deps-conservative (only updates if it resolves nix build failures).

# Inside nix develop
$ update-deps
# OR
$ update-deps-conservative

To make Bashcov a permanent part of your project's development environment, add it as an input to your flake.nix and include its package in your devShells. Reference the output attribute packages.<system>.bashcov.

# flake.nix

{ 
  inputs = {
    bashcov.url = "github:infertux/bashcov";
    bashcov.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = inputs @ { nixpkgs, bashcov, ... }: let
    system = "x86_64-linux";
  in {
    devShells.${system}.default = nixpkgs.legacyPackages.${system}.mkShell {
      packages = [inputs.bashcov.packages.${system}.bashcov];
    };
  };
}

You can run Bashcov immediately using the Nix package manager without performing a permanent installation by using the nix run command pointing to the GitHub repository.

$ nix run 'github:infertux/bashcov' -- <your-bash-script> <and-options>

To enter the Nix development shell (based on numtide/devshell), run nix develop. This provides access to several maintenance commands:

• fmt: Formats all Nix code using alejandra.
• bundix: Manages Nix <=> Ruby integration assets.
• update-deps: Unconditionally updates Gemfile.nix.lock and gemset.nix.
• update-deps-conservative: Updates Gemfile.nix.lock and gemset.nix only if nix build fails without updates but succeeds with them.

$ nix develop

You can run the Bashcov application directly using nix run. Use the -- separator to pass arguments to the application.

To run Bashcov:

$ nix run '.#' -- <args>

To run a command from the development shell without entering it (e.g., update-deps):

$ nix run '.#devshell' -- <command> <args>

Bashcov includes Nix flake checks that run the test suite (unit and feature tests) and verify Nix source file formatting using treefmt-nix.

To run checks for all supported systems:

$ nix flake check -L

To run a check for a specific system (e.g., x86_64-linux), use the nix build command targeting the specific check output:

$ nix build -L '.#checks.x86_64-linux.bashcov'

Install Bashcov using the gem command. Note that SimpleCov will be installed automatically as a dependency to handle HTML report generation.

gem install bashcov

Bashcov is distributed as a Ruby gem. To install it directly to your current user, use the gem command.

Prerequisites:

• Ruby installed on your system.
• Development tools (specifically a C compiler and make) to compile native extensions for dependencies.

$ gem install bashcov

Bashcov analyzes code coverage for Bash scripts. It is designed to work with test suites like shUnit2, Bats, bash_unit, assert.sh, and bashaspec by caching and merging results from multiple runs.

To run coverage on a script, pass the script path as an argument. If your script requires its own flags, use -- to separate Bashcov options from your script's arguments.

Coverage reports are generated in a ./coverage/ directory. You can view the results by opening ./coverage/index.html in a web browser.

# Basic usage
bashcov ./script.sh

# Skip uncovered lines
bashcov --skip-uncovered ./script.sh

# Running a script with its own flags (using -- separator)
bashcov -- ./script.sh --some --flags

# Combining options and script flags
bashcov --skip-uncovered -- ./script.sh --some --flags

To enter a temporary shell environment where bashcov is available in your PATH, use the nix shell command.

$ nix shell 'github:infertux/bashcov'

To manage Bashcov within a specific project environment using Bundler, add it to your Gemfile and run bundle install. To execute the tool, prefix the command with bundle exec to ensure it uses the project's specific gem versions.

# Gemfile
source 'https://rubygems.org'
gem 'bashcov'

$ bundle install
$ bundle exec bashcov -- <your-bash-script> <and-options>