or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-management.mdcoverage-processing.mdhttp-submission.mdindex.mdlcov-conversion.md
tile.json

tessl/npm-coveralls

Node.js library and CLI tool for sending code coverage data to Coveralls.io

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/coveralls@3.1.x

To install, run

npx @tessl/cli install tessl/npm-coveralls@3.1.0

index.mddocs/

Coveralls

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.

Package Information

  • Package Name: coveralls
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install coveralls --save-dev

Core Imports

const coveralls = require('coveralls');

Individual functions:

const { 
  handleInput, 
  convertLcovToCoveralls, 
  sendToCoveralls, 
  getOptions,
  getBaseOptions,
  logger,
  options
} = require('coveralls');

Basic Usage

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.info

Architecture

Coveralls is built around several key components:

  • Input Handler: handleInput orchestrates the entire coverage submission workflow
  • LCOV Converter: convertLcovToCoveralls parses LCOV format and transforms to Coveralls JSON
  • HTTP Client: sendToCoveralls handles API communication with Coveralls.io
  • Configuration System: getOptions automatically detects CI environment and configuration
  • Git Integration: fetchGitData extracts repository metadata for coverage reports
  • CLI Tool: Standalone executable for command-line usage and CI integration

Capabilities

Coverage Processing

Main 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;

Coverage Processing

LCOV Conversion

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[];
}

LCOV Conversion

HTTP Submission

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;

HTTP Submission

Configuration Management

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;

Configuration Management

Logger Factory

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;
}

Command-Line Options

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;

Types

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[];
}

Environment Variables

The package supports extensive environment variable configuration:

  • COVERALLS_SERVICE_NAME: CI service name
  • COVERALLS_REPO_TOKEN: Repository token for private repos
  • COVERALLS_GIT_BRANCH: Git branch name override
  • COVERALLS_FLAG_NAME: Flag name for parallel builds
  • COVERALLS_SERVICE_NUMBER: Build number
  • COVERALLS_SERVICE_JOB_ID: Job ID
  • COVERALLS_SERVICE_JOB_NUMBER: Job number
  • COVERALLS_RUN_AT: Timestamp override
  • COVERALLS_PARALLEL: Enable parallel build mode
  • COVERALLS_ENDPOINT: Custom Coveralls endpoint URL
  • NODE_COVERALLS_DEBUG: Enable debug logging

Supported CI Systems

Automatic detection and configuration for:

  • Travis CI
  • CircleCI
  • Jenkins
  • Drone
  • CodeShip
  • Wercker
  • GitLab CI
  • AppVeyor
  • Surf
  • Buildkite
  • Semaphore
  • Azure Pipelines
  • Codefresh