Testing Guide

Overview

cc-statusline uses a combination of manual testing, preview functionality, and specialized test scripts to ensure generated statuslines work correctly.

Quick Start

Build and Test

# Install dependencies
npm install

# Build the project (required before testing)
npm run build

# Test the CLI locally
./dist/index.js init --no-install
./dist/index.js preview ./test-statusline.sh

Development Workflow

1. Build the Project

Production Build
Watch Mode

npm run build

Creates optimized build in dist/ directory.

npm run dev

Automatically rebuilds on file changes during development.

2. Test CLI Commands

Test Init Command

# Test locally without installing
./dist/index.js init --no-install

# Test with custom output path
./dist/index.js init --output ./test-statusline.sh --no-install

# Test as if installed globally
npx . init

Test Preview Command

# Preview a generated statusline
./dist/index.js preview ./test-statusline.sh

# Preview with custom mock data
./dist/index.js preview .claude/statusline.sh

3. Test Generated Scripts

Direct Script Testing

# Test the generated statusline with mock data
./test_debug.sh

# Run a generated script manually
echo '{}' | ./test-statusline.sh

With Mock JSON Data

# Create mock JSON input
cat << 'EOF' > mock-input.json
{
  "workspace": { "current_dir": "/home/user/project" },
  "model": { "display_name": "Claude Sonnet", "version": "4" },
  "session_id": "test-session",
  "version": "1.0.85",
  "output_style": { "name": "default" },
  "context_window": {
    "context_window_size": 200000,
    "current_usage": {
      "input_tokens": 25000,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 1000
    }
  }
}
EOF

# Test with mock data
cat mock-input.json | ./test-statusline.sh

Preview Functionality

The preview command provides comprehensive testing before installation.

What Preview Does

Load Script

Reads your generated statusline script from disk

Generate Mock Data

Creates realistic Claude Code JSON input

Execute

Runs the script with mock data

Report

Shows output, performance metrics, and functionality status

Preview Output

$ cc-statusline preview .claude/statusline.sh

🔍 Preview of .claude/statusline.sh

━━━ Generated Output ━━━
📁 ~/Projects/cc-statusline  🌿 main  🤖 Claude Sonnet  📟 v1.0.85  🎨 default
🧠 Context Remaining: 87% [=========-]  ⌛ 3h 7m until reset at 01:00 (37%) [===-------]
💰 $2.48 ($12.50/h)  📊 25000 tok (4200 tpm)

━━━ Performance ━━━
⚡ Execution time: 67ms
✓ jq available
✓ git available
✓ All features working

Specialized Test Scripts

Installation Tests

# Run installation tests
./test/test-installation.sh

Tests the complete installation flow:

File creation
Permission setting
Settings.json updates
Configuration validation

Locking Mechanism Tests

The ccusage integration includes file-based locking to prevent concurrent process spawning.

Single Test
Concurrent Test
Manual Stress Test

echo '{}' | ./test/test-statusline-with-lock.sh

Tests single execution with lock file handling.

./test/test-concurrent-locking.sh

Tests multiple simultaneous executions.

# Spawn 10 concurrent processes
for i in {1..10}; do 
  echo '{}' | ./test/test-statusline-with-lock.sh & 
done

Verifies lock mechanism under load.

Expected Locking Behavior

Single Process Execution

Only 1 process runs ccusage at a time, preventing resource pile-up

Graceful Skipping

Other processes skip ccusage gracefully without blocking or errors

Lock Cleanup

Lock files are properly cleaned up after execution

No Hanging Processes

All processes complete without hanging or orphaned children

Verification Commands

# Check for stale locks
ls /tmp/ccusage_statusline.* 2>/dev/null || echo "✅ No locks remain"

# Monitor running processes
ps aux | grep ccusage | grep -v grep

# Check lock file age (should be recent or not exist)
find /tmp -name "ccusage_statusline.*" -mmin +5

Manual Testing Checklist

Feature Testing

Directory Display
Git Integration
Context Tracking
Color Support

# Test directory abbreviation
cd ~/Projects/test
echo '{"workspace":{"current_dir":"'$HOME'/Projects/test"}}' | ./test-statusline.sh
# Should show: ~/Projects/test

# Test in git repository
cd /path/to/git/repo
git checkout -b test-branch
echo '{}' | ./test-statusline.sh
# Should show: test-branch

# Test with high context usage
cat << 'EOF' | ./test-statusline.sh
{
  "context_window": {
    "context_window_size": 200000,
    "current_usage": {"input_tokens": 180000}
  }
}
EOF
# Should show red color (10% remaining)

# Test with colors enabled
./test-statusline.sh < mock-input.json

# Test with NO_COLOR
NO_COLOR=1 ./test-statusline.sh < mock-input.json
# Should have no ANSI color codes

Error Conditions

Test graceful degradation:

# Test without jq
PATH="" ./test-statusline.sh < mock-input.json

# Test without git
(cd /tmp && echo '{}' | /path/to/test-statusline.sh)

# Test with invalid JSON
echo 'invalid json' | ./test-statusline.sh

# Test with empty input
echo '' | ./test-statusline.sh

Performance Testing

Execution Time

# Measure execution time
time (echo '{}' | ./test-statusline.sh)

# Target: < 100ms
# Typical: 45-80ms

Resource Usage

# Monitor memory usage
/usr/bin/time -v ./test-statusline.sh < mock-input.json

# Check for process leaks
ps aux | grep statusline
# Should be empty after execution

Integration Testing

Test in Real Claude Code

Install Locally

npm run build
./dist/index.js init

Restart Claude Code

Close and reopen Claude Code terminal

Verify Output

Check that statusline appears at terminal prompt

Test All Features

Change directories
Switch git branches
Monitor costs over time
Check context updates

Settings Validation

# Verify settings.json was updated correctly
cat .claude/settings.json | jq .statusLine

# Expected output:
# {
#   "type": "command",
#   "command": ".claude/statusline.sh",
#   "padding": 0
# }

Debugging

Enable Logging

Generate statusline with logging enabled:

# During init, select "Enable debug logging"
cc-statusline init

# Or edit generated script to add logging

View logs:

# Check statusline logs
tail -f .claude/statusline.log

# View with timestamps
tail -f .claude/statusline.log | grep -E '^\['

Common Issues

Statusline not showing

# Check script permissions
ls -la .claude/statusline.sh
# Should be executable: -rwxr-xr-x

# Fix permissions
chmod +x .claude/statusline.sh

# Verify settings.json
cat .claude/settings.json | jq .statusLine

Features not working

# Check jq availability
which jq
jq --version

# Check git availability
which git
git --version

# Test with mock data
./dist/index.js preview .claude/statusline.sh

Performance issues

# Measure execution time
time (echo '{}' | .claude/statusline.sh)

# If > 500ms, disable heavy features:
# - ccusage integration
# - session timer
# - token tracking

Test Coverage Areas

When adding new features, test:

✅ With jq: Full functionality
✅ Without jq: Graceful fallback
✅ With colors: Proper ANSI codes
✅ Without colors: Clean output
✅ In git repo: Git features work
✅ Outside git: Git features skip gracefully
✅ With ccusage: Usage tracking works
✅ Without ccusage: Usage features skip
✅ Invalid JSON: No crashes
✅ Empty input: Sensible defaults

Development

Integration

Overview

Quick Start

Build and Test

Development Workflow

1. Build the Project

2. Test CLI Commands

Test Init Command

Test Preview Command

3. Test Generated Scripts

Direct Script Testing

With Mock JSON Data

Preview Functionality

What Preview Does

Preview Output

Specialized Test Scripts

Installation Tests

Locking Mechanism Tests

Expected Locking Behavior

Verification Commands

Manual Testing Checklist

Feature Testing

Error Conditions

Performance Testing

Execution Time

Resource Usage

Integration Testing

Test in Real Claude Code

Settings Validation

Debugging

Enable Logging

Common Issues

Test Coverage Areas

Next Steps

Contributing

Architecture

Build docs developers (and LLMs) love

Development

Integration

​Overview

​Quick Start

​Build and Test

​Development Workflow

​1. Build the Project

​2. Test CLI Commands

​Test Init Command

​Test Preview Command

​3. Test Generated Scripts

​Direct Script Testing

​With Mock JSON Data

​Preview Functionality

​What Preview Does

​Preview Output

​Specialized Test Scripts

​Installation Tests

​Locking Mechanism Tests

​Expected Locking Behavior

​Verification Commands

​Manual Testing Checklist

​Feature Testing

​Error Conditions

​Performance Testing

​Execution Time

​Resource Usage

​Integration Testing

​Test in Real Claude Code

​Settings Validation

​Debugging

​Enable Logging

​Common Issues

​Test Coverage Areas

​Next Steps

Contributing

Architecture

Build docs developers (and LLMs) love

Overview

Quick Start

Build and Test

Development Workflow

1. Build the Project

2. Test CLI Commands

Test Init Command

Test Preview Command

3. Test Generated Scripts

Direct Script Testing

With Mock JSON Data

Preview Functionality

What Preview Does

Preview Output

Specialized Test Scripts

Installation Tests

Locking Mechanism Tests

Expected Locking Behavior

Verification Commands

Manual Testing Checklist

Feature Testing

Error Conditions

Performance Testing

Execution Time

Resource Usage

Integration Testing

Test in Real Claude Code

Settings Validation

Debugging

Enable Logging

Common Issues

Test Coverage Areas

Next Steps