Testflinger

Testflinger is a system for orchestrating time-shared access to a pool of target machines.

Each Testflinger system consists of:

  • a web service (called just Testflinger) that provides an API to request jobs by placing them on a queue

  • per-machine agents that wait for jobs to be placed on queues they can service and then process them

Jobs can be either fully automated scripts that can attempt to complete within the allocated time or interactive shell sessions.

The Testflinger system is particularly useful for sharing finite machine resources between different consumers in a predictable fashion.

Typically this has been used for managing a test lab where CI/CD test runs and also exploratory testing by human operators is desired.

In this documentation

First steps

Install the client, run your first job, and learn the core workflow.

Jobs

The core unit of work: how a job is described, run, and used to reserve a machine.

Queues, agents, and agent hosts

Queues route jobs to compatible agents to provision and operate the devices under test, and report the results. Agents run on agent hosts, which are VMs deployed with Juju.

Device connectors

Agents invoke device connectors to provision and operate devices under test (DUT). Each connector supports a particular provisioning type.

Server

A Kubernetes application that stores data, serves the API, and coordinates the system.

Access and permissions

Prove client identity and control what each client is allowed to do.

Security

How Testflinger protects credentials and data, and how to handle secrets safely.

How this documentation is organised

This documentation uses the Diátaxis documentation structure.

  • Tutorial takes you step-by-step through submitting your first job with Testflinger.

  • How-to guides provide instructions for specific tasks like submitting jobs, reserving machines, and administering a deployment.

  • Reference provides technical specifications: job schemas, configuration files, and the REST API.

  • Explanation provides conceptual context about architecture, queues, security, and reservation.

Project and community

Testflinger is a member of the Ubuntu family. It is an open source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback.