How to Build superfile from Source and Run Tests

Build the Go binary with ./build.sh (Linux/macOS) or go build -o bin/spf.exe (Windows), then install the Python dependencies in testsuite/ and execute python3 main.py to launch the tmux-driven integration test harness.

superfile is a modern terminal file manager written in Go by yorukot/superfile and built on the Bubble Tea framework. If you want to build superfile from source and run tests, you must compile the executable and then set up a Python-based test environment that drives a tmux session. This guide walks through both stages using the exact commands and file paths found in the repository source code.

Build the superfile Binary from Source

Linux and macOS

The project provides a helper script at the repository root that handles cross-platform compilation. Run build.sh to produce the binary at ./bin/spf:

./build.sh

Internally, build.sh executes CGO_ENABLED=0 go build -o ./bin/spf. The script detects GOOS and disables CGO on non-macOS platforms to avoid linking issues, as documented in the README Build section.

After building, optionally move the binary into your $PATH:

sudo mv ./bin/spf /usr/local/bin/spf

Windows

On Windows, compile directly with go build and specify the .exe extension:

go build -o bin/spf.exe

This command is documented in the repository README for Windows contributors who want to build superfile from source.

Prepare the Integration Test Environment

The test suite lives under testsuite/ and relies on Python 3.9+, tmux, and several Python packages to simulate UI interactions.

Install System Dependencies

Before running tests, ensure the following tools are available:

• Python 3.9 or newer — Runs the test harness (testsuite/main.py).
• tmux — Manages the terminal session in which superfile is launched (required on Linux and macOS).

Install tmux through your system package manager. For example, run brew install tmux on macOS or sudo apt-get install tmux on Debian/Ubuntu.

Create a Python Virtual Environment

From the repository root, set up an isolated environment and install the platform-conditional dependencies listed in testsuite/requirements.txt:

cd testsuite
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

This installs libtmux for tmux control, pyautogui (Linux/macOS) or pyperclip (Windows) for input simulation, and assertpy for readable assertions.

Run the superfile Test Suite

With the binary built and the virtual environment activated, launch the integration tests from the testsuite directory:

cd testsuite
python3 main.py

The Python driver in testsuite/core/ spawns a tmux session, launches the compiled spf binary, and interacts with the UI to perform end-to-end verification.

Test Runner Options and Flags

testsuite/main.py accepts several arguments, configured in its argparse block around lines 31–44:

• -d — Enables debug logging for verbose test output.
• -t RenameTest CopyTest — Runs only the specified test classes by name.
• --close-wait-time 0.5 — Adjusts the delay after closing superfile before the runner validates results (default is 0.2 seconds).
• --spf-path /path/to/spf — Points to a custom binary if you did not use the default ./bin/spf location.

Example with flags:

python3 main.py -d -t RenameTest --spf-path ../bin/spf

The runner exits with code 0 when every test passes and code 1 if any assertion fails.

Key Source Files

Understanding the layout of yorukot/superfile helps when modifying code or debugging test failures:

• main.go — Application entry point that parses CLI flags via urfave/cli/v3 and initializes the UI layer in internal/ui.
• go.mod — Declares the Go module and third-party dependencies, including the Bubble Tea framework.
• build.sh — Wrapper that sets CGO_ENABLED=0 and runs go build for Linux and macOS.
• testsuite/main.py — Test runner that parses arguments and orchestrates the suite.
• testsuite/requirements.txt — Platform-specific Python dependencies for the integration harness.

Summary

• Compile with ./build.sh (Linux/macOS) or go build -o bin/spf.exe (Windows) to generate the spf binary.
• Install Python 3.9+, tmux, and the packages in testsuite/requirements.txt inside a virtual environment.
• Execute tests with python3 main.py from the testsuite/ directory.
• Customize execution using flags like -d, -t, --close-wait-time, and --spf-path defined in testsuite/main.py.
• Verify success with exit code 0; failures return exit code 1.

Frequently Asked Questions

Does superfile require CGO to build from source?

No. The build.sh script explicitly sets CGO_ENABLED=0 when compiling for Linux and macOS to avoid platform-specific linking issues. On Windows, the standard go build -o bin/spf.exe also runs without CGO according to the README build instructions.

Can I run the tests without tmux?

No. The integration test suite in testsuite/ relies on libtmux to manage a headless terminal session. This architecture allows the Python harness to programmatically launch the spf binary and simulate keyboard input. Tmux is required on Linux and macOS.

How do I run only a specific test case?

Use the -t flag followed by the class name when invoking testsuite/main.py. For example, python3 main.py -t RenameTest runs only the rename integration test. This filter is handled by the argparse configuration near the top of the test runner.

What Python version is required to run the test suite?

The test harness requires Python 3.9 or newer. The testsuite/main.py driver and its dependencies, including libtmux and pyautogui, are validated against this version according to the testsuite documentation.

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