The GattLab contract language

What a contract is

A contract is a plain YAML file describing the behavior you expect from a BLE peripheral - what it should advertise as, which GATT service it must expose, and optionally which characteristics you want to write to and what response you expect back. The exact same text is parsed identically whether you validate it in the console, dispatch it from the Manager, or bundle it locally in GattLab Agent - one parser, one schema.

Keys are written with underscores (advertised_name, not advertisedName).

A complete example

This is the default contract used throughout GattLab - a Nordic Blinky-flashed nRF52840 with an LED characteristic and an echo characteristic.

suite: nrf52840-smoke
target:
  advertised_name: "Nordic_Blinky"
  name_match: prefix        # exact | prefix
  service_uuid: "00001523-1212-efde-1523-785feabcd123"
  characteristic_steps:
    - name: "LED on"
      type: write
      characteristic_uuid: "00001525-1212-efde-1523-785feabcd123"
      value_hex: "01"
    - name: "LED off"
      type: write
      characteristic_uuid: "00001525-1212-efde-1523-785feabcd123"
      value_hex: "00"
    - name: "Echo roundtrip (notify)"
      type: write_expect_response
      characteristic_uuid: "00001526-1212-efde-1523-785feabcd123"
      value_hex: "AA55"
      expected_value_hex: "AA55"
      response_mode: notify_other
      response_characteristic_uuid: "00001527-1212-efde-1523-785feabcd123"
      timeout_seconds: 5
settings:
  scan_timeout_seconds: 15
  connect_timeout_seconds: 10

suite is a label only - it's never used by the runner, it just shows up as the "Suite" column in history.

Schema reference

Top level

target.*

settings.*

characteristic_steps[].*

The three fixed checks

Every run always executes these three, in order, before any characteristic_steps:

If a device is never discovered, Connects and Required GATT service exists both report Skipped - device was not discovered. instead of running. If the connection fails, the service check reports Skipped - connection failed.

Characteristic step types

Each entry in target.characteristic_steps runs after the three fixed checks, only if the required service was found - in the order they're listed.

write

Writes value_hex to the characteristic and passes if the write completes without a GATT error.

- name: "LED on"
  type: write
  characteristic_uuid: "00001525-1212-efde-1523-785feabcd123"
  value_hex: "01"

write_expect_response - response_mode: read

Writes, then reads the same characteristic back and compares bytes.

- name: "Echo roundtrip (read-back)"
  type: write_expect_response
  characteristic_uuid: "00001526-1212-efde-1523-785feabcd123"
  value_hex: "AA55"
  expected_value_hex: "AA55"
  response_mode: read

write_expect_response - response_mode: notify_same

Subscribes to the same characteristic before writing, then waits for a notification carrying the expected bytes.

- name: "Echo roundtrip (notify, same characteristic)"
  type: write_expect_response
  characteristic_uuid: "00001526-1212-efde-1523-785feabcd123"
  value_hex: "AA55"
  expected_value_hex: "AA55"
  response_mode: notify_same
  timeout_seconds: 5

write_expect_response - response_mode: notify_other

Subscribes to a different characteristic (response_characteristic_uuid) before writing, then waits for the notification there.

- name: "Echo roundtrip (notify, other characteristic)"
  type: write_expect_response
  characteristic_uuid: "00001526-1212-efde-1523-785feabcd123"
  value_hex: "AA55"
  expected_value_hex: "AA55"
  response_mode: notify_other
  response_characteristic_uuid: "00001527-1212-efde-1523-785feabcd123"
  timeout_seconds: 5

Subscribing happens before the write in both notify modes, specifically so a fast notification can't race ahead and be missed.

Failure details you'll see

Reading results

Every step - the 3 fixed checks plus each characteristic step - becomes one row: a name, a PASS/FAIL chip, a duration, and a detail message. The overall run is PASSED only if every step passed (OverallPassed = steps.All(passed)) - there's no partial-credit state.

A detail starting with Skipped - means a prior step's failure prevented this one from running at all, not that this specific check failed on its own.

Error reference

These are the exact messages the API returns when a contract can't be dispatched at all:

CI integration

Your CI runner never needs a Bluetooth radio. It dispatches a contract to GattLab, and the devices in your lab - the ones running the Agent app - execute it and report back. A GitHub-hosted runner can drive a phone sitting on a shelf in your office.

1. Mint an API token

Go to API tokens and create one. It's shown once; store it as a repository secret named GATTLAB_TOKEN. A token is separate from your login and can be revoked on its own, so a secret sitting in a build system stays under your control.

2. Add the step to your workflow

- uses: Umer-Mahmood/TestLabX/.github/actions/gattlab-run@main
  with:
    contract: tests/blinky.yaml
    agents: android,windows
    token: ${{ secrets.GATTLAB_TOKEN }}
    junit: results/junit.xml

agents is a list of platforms - android, windows, ios - and each one resolves to every online device of that platform on your account. The step fails if a platform you asked for has no device online.

Not on GitHub Actions? cli/gattlab.sh is a plain shell script over curl and jq; run it from any CI system.

3. Read the result

The step writes a JUnit XML report your CI can render as checks and annotations, appends a results table to the GitHub job summary, and exits non-zero when a device fails. The exit code distinguishes a real regression from a lab problem:

Three things to know before you rely on it

Not yet supported