Fauji CLI Reference

Basic Usage

npx fauji [options]

Quick Examples

# Run all tests in current directory
npx fauji

# Run tests in specific directory
npx fauji --dir ./tests

# Run tests matching a pattern
npx fauji --pattern "*.test.js"

# Run tests with specific name
npx fauji --name "auth"

# Watch mode for continuous testing
npx fauji --watch

# Combine multiple options
npx fauji --dir ./src --pattern "*.spec.js" --name "user" --watch

Command Line Options

Basic Options

Advanced Options

Utility Options

Configuration File

Fauji uses a configuration file to define test patterns and source directories. Create a fauji.config.json file in your project root:

{
  "sourceDirectory": "./src",
  "testMatch": [
    "**/*.test.js",
    "**/*.spec.js"
  ]
}

Configuration Options

• sourceDirectory - Directory containing your source code (default: current directory)
• testMatch - Array of glob patterns to match test files

Allowed Test Patterns

• **/*.test.js - Files ending with .test.js
• **/*.spec.js - Files ending with .spec.js

Environment Options

Node Environment (Default)

npx fauji --env node

Runs tests in Node.js environment. Suitable for testing utilities, services, and backend code.

JSDOM Environment

npx fauji --env jsdom

Runs tests with JSDOM for DOM testing. Automatically sets up browser-like environment with document, window, and other DOM APIs.

Example: DOM Testing

// dom.test.js
describe('DOM Testing', () => {
  test('creates and manipulates DOM elements', () => {
    const div = document.createElement('div');
    div.textContent = 'Hello World';
    document.body.appendChild(div);
    
    expect(document.body.contains(div)).toBe(true);
    expect(div.textContent).toBe('Hello World');
  });
});

npx fauji --env jsdom dom.test.js

Performance Optimization

Parallel Execution

# Use all available CPU cores
npx fauji --parallel

# Use specific number of workers
npx fauji --parallel 4

Run test files in parallel for faster execution. Defaults to the number of available CPU cores.

Large File Optimization

Fauji automatically detects and optimizes large test files for better performance:

# Auto-detect optimization strategy (default)
npx fauji --optimization-strategy auto

# Force memory optimization
npx fauji --optimization-strategy memory

# Force timeout optimization
npx fauji --optimization-strategy timeout

File Size Thresholds

# Set custom file size threshold (in bytes)
npx fauji --max-file-size 100000

# Set threshold in KB
npx fauji --max-file-size 100KB

• Default threshold: 50KB
• Large file: > 50KB (enhanced memory management)
• Huge file: > 200KB (extended timeouts)

Watch Mode

Watch mode continuously monitors your test files and source code for changes, automatically re-running tests when files are modified.

# Basic watch mode
npx fauji --watch

# Watch with specific directory and pattern
npx fauji --dir ./src --pattern "*.test.js" --watch

# Watch with name filter
npx fauji --name "auth" --watch

Watch Mode Features

• File Monitoring: Watches test files and source files for changes
• Smart Re-runs: Only re-runs affected tests when possible
• Continuous Feedback: Provides real-time test results
• Performance: Optimized for fast re-execution

Test Filtering

By Directory

# Run tests in specific directory
npx fauji --dir ./tests

# Run tests in nested directory
npx fauji --dir ./src/components

By Pattern

# Run all test files
npx fauji --pattern "*.test.js"

# Run spec files only
npx fauji --pattern "*.spec.js"

# Run specific test pattern
npx fauji --pattern "user*.test.js"

By Name

# Run tests containing "auth" in filename
npx fauji --name "auth"

# Run tests containing "user" in filename
npx fauji --name "user"

# Case-insensitive matching
npx fauji --name "API"

Advanced Usage Examples

Complex Project Setup

# Run tests for specific module with DOM environment
npx fauji --dir ./src/components --pattern "*.test.js" --env jsdom --parallel 4

# Watch mode with optimization for large files
npx fauji --dir ./src --pattern "*.spec.js" --watch --optimization-strategy memory

# Run tests with custom file size threshold
npx fauji --max-file-size 100KB --parallel 2

# Filter and run specific test suites
npx fauji --name "integration" --env node --parallel

CI/CD Integration

# CI-friendly output with parallel execution
npx fauji --parallel 4 --env node

# Coverage collection in CI
npx fauji --coverage --parallel 2

# Specific test suite for deployment
npx fauji --name "smoke" --env jsdom

Development Workflow

# Quick test run during development
npx fauji --name "current-feature"

# Watch mode for TDD workflow
npx fauji --watch --pattern "*.test.js"

# DOM testing during component development
npx fauji --env jsdom --watch --name "component"

Exit Codes

Fauji uses standard exit codes to indicate test results:

Example: CI Integration

#!/bin/bash
# Run tests and capture exit code
npx fauji --parallel 4
TEST_EXIT_CODE=$?

# Check if tests passed
if [ $TEST_EXIT_CODE -eq 0 ]; then
  echo "✅ All tests passed"
  exit 0
else
  echo "❌ Some tests failed"
  exit 1
fi

Troubleshooting

Common Issues

Configuration File Not Found

Error: fauji.config.json not found in the project root

Solution: Create a fauji.config.json file in your project root with required configuration.

No Test Files Found

❌ No test files found in directory: ./tests

Solution: Ensure your test files match the patterns in your configuration or use --pattern to specify custom patterns.

Large File Timeout

⏰ Large file execution timeout after 30s

Solution: Use --optimization-strategy memory or split large test files into smaller ones.

Performance Tips

• Use --parallel for faster execution on multi-core systems
• Split large test files to avoid optimization overhead
• Use --name to run only relevant tests during development
• Use --watch for faster feedback during development