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

> Learn to run Go unit tests for Superfile using make test and execute the Python integration testsuite with make testsuite. Fast and easy testing for the yorukot/superfile repo.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/yorukot/superfile/blob/main/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:

```bash
go test ./...

```

The `Makefile` provides a shortcut target:

```bash
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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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:

```bash
./dev.sh --testsuite

```

Enable verbose debug output:

```bash
./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:

```bash
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:

```bash

# 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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/.github/workflows/testsuite-run.yml), which invokes `./dev.sh --testsuite` automatically on pull requests and pushes. For CI pipelines, use:

```bash
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`](https://github.com/yorukot/superfile/blob/main/testsuite/main.py) (entry point), [`testsuite/core/runner.py`](https://github.com/yorukot/superfile/blob/main/testsuite/core/runner.py) (`run_tests` function), [`testsuite/core/environment.py`](https://github.com/yorukot/superfile/blob/main/testsuite/core/environment.py) (`Environment` class), and [`testsuite/tests/rename_test.py`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/dev.sh) script handles Python dependency installation automatically via [`requirements.txt`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/dev.sh) or [`main.py`](https://github.com/yorukot/superfile/blob/main/main.py) with specific test names. The `run_tests` function in [`testsuite/core/runner.py`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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.