or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration-management.md coverage-processing.md http-submission.md index.md lcov-conversion.md

tile.json

HTTP Submission

Handles the HTTP communication with the Coveralls.io API to submit coverage data, with support for custom endpoints and stdout output mode.

Capabilities

Coverage Data Submission

Posts coverage data to the Coveralls.io API endpoint using HTTP POST with form data encoding.

/**
 * Send coverage data to Coveralls.io API
 * @param data - Coverage data in Coveralls JSON format
 * @param callback - Error-first callback with HTTP response
 */
function sendToCoveralls(
  data: CoverallsData,
  callback: (err: Error | null, response?: HttpResponse, body?: string) => void
): void;

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 HttpResponse {
  statusCode: number;
  headers: object;
  // Additional response properties from request library
}

Usage Examples:

const { sendToCoveralls } = require('coveralls');

// Send coverage data
const coverallsData = {
  source_files: [
    {
      name: "lib/index.js",
      source: "const x = 1;\nmodule.exports = x;",
      coverage: [1, 1],
      branches: []
    }
  ],
  service_name: "travis-ci",
  service_job_id: "12345",
  repo_token: "your-repo-token"
};

sendToCoveralls(coverallsData, (err, response, body) => {
  if (err) {
    console.error('Network error:', err);
    return;
  }
  
  if (response.statusCode >= 400) {
    console.error(`HTTP error: ${response.statusCode} - ${body}`);
    return;
  }
  
  console.log('Success:', body);
  console.log('Status:', response.statusCode);
});

API Endpoint Configuration

The submission endpoint can be customized using environment variables:

// Default endpoint
const defaultEndpoint = 'https://coveralls.io/api/v1/jobs';

// Custom endpoint via environment variable
process.env.COVERALLS_ENDPOINT = 'https://custom-coveralls.example.com';

Request Format

Coverage data is submitted as HTTP POST with form-encoded JSON:

POST /api/v1/jobs HTTP/1.1
Host: coveralls.io
Content-Type: application/x-www-form-urlencoded

json={"source_files":[...],"service_name":"travis-ci",...}

Stdout Mode

For testing and debugging, the function supports stdout mode instead of HTTP submission:

const coveralls = require('coveralls');

// Enable stdout mode
coveralls.options.stdout = true;

sendToCoveralls(data, (err, response, body) => {
  // Data is written to stdout instead of HTTP POST
  // response.statusCode will be 200
  // body will be empty string
});

Command-line usage:

# Output to stdout instead of submitting
coveralls --stdout < coverage/lcov.info

Response Handling

Successful Response

Status code: 200
Body: JSON response from Coveralls.io API
Typical success body: {"message":"Job #123.1","url":"https://coveralls.io/jobs/456"}

Error Responses

Status codes: 400+ indicate API errors
Body contains error details from Coveralls.io
Common errors:
- 422: Invalid data format
- 401: Authentication failed (invalid repo token)
- 404: Repository not found

Network Errors

Standard Node.js HTTP errors:

ECONNREFUSED: Connection refused
ENOTFOUND: DNS resolution failed
ETIMEDOUT: Request timeout

Usage with Options

The function respects global options from the main module:

const coveralls = require('coveralls');

// Configure options before calling
coveralls.options.stdout = true;  // Enable stdout mode
coveralls.options.verbose = true; // Enable verbose logging

sendToCoveralls(data, callback);

Error Handling Examples

sendToCoveralls(data, (err, response, body) => {
  if (err) {
    // Network-level errors
    console.error('Request failed:', err.message);
    if (err.code === 'ECONNREFUSED') {
      console.error('Could not connect to Coveralls.io');
    } else if (err.code === 'ETIMEDOUT') {
      console.error('Request timed out');
    }
    return;
  }
  
  // HTTP-level errors  
  if (response.statusCode >= 400) {
    console.error(`HTTP ${response.statusCode}: ${body}`);
    if (response.statusCode === 422) {
      console.error('Invalid coverage data format');
    } else if (response.statusCode === 401) {
      console.error('Authentication failed - check repo token');
    }
    return;
  }
  
  // Success
  console.log('Coverage submitted successfully');
  console.log('Response:', body);
});

Parallel Builds

For parallel build workflows, ensure the coverage data includes the parallel: true flag:

const parallelData = {
  ...coverallsData,
  parallel: true,
  flag_name: 'unit-tests'  // Distinguish different parallel jobs
};

sendToCoveralls(parallelData, callback);

After all parallel jobs complete, trigger the completion webhook as documented by Coveralls.io.