Coveralls is a Node.js library and command-line tool for sending code coverage data to the Coveralls.io service. It processes LCOV coverage data from various testing frameworks and CI environments, transforming it into the format required by the Coveralls.io API. The package supports automatic detection of CI environment settings, Git repository information extraction, and flexible input handling through both programmatic API and command-line interface.
npm install coveralls --save-devconst coveralls = require('coveralls');Individual functions:
const {
handleInput,
convertLcovToCoveralls,
sendToCoveralls,
getOptions,
getBaseOptions,
logger,
options
} = require('coveralls');const coveralls = require('coveralls');
const fs = require('fs');
// Read LCOV data and send to Coveralls
const lcovData = fs.readFileSync('./coverage/lcov.info', 'utf8');
coveralls.handleInput(lcovData, (err, result) => {
if (err) {
console.error('Error sending coverage:', err);
} else {
console.log('Coverage sent successfully:', result);
}
});Command-line usage:
# Pipe LCOV data to coveralls
cat coverage/lcov.info | ./node_modules/.bin/coveralls
# Or with jest
jest --coverage && coveralls < coverage/lcov.infoCoveralls is built around several key components:
handleInput orchestrates the entire coverage submission workflowconvertLcovToCoveralls parses LCOV format and transforms to Coveralls JSONsendToCoveralls handles API communication with Coveralls.iogetOptions automatically detects CI environment and configurationfetchGitData extracts repository metadata for coverage reportsMain workflow function that processes LCOV coverage data and submits it to Coveralls.io with full CI environment detection.
function handleInput(
input: string,
callback: (err: Error | null, result?: string) => void,
userOptions?: object
): void;Converts LCOV format coverage data into Coveralls.io JSON format with source file reading and metadata enrichment.
function convertLcovToCoveralls(
input: string,
options: CoverallsOptions,
callback: (err: Error | null, data?: CoverallsData) => void
): void;
interface CoverallsOptions {
filepath?: string;
service_name?: string;
service_number?: string;
service_job_id?: string;
service_job_number?: string;
service_pull_request?: string;
repo_token?: string;
flag_name?: string;
parallel?: boolean;
run_at?: string;
git?: GitData;
}
interface CoverallsData {
source_files: SourceFile[];
service_name?: string;
service_number?: string;
service_job_id?: string;
service_job_number?: string;
service_pull_request?: string;
repo_token?: string;
flag_name?: string;
parallel?: boolean;
run_at?: string;
git?: GitData;
}
interface SourceFile {
name: string;
source: string;
coverage: (number | null)[];
branches: number[];
}Sends coverage data to the Coveralls.io API endpoint with proper error handling and response processing.
function sendToCoveralls(
data: CoverallsData,
callback: (err: Error | null, response?: any, body?: string) => void
): void;Extracts configuration options from environment variables, CI system detection, and YAML configuration files.
function getOptions(
callback: (err: Error | null, options?: CoverallsOptions) => void,
userOptions?: object
): void;
function getBaseOptions(
callback: (err: Error | null, options?: CoverallsOptions) => void
): void;Creates configured logger instances based on verbosity settings and debug environment variables.
function logger(): LogDriverInstance;
interface LogDriverInstance {
debug(...args: any[]): void;
info(...args: any[]): void;
warn(...args: any[]): void;
error(...args: any[]): void;
}Global options object parsed from command-line arguments with support for verbose and stdout modes.
interface Options {
verbose?: boolean; // Enable verbose logging
stdout?: boolean; // Output to stdout instead of HTTP POST
_: string[]; // Non-option arguments (file paths)
}
const options: Options;interface GitData {
head: {
id: string;
author_name?: string;
author_email?: string;
committer_name?: string;
committer_email?: string;
message?: string;
};
branch?: string;
remotes?: Array<{
name: string;
url: string;
}>;
}
interface CoverallsOptions {
filepath?: string;
service_name?: string;
service_number?: string;
service_job_id?: string;
service_job_number?: string;
service_pull_request?: string;
repo_token?: string;
flag_name?: string;
parallel?: boolean;
run_at?: string;
git?: GitData;
}
interface CoverallsData {
source_files: SourceFile[];
service_name?: string;
service_number?: string;
service_job_id?: string;
service_job_number?: string;
service_pull_request?: string;
repo_token?: string;
flag_name?: string;
parallel?: boolean;
run_at?: string;
git?: GitData;
}
interface SourceFile {
name: string;
source: string;
coverage: (number | null)[];
branches: number[];
}The package supports extensive environment variable configuration:
COVERALLS_SERVICE_NAME: CI service nameCOVERALLS_REPO_TOKEN: Repository token for private reposCOVERALLS_GIT_BRANCH: Git branch name overrideCOVERALLS_FLAG_NAME: Flag name for parallel buildsCOVERALLS_SERVICE_NUMBER: Build numberCOVERALLS_SERVICE_JOB_ID: Job IDCOVERALLS_SERVICE_JOB_NUMBER: Job numberCOVERALLS_RUN_AT: Timestamp overrideCOVERALLS_PARALLEL: Enable parallel build modeCOVERALLS_ENDPOINT: Custom Coveralls endpoint URLNODE_COVERALLS_DEBUG: Enable debug loggingAutomatic detection and configuration for: