Test CLI Reference

Complete command-line interface reference for the Garden Linux test runner (./test).

Overview

The main entry point is ./test in the Garden Linux root directory (symlink to tests/util/run.sh). It automatically detects the image type and runs appropriate tests.

Basic Syntax:

./test [OPTIONS] <image-file>

Common Options

--help

Show help message and exit.

./test --help

--skip-cleanup

Skip cleanup of cloud resources after testing.

QEMU VM behavior:

• After running or skipping tests, stop and cleanup the VM with ctrl + c.

Cloud behavior:

• To clean up cloud resources after using this flag, re-run without the flag or use --only-cleanup.

./test --skip-cleanup .build/image.raw

--skip-tests

Skip running the actual test suite (useful for infrastructure setup only).

./test --skip-tests .build/image.raw

--test-args

Pass any command-line argument to pytest. Put multiple arguments inside quotes.

Examples:

Run a specific test file:

./test --test-args "test_ssh.py" .build/image.raw

Run with verbose output:

./test --test-args "-v" .build/image.raw

Run multiple tests:

./test --test-args "test_ssh.py test_network.py -v" .build/image.raw

Enable debug logging:

./test --test-args "--log-cli-level=DEBUG" .build/image.raw

Cloud-Specific Options

--cloud <provider>

Specify cloud provider (aws, gcp, azure, ali, openstack).

./test --cloud aws .build/image.raw
./test --cloud gcp .build/image.raw
./test --cloud azure .build/image.raw
./test --cloud ali .build/image.raw
./test --cloud openstack .build/image.raw

INFO

QEMU VM testing ignores this flag.

--cloud-image

Use an existing cloud image instead of uploading a new one.

Possible images are listed on official releases, for example 1592.12:

• ali: m-d7o7skltl4qe9anmwdp4 (eu-west-1 amd64)
• aws: ami-0d8d06eb3a44ae794 (eu-central-1 amd64)
• gcp: gardenlinux-gcp-ff804026cbe7b5f2d6f729e4-1592-12-c6d7f9a9 (amd64)
• azure: /CommunityGalleries/gardenlinux-13e998fe-534d-4b0a-8a27-f16a73aef620/Images/gardenlinux-nvme-gen2/Versions/1592.12.0 (amd64)

./test --cloud aws --cloud-image ami-0d8d06eb3a44ae794

--image-requirements-file <file>

Only needed with --cloud-image. Points to a valid *.requirements file.

./test --cloud aws --cloud-image \
  --image-requirements-file .build/aws-gardener_prod-amd64-today-local.requirements \
  ami-07f977508ed36098e

--only-cleanup

Only run tofu destroy for cloud setups (cleans up resources without running tests).

./test --cloud aws --only-cleanup .build/image.raw

--cloud-plan

Only run tofu plan for cloud setups (shows what resources would be created without creating them).

./test --cloud aws --cloud-plan .build/image.raw

INFO

QEMU VM testing ignores this flag.

QEMU-Specific Options

--ssh

Enable SSH access to QEMU VM (gardenlinux@127.0.0.1:2222).

./test --ssh .build/image.raw

INFO

For cloud testing, SSHD is always enabled via cloud-init.

--debug

Enable debug mode (display window) for QEMU VM.

./test --debug .build/image.raw

Shows a graphical window with the QEMU VM console output.

Development Options

--dev

Enable development mode with automatic file synchronization and test re-execution.

QEMU shorthand for:

--ssh --skip-cleanup --skip-tests --watch

Cloud shorthand for:

--skip-cleanup --skip-tests --watch

Usage:

# QEMU dev mode
./test --dev .build/image.raw

# Cloud dev mode
./test --dev --cloud aws .build/image.raw

# With specific tests
./test --dev --test-args "test_ssh.py -v" .build/image.raw

What it does:

1. Starts VM (QEMU or cloud)
2. Syncs test distribution
3. Runs tests once
4. Watches for file changes in tests/ and features/
5. Re-syncs and re-runs tests on changes
6. Stop with Ctrl+C

--watch

Watch for file changes and re-run tests automatically (used internally by --dev).

./test --ssh --skip-cleanup --skip-tests --watch .build/image.raw

Image Types

The test runner automatically detects the image type based on the file extension:

.tar files - Chroot testing:

./test .build/image.tar

.raw files - QEMU or cloud testing:

# QEMU (default)
./test .build/image.raw

# Cloud (with --cloud flag)
./test --cloud aws .build/image.raw

.oci files - OCI container testing:

./test .build/container-amd64-today-local.oci

Examples

Basic Testing

Run chroot tests:

./test .build/image.tar

Run QEMU tests:

./test .build/image.raw

Run cloud tests:

./test --cloud aws .build/image.raw

Development Workflow

Run QEMU with SSH and keep running:

./test --ssh --skip-cleanup .build/image.raw

Use dev mode for rapid iteration:

./test --dev --test-args "test_ssh.py -v" .build/image.raw

Specific Test Execution

Run only SSH tests:

./test --test-args "test_ssh.py" .build/image.raw

Run tests with verbose output:

./test --test-args "-v" .build/image.raw

Run multiple specific tests:

./test --test-args "test_ssh.py test_network.py -v" .build/image.raw

Cloud Testing

Test on AWS with cleanup:

./test --cloud aws .build/image.raw

Test on AWS, keep resources for inspection:

./test --cloud aws --skip-cleanup .build/image.raw

Clean up resources later:

./test --cloud aws --only-cleanup .build/image.raw

Test existing cloud image:

./test --cloud aws --skip-cleanup --skip-tests --cloud-image \
  --image-requirements-file .build/aws-gardener_prod-amd64-today-local.requirements \
  ami-07f977508ed36098e

Debugging

Enable debug logging:

./test --test-args "--log-cli-level=DEBUG" .build/image.raw

Run specific test with debug logging:

./test --test-args "--log-cli-level=DEBUG test_ssh.py" .build/image.raw

Show QEMU debug window:

./test --debug .build/image.raw

Infrastructure Only

Set up infrastructure without running tests:

./test --skip-tests .build/image.raw

Plan cloud resources without creating them:

./test --cloud aws --cloud-plan .build/image.raw

Option Combinations

Common option combinations:

Local development:

./test --ssh --skip-cleanup .build/image.raw

Rapid iteration:

./test --dev --test-args "test_ssh.py -v" .build/image.raw

Cloud inspection:

./test --cloud aws --skip-tests --skip-cleanup .build/image.raw

Specific test in cloud:

./test --cloud aws --skip-cleanup --test-args "test_ssh.py -v" .build/image.raw

Debug mode with SSH:

./test --ssh --debug --skip-cleanup .build/image.raw

Exit Codes

The test runner returns standard pytest exit codes:

• 0 - All tests passed
• 1 - Tests failed
• 2 - Test execution was interrupted
• 3 - Internal error during test execution
• 4 - pytest command-line usage error
• 5 - No tests were collected

Related Topics

• Testing Garden LinuxGet started with the Garden Linux Testing Framework
• Test Framework ArchitectureUnderstanding the Garden Linux Test Framework Architecture
• Test OrganizationUnderstanding how Garden Linux tests are organized and structured
• Run TestsHow to run Garden Linux tests in chroot, QEMU, cloud, OCI, and Kubernetes environments
• Setup Test EnvironmentInstall prerequisites and dependencies for running Garden Linux tests
• Debug TestsLearn how to Troubleshoot and Debug Garden Linux Tests
• Test in CloudRun Garden Linux tests on cloud providers with authentication and configuration guides
• Developing TestsComprehensive guidelines for developing and maintaining tests in the Garden Linux test framework
• Test Coverage MarkersGuide to test coverage markers for establishing traceability between features and tests