Leviathan

Leviathan can be used to automate, test and control real/virtual devices in production or controlled environments. What can you do:

1. Stress testing the provisioning process for reliability, performance & fault tolerance.
2. Testing new balenaOS, balenaEngine and balena supervisor on different board revisions, prod/staging environments for managed and unmanaged scenarios.
3. Automate release deployment for balenaCloud fleets by testing codebase on real/virtual devices under test.
4. Automate support for new modems, sensors, components and eventually new boards.

The high-level overview of the leviathan architecture can be found here

Getting Started

Leviathan allows for running tests on a device controlled by a worker. A worker is a component that provides an interface to a device under test (DUT). The worker can be either real hardware or a virtualised environment. Leviathan is designed to work with multiple workers. At the moment, leviathan supports testbot(deprecated), autokit and qemu workers. Learn more about Leviathan.

Clone the repository

• Clone this repository with git clone --recursive or
• Run git clone and then git submodule update --init --recursive to install submodules.

Prerequisites

• Install Docker, node and npm in your system. We recommend installing LTS versions from NVM.
• Download the balenaOS image you want to test on your DUT from balena.io/os.

Worker setup

Leviathan allows for running tests on a device under test (DUT) connected to and controlled by either a testbot worker, or on a virtualized device using the QEMU worker. Check out the following getting started guides to setup and run each type of worker.

1. Testbot worker
2. QEMU worker
3. Autokit worker

Instructions for rig-owners

Leviathan is made up of a client and worker. The client is the test runner while the worker is where tests get executed. For testbot workers, the worker component exists on the testbot device. The testbot devices are part of a balenaCloud fleet. In order to update the worker component for testbot workers, you need to push a new release to the testbot fleet.

To push a new release of leviathan to balenaCloud, use the following command:

balena push <fleetName>

The <fleetName> is the name of the fleet you intend to push a new version of leviathan to. Keep in mind, the client and the test that run are independent of the worker. Hence, updates to the client or the tests don't need to be pushed to the balenaCloud fleet. In order to change the worker component, you need to push a new release to the balenaCloud fleet.

Documentation for Leviathan Helpers

Documentation for Leviathan helpers can be found on https://balena-os.github.io/leviathan. To generate the documentation, run the following command from either the root of the repository or the core directory.

npm install
npm run docs

If the docs are generated successfully, you will be getting the success line as:

Info: Documentation generated at /path/to/documentation

Support

If you're having any problem, please raise an issue on GitHub and the balena team will be happy to help.

License

The project is licensed under the Apache 2.0 license.