# How to Build superfile from Source and Run Tests > Learn to build superfile from source and run its tests. Follow simple Go build and Python script execution steps for a smooth setup. - Repository: [Yorukot/superfile](https://github.com/yorukot/superfile) - Tags: how-to-guide - Published: 2026-07-26 --- **Build the Go binary with [`./build.sh`](https://github.com/yorukot/superfile/blob/main/./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`](https://github.com/yorukot/superfile/blob/main/build.sh) to produce the binary at `./bin/spf`: ```bash ./build.sh ``` Internally, [`build.sh`](https://github.com/yorukot/superfile/blob/main/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`: ```bash sudo mv ./bin/spf /usr/local/bin/spf ``` ### Windows On Windows, compile directly with `go build` and specify the `.exe` extension: ```bash 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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/testsuite/requirements.txt): ```bash 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: ```bash 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`](https://github.com/yorukot/superfile/blob/main/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: ```bash 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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/build.sh)** — Wrapper that sets `CGO_ENABLED=0` and runs `go build` for Linux and macOS. - **[`testsuite/main.py`](https://github.com/yorukot/superfile/blob/main/testsuite/main.py)** — Test runner that parses arguments and orchestrates the suite. - **[`testsuite/requirements.txt`](https://github.com/yorukot/superfile/blob/main/testsuite/requirements.txt)** — Platform-specific Python dependencies for the integration harness. ## Summary - **Compile** with [`./build.sh`](https://github.com/yorukot/superfile/blob/main/./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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/testsuite/main.py) driver and its dependencies, including `libtmux` and `pyautogui`, are validated against this version according to the testsuite documentation.