Coveralls Next

A modern, actively maintained rewrite of the original coveralls library for Node.js. Built for Node.js 20+ with modern dependencies and improved reliability.

What's New:

✨ Uses native Node.js fetch() and FormData APIs (no deprecated dependencies)
🔒 100% test coverage with comprehensive test suite
🚀 Modern tooling with ESLint and Prettier
📦 Zero security vulnerabilities
🔧 Active maintenance and bug fixes
📖 Comprehensive documentation and contribution guidelines

Get the great coverage reporting of Coveralls.io and add a cool coverage badge (like the one above) to your README.

Supported CI services:

Installation:

Add the latest version of coveralls-next to your package.json:

npm install coveralls-next --save-dev

If you're using mocha, add mocha-lcov-reporter to your package.json:

npm install mocha-lcov-reporter --save-dev

Usage:

This script bin/coveralls.js can take standard input from any tool that emits the lcov data format (including mocha's LCOV reporter) and send it to coveralls.io to report your code coverage there.

Once your app is instrumented for coverage, and building, you need to pipe the lcov output to coveralls (or ./node_modules/coveralls-next/bin/coveralls.js if using the direct path).

This library currently supports Travis CI with no extra effort beyond piping the lcov output to coveralls. However, if you're using a different build system, there are a few necessary environment variables:

COVERALLS_SERVICE_NAME (the name of your build system)
COVERALLS_REPO_TOKEN (the secret repo token from coveralls.io)
COVERALLS_GIT_BRANCH (the branch name)

There are optional environment variables for other build systems as well:

COVERALLS_FLAG_NAME (a flag name to differentiate jobs, e.g. Unit, Functional, Integration)
COVERALLS_SERVICE_NUMBER (a number that uniquely identifies the build)
COVERALLS_SERVICE_JOB_ID (an ID that uniquely identifies the build's job)
COVERALLS_SERVICE_JOB_NUMBER (a number that uniquely identifies the build's job)
COVERALLS_RUN_AT (a date string for the time that the job ran. RFC 3339 dates work. This defaults to your build system's date/time if you don't set it)
COVERALLS_PARALLEL (set to true when running jobs in parallel, requires a completion webhook. More info here: https://docs.coveralls.io/parallel-build-webhook)
COVERALLS_ENDPOINT (overrides the default Coveralls API endpoint. Useful for enterprise or self-hosted instances. Defaults to https://coveralls.io)
NODE_COVERALLS_DEBUG (set to 1 to enable debug-level logging. Alternative to using the -v or --verbose flag)

GitHub Actions CI

GitHub Actions users have two options:

Use the official GitHub Action (recommended for simplicity): coverallsapp/github-action - This is the easiest approach and doesn't require adding this library to your dependencies.
Use this library directly (more control): Install coveralls-next and pipe your coverage data to it in your workflow, just like you would in any other CI environment. This approach gives you more flexibility in how you configure and run coverage reporting.

See this project's own workflow for an example of using coveralls-next directly in GitHub Actions, or check out the parallel runs example using the official action.

CircleCI Orb

If you use this then there is no reason to have coveralls or coveralls-next library in your package as it has it's own npm version in the step. This doesn't use this library but the original coveralls npm package which will work just the same.

Here's our Orb for quick integration: coveralls/coveralls

Workflow example: config.yml

Travis-CI

Parallel jobs example: .travis.yml

Jest

Install jest
Use the following to run tests and push files to coveralls on success:
```
jest --coverage && coveralls < coverage/lcov.info
```

Check out an example here which makes use of Travis CI build stages

Vitest

Vitest is a modern test framework powered by Vite with built-in coverage support:

vitest run --coverage.enabled --coverage.reporter=lcov && coveralls < coverage/lcov.info

Or configure coverage in vitest.config.ts:

export default {
  test: {
    coverage: {
      provider: 'v8', // or 'istanbul'
      reporter: ['lcov', 'text']
    }
  }
}

Then run: vitest run --coverage && coveralls < coverage/lcov.info

Mocha

Mocha with nyc for coverage:

nyc mocha && nyc report --reporter=text-lcov | coveralls

Or with c8 (modern native V8 coverage):

c8 mocha && c8 report --reporter=lcov && coveralls < coverage/lcov.info

c8

Modern code coverage using Node's built-in V8 coverage. Works with any test framework:

c8 npm test && c8 report --reporter=lcov && coveralls < coverage/lcov.info

Lab

lab -r lcov | ./node_modules/.bin/coveralls

nyc

Works with almost any testing framework. Simply execute npm test with the nyc bin followed by running its reporter:

nyc npm test && nyc report --reporter=text-lcov | coveralls

TAP

Simply run your tap tests with the COVERALLS_REPO_TOKEN environment variable set and tap will automatically use nyc to report coverage to coveralls.

Command Line Parameters

Usage: coveralls.js [-v] [-s] filepath

Optional arguments:

-v, --verbose - enable verbose/debug logging
-s, --stdout - write the coverage JSON payload to stdout instead of sending to Coveralls (useful for debugging)
filepath - optionally defines the base filepath of your source files.

Running locally

If you're running locally, you must have a .coveralls.yml file, as documented in their documentation, with your repo_token in it; or, you must provide a COVERALLS_REPO_TOKEN environment variable on the command-line.

If you want to send commit data to coveralls, you can set the COVERALLS_GIT_COMMIT environment-variable to the commit hash you wish to reference. If you don't want to use a hash, you can set it to HEAD to supply coveralls with the latest commit data. This requires git to be installed and executable on the current PATH.

Migrating from node-coveralls

Switching from the original node-coveralls package is straightforward:

Update your package.json:

npm uninstall coveralls
npm install coveralls-next --save-dev

Update your scripts - The command-line interface is identical:

{
  "scripts": {
    "coverage": "nyc npm test && nyc report --reporter=text-lcov | coveralls"
  }
}

Just works! No changes needed.

Update CI configuration - If you reference the binary path directly:

# Before
- ./node_modules/coveralls/bin/coveralls.js < coverage/lcov.info

# After
- ./node_modules/coveralls-next/bin/coveralls.js < coverage/lcov.info

# Or use npx (recommended)
- npx coveralls-next < coverage/lcov.info

Node.js version requirement: Ensure you're running Node.js 20 or higher (for native fetch support)

That's it! All environment variables, flags, and configuration files remain compatible.

Troubleshooting

Common Issues

"Bad response: 422 Unprocessable Entity"

This usually means the coverage data format is incorrect or incomplete. Common causes:

Missing git information: Ensure git is installed and your directory is a git repository
Missing repo token: Set COVERALLS_REPO_TOKEN environment variable or create .coveralls.yml
Detached HEAD state: Some CI environments checkout in detached HEAD state, set COVERALLS_GIT_BRANCH explicitly

Solution:

# Enable debug logging to see what's being sent
NODE_COVERALLS_DEBUG=1 coveralls < coverage/lcov.info

# Or use --verbose flag
coveralls --verbose < coverage/lcov.info

"Cannot find module" or import errors

Cause: Package not installed or wrong Node.js version

Solution:

# Check Node.js version (must be 20+)
node --version

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

No coverage being reported

Cause: Coverage file not being generated or piped correctly

Solution:

# Verify coverage file exists and has content
cat coverage/lcov.info

# Test with --stdout to see what would be sent
coveralls --stdout < coverage/lcov.info

# Check your test command generates lcov format
nyc report --reporter=text-lcov

Git branch not detected correctly

Cause: Detached HEAD state in CI or missing git data

Solution:

# Explicitly set branch in CI
export COVERALLS_GIT_BRANCH=${CIRCLE_BRANCH}  # CircleCI
export COVERALLS_GIT_BRANCH=${CI_COMMIT_BRANCH}  # GitLab
export COVERALLS_GIT_BRANCH=${GITHUB_REF##*/}  # GitHub Actions

Enterprise/Self-hosted Coveralls instance

Cause: Default endpoint points to coveralls.io

Solution:

# Set custom endpoint
export COVERALLS_ENDPOINT=https://your-coveralls-instance.com

Getting Help

Enable debug logging: Use -v or --verbose flag, or set NODE_COVERALLS_DEBUG=1
Check the output: Use --stdout to see the exact JSON payload being sent
Verify environment: Ensure all required environment variables are set
Review CI logs: Look for error messages or missing git data warnings
Open an issue: If stuck, open an issue with:
- Your Node.js version (node --version)
- CI service being used
- Relevant configuration files
- Debug output (--verbose or NODE_COVERALLS_DEBUG=1)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

Development setup and workflow
Code style and testing requirements
Submitting pull requests
Reporting issues

Quick Guidelines

All code must have tests and maintain 100% coverage
Follow the existing code style (enforced by ESLint)
Use exact dependency versions (no ^, ~, or other range operators)
Write clear commit messages following conventional commit format
Update documentation for new features or behavior changes

See CONTRIBUTING.md for complete details.

Détail du package

coveralls-next

readme

Coveralls Next

Supported CI services:

Installation:

Usage:

GitHub Actions CI

CircleCI Orb

Travis-CI

Jest

Vitest

Mocha

c8

Lab

nyc

TAP

Command Line Parameters

Optional arguments:

Running locally

Migrating from node-coveralls

Troubleshooting

Common Issues

"Bad response: 422 Unprocessable Entity"

"Cannot find module" or import errors

No coverage being reported

Git branch not detected correctly

Enterprise/Self-hosted Coveralls instance

Getting Help

Contributing

Quick Guidelines