How to Run Tests for Superfile: Unit Tests and Full Integration Suite

TLDR: Execute Go unit tests with make test (runs go test ./...) and the Python integration testsuite with make testsuite (invokes ./dev.sh --testsuite), which automatically builds a virtual environment, installs dependencies, and drives the compiled spf binary through simulated keyboard inputs in a real terminal.

Superfile (yorukot/superfile) maintains code quality through a rigorous two-tier testing strategy that covers both isolated package logic and end-to-end UI interactions. The repository provides automated orchestration via the dev.sh script and convenient Makefile targets, allowing contributors to validate changes using either fast Go tests or the comprehensive Python-driven integration framework.

Running Unit Tests (Fast Go Tests)

Unit tests are standard Go tests located in *_test.go files throughout the repository. These validate individual package logic without initializing the user interface.

To execute all unit tests, run:

go test ./...

The Makefile provides a shortcut target:

make test

This command compiles and executes tests across all packages. According to the source code in the Makefile, this is the fastest way to verify logic changes during development cycles.

Running the Integration Testsuite (Full UI Tests)

The integration testsuite resides in the testsuite/ directory and validates the actual compiled binary through real terminal interactions. It launches spf using tmux on Unix or PyAutoGUI on Windows, then simulates key presses to verify UI behavior.

Test Architecture and Key Components

The Python framework follows a modular design with specific responsibilities divided across modules:

• Entry Point – testsuite/main.py parses CLI flags (--debug, --spf-path, --use-global-env), creates a TestFSManager instance for temporary directory management, and instantiates the appropriate SPFManager (TmuxSPFManager for Unix, PyAutoGuiSPFManager for Windows).
• Core Runner – testsuite/core/runner.py contains the run_tests function, which constructs the Environment, discovers all *_test.py files via get_testcases, and orchestrates the three-phase test lifecycle: setup → test_execute → validate → cleanup.
• Environment Management – testsuite/core/environment.py combines the SPFManager (controlling the running spf process) with the TestFSManager (providing isolated file trees), ensuring single-point cleanup after each test.
• Test Implementation – Files like testsuite/tests/rename_test.py demonstrate the pattern: declare an initial file tree, specify key sequences to send, and assert final filesystem state (existence or absence of specific paths).

Using the dev.sh Script

The dev.sh script automates environment setup and execution. Referencing lines 25-91 and 74-92, it performs:

1. Virtual Environment Creation – Initializes testsuite/venv unless --use-global-env is passed.
2. Dependency Installation – Runs pip install -r requirements.txt to fetch libtmux, pyautogui, and supporting libraries.
3. Binary Validation – Ensures the spf binary exists in bin/.
4. Test Execution – Invokes python3 main.py with appropriate flags.

Run the full suite:

./dev.sh --testsuite

Enable verbose debug output:

./dev.sh --testsuite --debug

The script returns exit code 0 on success and non-zero on failure, suitable for CI integration.

Using Makefile Shortcuts

For the complete validation workflow:

make testsuite

This target builds the Go binary (via make build) then executes ./dev.sh --testsuite with FORCE_COLOR=1. It is the recommended one-command solution for pre-commit verification.

Manual Execution

For direct control without the wrapper script:

# Build required binary

make build

cd testsuite

# Run with defaults (uses ../bin/spf)

python3 main.py

# Run with debug logging

python3 main.py --debug

# Use specific binary path

python3 main.py --spf-path /custom/path/to/spf

The argument parser in main.py accepts -d/--debug for verbose logging and --spf-path to override the default binary location.

Continuous Integration Configuration

The repository includes .github/workflows/testsuite-run.yml, which invokes ./dev.sh --testsuite automatically on pull requests and pushes. For CI pipelines, use:

FORCE_COLOR=1 ./dev.sh --testsuite

This ensures colorized output while preserving the exit status required for GitHub Actions success/failure reporting.

Summary

• Unit tests (make test) execute go test ./... for fast package-level validation without UI components.
• Integration tests (make testsuite) run the Python framework in testsuite/ to verify the compiled spf binary through real terminal sessions.
• dev.sh automates Python virtual environment creation, dependency installation, and test execution.
• Key files: testsuite/main.py (entry point), testsuite/core/runner.py (run_tests function), testsuite/core/environment.py (Environment class), and testsuite/tests/rename_test.py (example implementation).
• Exit codes are reliable across all commands, returning 0 only when all tests pass.

Frequently Asked Questions

What are the system requirements for running Superfile tests?

Running the complete suite requires Go (for compilation and unit tests) and Python 3 with pip (for the integration framework). Unix systems need tmux installed to manage terminal sessions, while Windows relies on PyAutoGUI. The dev.sh script handles Python dependency installation automatically via requirements.txt, creating an isolated virtual environment unless --use-global-env is specified.

How do I run only specific integration tests?

Filter test execution by passing the --tests flag to dev.sh or main.py with specific test names. The run_tests function in testsuite/core/runner.py accepts an only_run_tests parameter that limits discovery to matching *_test.py files, executing only the specified classes that inherit from BaseTest and skipping the rest of the suite.

Why does the integration testsuite require a compiled binary?

The integration suite validates the actual user interface by launching the spf executable in a real terminal session (tmux or PyAutoGUI window) rather than importing Go packages directly. As implemented in testsuite/core/environment.py, the SPFManager interface controls this running process while TestFSManager provides temporary filesystem isolation, ensuring tests cover the complete application including terminal rendering and input handling.

How do I debug failing integration tests?

Enable verbose logging with the --debug flag (./dev.sh --testsuite --debug or python3 main.py --debug). This activates detailed output showing the three-phase lifecycle (setup, test_execute, validate, cleanup) and any exceptions raised by the SPFManager. For filesystem-related failures, inspect the temporary directories created by TestFSManager to verify initial state and final assertions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}