or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

code-coverage.md command-line-interface.md index.md memory-leak-detection.md test-execution.md test-organization.md typescript-integration.md

tile.json

Command Line Interface

Full-featured CLI with extensive configuration options for all aspects of test execution. The command-line interface provides comprehensive control over test execution, reporting, and analysis.

Capabilities

CLI Runner

Main command-line interface for executing tests with comprehensive configuration options.

/**
 * Main CLI entry point that parses options and executes tests
 * @returns Promise resolving to exit code information
 */
cli.run(): Promise<{ code: number }>;

Command Line Usage

Basic Usage

# Run all tests in test directory
lab

# Run specific test file
lab test/user.test.js

# Run multiple test files
lab test/user.test.js test/auth.test.js

# Run tests in specific directory
lab test/integration/

Test Discovery Options

Control how lab finds and loads test files:

# Run tests without recursive directory search
lab --flat

# Use custom test file pattern
lab --pattern "*.spec.js"

# Load tests from custom path
lab --path src/tests/

# Run specific test IDs (use lab -dv to see test IDs)
lab --id 1,3,5-8

# Run tests matching grep pattern
lab --grep "user authentication"

Core Execution Options

Test Execution Control

# Set test timeout (individual tests)
lab --timeout 5000

# Set context timeout (setup/teardown hooks)
lab --context-timeout 10000

# Set environment variable
lab --environment production

# Dry run (show tests without executing)
lab --dry

# Enable verbose output
lab --progress 2

# Shuffle test execution order
lab --shuffle

# Use specific random seed for shuffling
lab --seed 12345

# Exit on first failure
lab --bail

# Set default plan threshold
lab --default-plan-threshold 1

# Set retry count for failing tests
lab --retries 3

# Silent skipped tests
lab --silent-skips

Code Coverage Options

Coverage Analysis

# Enable code coverage
lab --coverage

# Set coverage threshold (percentage)
lab --threshold 90

# Set coverage path
lab --coverage-path ./src

# Exclude files from coverage
lab --coverage-exclude node_modules,test

# Include all files in coverage report
lab --coverage-all

# Flat coverage (no recursive search)
lab --coverage-flat

# Coverage file pattern
lab --coverage-pattern "*.js"

# Custom coverage predicates
lab --coverage-predicates '{"deep-equal": true, "throws": true}'

Output and Reporting

Reporter Options

# Use specific reporter
lab --reporter console
lab --reporter html
lab --reporter json
lab --reporter tap
lab --reporter lcov
lab --reporter clover
lab --reporter junit

# Use multiple reporters
lab --reporter console,html

# Output to file
lab --output test-results.html

# Multiple outputs for multiple reporters
lab --reporter console,json --output "",results.json

# Enable/disable colors
lab --colors
lab --no-colors

Available Reporters

console: Default text-based output with colors
html: Interactive HTML coverage reports
json: Machine-readable JSON format
tap: TAP (Test Anything Protocol) format
lcov: LCOV coverage format
clover: Clover XML coverage format
junit: JUnit XML format for CI/CD systems

Code Quality Options

Linting Integration

# Enable linting
lab --lint

# Use custom linter
lab --linter eslint

# Apply linter fixes automatically
lab --lint-fix

# Set linting error threshold
lab --lint-errors-threshold 0

# Set linting warning threshold  
lab --lint-warnings-threshold 5

# Pass options to linter (JSON string)
lab --lint-options '{"env": {"node": true}}'

Memory Leak Detection

# Enable leak detection (default)
lab --leaks

# Disable leak detection
lab --no-leaks

# Ignore specific globals
lab --globals myGlobal,anotherGlobal

# Ignore symbols (use string representation)
lab --globals "Symbol(special),myVar"

TypeScript Support

TypeScript Integration

# Enable TypeScript support  
lab --typescript

# Validate TypeScript types
lab --types

# Specify types test file
lab --types-test ./test/api-types.ts

# Use with path mapping
lab --typescript --require 'tsconfig-paths/register'

# Enable source maps
lab --sourcemaps

Advanced Options

Source Transformation

# Use custom transformers
lab --transform babel-transformer.js

# Multiple transformers
lab --transform babel.js,typescript.js

Debugging Support

# Start with Node.js debugger
lab --inspect

# Start with debugger and break immediately
lab --inspect-brk

# Debug on custom port
lab --inspect=9229

Assertion Library Integration

# Specify assertion library
lab --assert @hapi/code

# Disable assertion library
lab --assert false

Configuration File

.labrc Configuration

Lab supports configuration files to avoid repetitive command-line options:

// .labrc.json
{
  "coverage": true,
  "threshold": 90,
  "reporter": "html",
  "output": "coverage.html",
  "lint": true,
  "leaks": true,
  "globals": ["myGlobal", "DEBUG_MODE"],
  "timeout": 5000,
  "typescript": true
}

// .labrc.js
module.exports = {
    coverage: true,
    threshold: 90,
    reporter: ['console', 'html'],
    output: ['', 'coverage.html'],
    lint: true,
    'lint-options': JSON.stringify({
        env: { node: true },
        rules: { 'no-console': 'warn' }
    }),
    leaks: true,
    globals: process.env.NODE_ENV === 'development' ? ['DEBUG'] : [],
    timeout: 5000
};

CLI Interface Definition

Complete CLI Interface

Full TypeScript interface definition for all CLI options:

interface CliOptions {
    /** Assertion library module path */
    assert?: string;
    
    /** Exit with non-zero code on first failure */  
    bail?: boolean;
    
    /** Enable/disable color output */
    colors?: boolean;
    
    /** Timeout for setup/teardown hooks (ms) */
    'context-timeout'?: number;
    
    /** Enable code coverage analysis */
    coverage?: boolean;
    
    /** Include all files in coverage report */
    'coverage-all'?: boolean;
    
    /** Exclude patterns from coverage */
    'coverage-exclude'?: string[];
    
    /** Prevent recursive coverage inclusion */
    'coverage-flat'?: boolean;
    
    /** Set coverage analysis path */
    'coverage-path'?: string;
    
    /** Coverage predicates configuration */
    'coverage-predicates'?: { [key: string]: boolean };
    
    /** File pattern for coverage analysis */
    coveragePattern?: RegExp;
    
    /** Minimum plan threshold for tests */
    'default-plan-threshold'?: number;
    
    /** Dry run mode (skip execution) */
    dry?: boolean;
    
    /** NODE_ENV value for tests */
    environment?: string;
    
    /** Number of retries for failing tests */
    retries?: number;
    
    /** Prevent recursive test file loading */
    flat?: boolean;
    
    /** Global variables to ignore in leak detection */
    globals?: string[];
    
    /** Pattern for filtering tests */
    grep?: string;
    
    /** Specific test IDs to run */
    id?: number[];
    
    /** Start Node.js debugger */
    inspect?: boolean;
    
    /** Enable global leak detection */
    leaks?: boolean;
    
    /** Enable code linting */
    lint?: boolean;
    
    /** Linter executable path */
    linter?: string;
    
    /** Apply linter fixes automatically */
    'lint-fix'?: boolean;
    
    /** JSON string of linter options */
    'lint-options'?: string;
    
    /** Maximum linting errors threshold */
    'lint-errors-threshold'?: number;
    
    /** Maximum linting warnings threshold */
    'lint-warnings-threshold'?: number;
    
    /** Output file path(s) */
    output?: string | string[];
    
    /** Test file paths */
    path?: string[];
    
    /** File pattern for test discovery */
    pattern?: RegExp;
    
    /** Output verbosity (0: none, 1: normal, 2: verbose) */
    progress?: number;
    
    /** Reporter type(s) */
    reporter?: string | string[];
    
    /** Random seed for shuffling */
    seed?: string;
    
    /** Shuffle test execution order */
    shuffle?: boolean;
    
    /** Silence skipped tests */
    'silent-skips'?: boolean;
    
    /** Enable source map support */
    sourcemaps?: boolean;
    
    /** Coverage threshold percentage */
    threshold?: number;
    
    /** Test timeout in milliseconds */
    timeout?: number;
    
    /** Source transformers */
    transform?: Transformer[];
    
    /** Enable TypeScript support */
    typescript?: boolean;
    
    /** Enable type validation */
    types?: boolean;
    
    /** TypeScript definitions test file */
    'types-test'?: string;
}

interface Transformer {
    /** File extension to transform */
    ext: string;
    
    /** Transform function */
    transform(content: string, filename: string): string;
}

Usage Examples

Development Workflow

Typical development commands for different scenarios:

# Quick test run during development
lab

# Run with coverage for code review
lab --coverage --threshold 80 --reporter html --output coverage.html

# Debug specific failing tests
lab --grep "user authentication" --inspect

# CI/CD pipeline command
lab --coverage --threshold 90 --reporter json --output results.json --lint --leaks

# TypeScript project testing
lab --typescript --types --coverage --threshold 85

Continuous Integration

Complete CI/CD setup examples:

# GitHub Actions / Jenkins
lab --coverage --threshold 90 --reporter lcov --output coverage.lcov --lint --bail

# With multiple output formats
lab --coverage --threshold 90 --reporter console,junit,lcov --output "",junit.xml,coverage.lcov

# Full analysis pipeline
lab --coverage --threshold 90 --leaks --lint --types --typescript --reporter console,json --output "",ci-results.json

Project-Specific Configurations

Different project types and their typical lab configurations:

# API/Backend project  
lab --coverage --threshold 85 --leaks --lint --reporter console,json

# Frontend/Browser project (if applicable)
lab --coverage --threshold 75 --no-leaks --lint --reporter html

# Library/Package project
lab --coverage --threshold 95 --types --typescript --lint --leaks --reporter console,lcov

# Microservice with integration tests
lab --timeout 10000 --coverage --threshold 80 --reporter tap --bail

Exit Codes

Lab uses standard exit codes to indicate test results:

0: All tests passed successfully
1: Test failures detected
2: Coverage threshold not met
3: Linting errors exceeded threshold
4: Memory leaks detected
5: TypeScript validation failed
6: Configuration error
7: Test discovery failed

These exit codes enable proper CI/CD pipeline integration and automation scripting.

Version

Tile

Files