LIFT.YAML(1)

📦
version 2.6.2 · 2 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 LIFT.YAML(1) — the Lift Manual, bestie edition 💖

okay so. welcome to lift.yaml, the file that tells Lift what your test suite actually is. this is the <pink>lift.yaml</pink> page from the Lift manual, and yeah it's a whole vibe. sit down, grab a strawberry 🍓, we're doing this.

✨ NAME ✨

lift.yaml — define a Lift test suite. that's it. that's the whole job. iconic. 👑

🌸 DESCRIPTION 🌸

okay so Lift is an integration/functional test platform, and the way it works is it handles executable tests easily and generically. no cap. 💅

lift.yaml files are literally how you define a test suite. you write one in YAML ( http://yaml.org/ ) and it supports 3 root section types:

  1. settings
  2. local tests
  3. remote tests

and all three are documented further down this very page, bestie. keep scrolling. 🫶

so a Lift test suite is made of at least one lift.yaml file — but honestly? it's usually a whole folder hierarchy with one lift.yaml at each level. it's giving organizational queen. 🎀

and why would you do that hierarchy thing? because it lets you define more specialized sub-suites, like:

  • one for basic functionalities
  • one for performances
  • literally whatever your heart desires

each sub-suite gets its own lift.yaml and can be run individually. independent. self-sufficient. main character energy. ✨

and here's the tea: settings you define on a lift.yaml file are inherited in sub-suites. and sub-suites can override those inherited settings if they need to. the family tree respects itself but also knows when to do its own thing. 💜

🎀 SETTINGS DEFINITION 🎀

this section is for two things, bestie:

  • defining remote machines that you'll use for remote tests
  • defining environment variables that get passed to your tests

and the cute part? environment variables can be overridden for each test individually in that test's own definition. per-test customization, slay. 💅

the settings section has to be defined at the root of the lift.yaml file. no nesting it somewhere weird. root. periodt.

settings:
    # The 'define' keyword followed by the remote name
    define my_remote:
        host: localhost  # mandatory
        username: root  # mandatory
        password: foobar  # optional (if ssh keys are set properly)
    define my_other_remote:
        host: localhost
        username: not_root
        password: foobar
    # These will be transmitted to the test commands
    # They can be used as a way to pass common settings around
    environment:
        MY_ENV_VAR1: foo
        MY_ENV_VAR2: bar

quick breakdown of that block so nothing flies past you:

  • host — mandatory, no host no remote
  • username — mandatory too
  • password — optional! only needed if your ssh keys aren't set up properly. if they are? you're free. 🦋
  • environment — these get transmitted to the test commands, and they're a great way to pass common settings around. lowkey the move.

💅 LOCAL TEST DEFINITION 💅

every test = a single section at the root of the lift.yaml file. that's the rule. here's the example, look at her:

# the 'test' keyword followed by the test name
test my_test_name:
    command: "./my_test_executable --my-arg"  # mandatory
    return code: 0  # optional (default to 0)
    timeout: 10  # optional, in seconds (no timeout by default)
    environment:  # optional
        MY_VAR: 42  # may override an already defined variable

okay so what's what:

  • command — mandatory. this is the actual thing that runs.
  • return code — optional, and it defaults to 0
  • timeout — optional, measured in seconds, and there's no timeout by default. if you don't ask for one, you don't get one.
  • environment — optional, and it may override an already defined variable

now this next bit is important so I'm saying it loud:

if a test times out, it will return 124. so if you want to test that a command does time out? set return code to 124 and let it cook. 🔥

and the way the actual environment for a test gets computed is in this exact order, bestie:

  1. environment defined in higher level lift.yaml files (inheritance)
  2. then the environment defined in the current lift.yaml file
  3. and finally the environment defined in the test itself

last one wins. that's the whole chain. 🧚

also, the command can be any of these three flavors:

  • an absolute path
  • a path relative to the current lift.yaml position
  • or a system command (like ping, curl...)

so flexible. so versatile. obsessed. 😭

🦋 REMOTE TEST DEFINITION 🦋

every remote test = a single section at the root of the lift.yaml file. same energy as local tests, different address. ✨

heads up bestie: please also refer to the local test definition documentation, because all options are reused in the same way for remote tests. don't skip it, iykyk. 👀

here's the example:

# A known remote name followed by the 'test' keyword and the test name
# This defines a test that will be ran on my_remote.
my_remote test my_remote_test_name:
    command: "sh test/test.sh --my-arg"
    return code: 0
    timeout: 2
    # List files and folders that will be uploaded to the remote
    # before running the test.
    resources:
        - test/
    environment:
        MY_VAR: content

see how it's <remote name> + test + <test name>? that's the whole syntax. the remote name goes first and it's how Lift knows where to run the thing. 💜

now, for a remote to be known, it has to be defined in one of these places:

  • a higher level lift.yaml file (inheritance, again, she's everywhere)
  • the current lift.yaml
  • or directly via the --remote option of the lift command line

three ways. pick your fighter. 🥊

about those resources — listen closely because the structure matters:

  • files get uploaded "flatly"
  • folders keep their structure

and don't worry about cleanup — Lift will take care of deleting all resources from the remote after the test is over. she cleans up after herself. a queen. 👑

last thing: the command will be executed in a temporary directory that gets created on the remote. your resources get put in that directory, so you can totally use relative paths to them inside your command/executable. easy. 🎀

🌈 FULL TEST SUITE EXAMPLE 🌈

the example folder at the root of the Lift sources has a fully commented example of a Lift test suite. and the cute part? it can also be used as a functional test suite for Lift itself. she tests herself. self-love fr fr. 💖

and on Debian systems, bestie, you can find that example folder right here:

/usr/share/doc/lift/example

⭐ SEE ALSO ⭐

for the command line utility, see lift(1). go read her next, she's the other half of the story. 🫶

👑 AUTHOR 👑

written and maintained by Nicolas Delvaux <contact@nicolas-delvaux.org> 💜

GPL2+

okay that's the whole page!! you made it, bestie, I'm so proud of you 🥹✨

this was Lift version 2.5.0 of the <pink>LIFT.YAML(1)</pink> manual page — now go forth and write the most organized lift.yaml hierarchy anyone's ever seen. slay. 💅🌸🦋

📦 where this page comes from