armada

Repository for integration tests of the Equinor Flotilla robotics system. The term armada points to the integration tests deploying a large number of containers beyond the ones provided by Flotilla to perform full integration tests.

Purpose

The integration tests shall replicate normal operation and error situations that can occur for a robot mission in Flotilla and determine whether the system handles the situation as expected. Whenever changes are made to the system, the integration tests will execute to verify that the behavior remains consistent.

The following components are currently included in the integration tests:

• Flotilla Backend (C#)
• Flotilla Broker (mosquitto mqtt broker)
• PostgreSQL database
• Azure Blob Storage (emulated with Azurite)
• ISAR Robot (your friendly neighbourhood mocked robot which provides the answers you need)

Run the integration tests through remote workflow call

To run the integration tests in a remote repository, this workflow has been set up.

In your repository, setup the following workflow:

name: Run integration tests

on:
  push:
    branches: [ main ]
  release:
    types: [ published ]
  workflow_dispatch:
    inputs:
      lane:
        description: "dev or latest"
        required: true
        default: latest

permissions:
  contents: read
  packages: read

jobs:
  run-integration-tests:
    uses: equinor/armada/.github/workflows/run_integration_tests.yml@main
    with:
      # Pick lane automatically based on event, or honor manual input
      lane: ${{ github.event_name == 'push' && 'dev'
            || github.event_name == 'release' && 'latest'
            || github.event_name == 'workflow_dispatch' && inputs.lane
            || 'latest' }}

    secrets:
      INTEGRATION_TEST_AZURE_CLIENT_SECRET: ${{ secrets.INTEGRATION_TEST_AZURE_CLIENT_SECRET }}

This snippet will enable you to run the integration tests manually and automatically on push to main and published release. It requires the following secret to be set in your repository secrets:

INTEGRATION_TEST_AZURE_CLIENT_SECRET

The input lane determines which image tag should be applied to the internally developed packages like Flotilla and ISAR. If input is set as lane=dev the newest development images (corresponding to newest push to main branch) will be used while lane=latest will use the newest release.

Local development

Clone the repository and install dependencies with uv:

uv sync

Ensure the following secrets are populated in your local environment, either as environment variables or in a .env file in the repository root directory.

INTEGRATION_TESTS_CLIENT_SECRET
FLOTILLA_AZURE_CLIENT_SECRET
FLOTILLA_BROKER_SERVER_KEY
FLOTILLA_MQTT_PASSWORD
ISAR_AZURE_CLIENT_SECRET
ISAR_MQTT_PASSWORD
SARA_AZURE_CLIENT_SECRET
SARA_MQTT_PASSWORD

They may all be found in the integration test keyvault.

You may now run the tests with

uv run pytest -s .

Running against locally built images

By default the tests pull ghcr.io/equinor/{flotilla-backend,sara,isar-robot}. A change that spans armada and one of those services therefore cannot be verified until the service change is merged and an image published — even though the armada side is what proves the service side works.

To close that gap, build the images from your local working copies:

scripts/build_local_images.sh           # build and verify
scripts/build_local_images.sh --run     # ... and run the full suite against them

The script expects the sibling checkouts of the superrepo (../isar, ../isar-robot, ../flotilla, ../sara); override with ISAR_DIR, ISAR_ROBOT_DIR, FLOTILLA_DIR, SARA_DIR. It verifies each image before handing back, because a subtly broken build otherwise shows up only as an unexplained timeout several minutes into the suite.

The database schema is taken from the same local checkouts, via FLOTILLA_MIGRATIONS_SOURCE_DIR and SARA_MIGRATIONS_SOURCE_DIR, so application code and schema always agree. The directory is mounted read-only and copied into the migrations container, which means uncommitted and untracked migrations are picked up. Set either variable on its own if you want to mix a local schema with published images.

Two things worth knowing:

• flotilla, sara and isar are built from the working tree, so uncommitted changes are included. isar-robot is cloned, so only committed changes are — the script warns if that checkout is dirty. It has to be cloned because its Dockerfile bind-mounts .git, and in the superrepo that is a submodule file rather than a directory.
• isar-robot's uv.lock pins isar from PyPI, so the locally built isar wheel is installed over the released one.

The mosquitto broker is always the published image.