Skip to content

TESTING.md

Latest commit

 

History

History
187 lines (131 loc) · 4.46 KB

TESTING.md

File metadata and controls

187 lines (131 loc) · 4.46 KB

Caffeinate Test Suite

This document describes how to use the comprehensive test suite for caffeinate-linux.

Quick Start

# Run all tests
./test_caffeinate.sh

# Run tests with verbose output
bash -x ./test_caffeinate.sh

Test Categories

The test suite covers the following categories:

1. Pre-flight Checks

  • Verifies the caffeinate script exists and is executable

2. Basic Functionality Tests

  • Help flag (-h)
  • Default behavior (no arguments)

3. Individual Flag Tests

  • -i (idle prevention)
  • -d (display sleep prevention)
  • -s (system sleep prevention - AC only)
  • -u (user activity simulation)
  • -v (verbose output)
  • -t (timeout)

4. Flag Combination Tests

  • -d -s (display + system sleep prevention)
  • -d -i (display + idle prevention)
  • -s -i (system + idle prevention)
  • -d -s -i (all sleep prevention)
  • -d -s -u (display + system + user activity)
  • All flags together
  • Timeout combinations (-d -t, -s -t, -d -s -t)

5. Command Execution Tests

  • Execute commands with caffeinate
  • Execute with various flags

6. PID Waiting Tests

  • Wait for process completion

7. Error Condition Tests

  • Invalid timeout values
  • Invalid PID values
  • Invalid flags

8. Verbose Output Tests

  • Verify verbose logging format

9. Non-GUI Environment Tests

  • Test behavior in headless/SSH sessions

10. Cleanup Functionality Tests

  • Verify proper resource cleanup on exit

11. AC Power Detection Tests

  • Verify AC power detection works correctly

Test Output

The test script provides color-coded output:

  • ✅ PASS (green): Test passed successfully
  • ❌ FAIL (red): Test failed
  • ⚠️ SKIP (yellow): Test was skipped
  • ℹ️ INFO (yellow): Informational messages

Running Specific Tests

You can run specific test categories by modifying the script or commenting out sections you don't want to run.

Continuous Integration

For CI/CD pipelines, use:

# Exit with non-zero status if any test fails
./test_caffeinate.sh

# Continue even if tests fail (for reporting)
bash test_caffeinate.sh || true

Test Requirements

  • Bash 4+ (for the test script)
  • Standard Linux utilities (timeout, grep, etc.)
  • The same dependencies as caffeinate itself

Adding New Tests

To add new tests:

  1. Add test functions following the existing pattern
  2. Use run_test for simple exit code tests
  3. Use log_pass, log_fail, log_skip for custom tests
  4. Update the summary section

Debugging Failed Tests

If tests fail:

  1. Check the detailed output for specific failures
  2. Run with bash -x for verbose debugging: 
    bash -x ./test_caffeinate.sh
  3. Check temporary test files in /tmp/caffeinate_test_*

Test Maintenance

Update tests when:

  • New features are added to caffeinate
  • Bug fixes are implemented
  • New compatibility requirements are identified

Compatibility Testing

For testing across different environments:

# Test in different desktop environments
XDG_SESSION_TYPE=wayland ./test_caffeinate.sh
XDG_SESSION_TYPE=x11 ./test_caffeinate.sh

# Test in non-GUI environment
XDG_SESSION_TYPE=tty DISPLAY= WAYLAND_DISPLAY= ./test_caffeinate.sh

Expected Test Results

All tests should pass on a properly configured system with:

  • systemd
  • D-Bus
  • X11 or Wayland session
  • AC power (for -s flag tests)

Test Results Summary

  • Total tests: 30
  • Expected pass: 29
  • Expected skip: 1 (PID waiting test due to race conditions)
  • Expected fail: 0

Known Limitations

  1. PID waiting test: This test is skipped due to race conditions in the test environment. The -w flag functionality works correctly when tested manually.

  2. Filesystem restrictions: If running from a noexec mounted filesystem, scripts must be executed with bash script.sh instead of ./script.sh.

  3. Container environments: Some tests may behave differently in containers without proper D-Bus or systemd support.

Manual Testing Recommendations

For comprehensive testing, also manually verify:

# Test PID waiting functionality (known to work but hard to test automatically)
sleep 10 & bash caffeinate -w $! -v

# Test in different desktop environments
# Test on battery power (if available)
# Test in VMs and containers

Continuous Integration Setup

Example CI configuration:

# GitHub Actions example
- name: Run caffeinate tests
  run: bash test_caffeinate_fixed.sh

# GitLab CI example
test:
  script:
    - bash test_caffeinate_fixed.sh