Setting Up Your Repository

Before deploying to a balena fleet, create a project repository for your test runner from the FixturFab Cookiecutter F3TS Runner template. The template scaffolds the project structure, an example test plan, and the balena configuration needed to build and deploy the Test Runner.

Install Cookiecutter

Install or update Cookiecutter to the latest version:

pip install -U cookiecutter

Generate the Project

Run the following command in the directory where you want the project created. Cookiecutter will clone the template and prompt you for the project variables:

cookiecutter https://gitlab.com/fixturfab/software/cookiecutter-f3ts-runner

Template Variables

The generator prompts for the following parameters:

Parameter	Default	Purpose
project_name	Python Project	Your project's name.
organization	FixturFab	Organization name used for licensing.
minimal_python_version	3.10	Minimum supported Python version (3.10, 3.11, or 3.12).
full_name	Full Name	Author name written into project files.
test_plan_name	Example Test Plan	Name of the initial test plan.
email	Based on organization	Project ownership email.
version	0.1.0	Initial version (follows Semantic Versioning).
line_length	88	Maximum characters per line (50–300).
first_superuser	Based on organization	Initial admin username.
first_superuser_password	password	Initial admin password.
first_operator	Based on organization	Initial operator username.
first_operator_password	password	Initial operator password.

All values you enter are saved to cookiecutter-config-file.yml in the generated project for future reference.

Change default passwords

Replace the password defaults for first_superuser_password and first_operator_password with strong, unique values before deploying to a shared or production fleet.

Project Structure

The template generates a project laid out like the example below. The top-level project folder and the inner Python package are both named after your project_name, and each test plan lives in a folder named after its test_plan_name:

my-test-runner/
├── docker-compose.yml            # Multi-container definition deployed to balena
├── pytest-f3ts-api.dockerfile    # Build for the pytest-f3ts-api service
├── worker.dockerfile             # Build for the test worker service
├── pyproject.toml                # Project dependencies and metadata
├── mkdocs.yml                    # Project documentation site config
├── .env                          # Local environment variables
├── .gitlab-ci.yml                # CI/CD pipeline (build & deploy)
├── .pre-commit-config.yaml
├── README.md
├── docs/                         # Project documentation (MkDocs)
│   ├── index.md
│   ├── users_guide.md
│   ├── running_tests.md
│   ├── test_plan.md
│   ├── interface.md
│   ├── conftest.md
│   ├── data_logging.md
│   ├── software_approach.md
│   ├── assets/                   # Logos and images
│   └── resources/                # Stylesheets and PDF cover templates
├── macros/
│   └── __init__.py
└── my-test-runner/               # Python package (named after your project)
    └── test_plans/
        └── example-test-plan/    # One folder per test plan
            ├── test_plan.py      # Test cases
            ├── interface.py      # Hardware / instrument interface
            ├── conftest.py       # pytest fixtures
            ├── config.yml        # Test plan configuration
            ├── pyproject.toml
            └── __init__.py

The docker-compose.yml and the *.dockerfile files define the services that balena builds and deploys (see the Overview), while the test_plans/ directory holds the pytest-f3ts test plans the Test Runner executes.

Next Steps

Once the project has been generated, change into the new project directory and finish setting it up:

1. Initialize Git — run git init.
2. Install dependencies — run poetry install.

With the repository in place, you can start writing your fixture's Test Plan or deploy a release as described in Deploying to a Device.