LawnLawn Docs
Templates

Testing

How to test templates end-to-end before shipping.
Custom templates are not yet supported in the app. For now, we're temporarily curating the catalog. Support for importing and sharing custom templates is coming soon.
lawn-validate is available to users taking part in our private alpha as a standalone tool. These commands will be integrated into the CLI as lawn template validate and lawn template test in a future release.

lawn-validate test tests a template end-to-end. It spins up an isolated container engine, pulls all images, creates a test instance with dynamic ports, starts it, and runs every configured health check. When the test finishes, it tears everything down automatically.

lawn-validate test <template-id>
OptionDescription
--timeout <seconds>Timeout for the entire test (default: 300)
--validate-onlyOnly validate the manifest, skip image pulling and container startup
--keep-instanceKeep the test instance after completion for debugging
--validate-config <path>Path to a YAML file with env var overrides
--output <format>Output format: text (default) or json

What a test run does

  1. Validates the manifest and compose files
  2. Pulls all container images
  3. Allocates free ports dynamically to avoid conflicts
  4. Creates a test instance with generated credentials
  5. Starts the instance and waits for containers to be ready
  6. Runs all health checks (HTTP and command-based)
  7. Cleans up the test instance and shuts down the engine
# Test a simple template
lawn-validate test whoami

# Test with a longer timeout
lawn-validate test immich --timeout 600

# Keep the instance running after the test for manual inspection
lawn-validate test jellyfin --keep-instance

Templates with required variables

Templates that declare userProvided variables (like admin passwords or API tokens) cannot start without credentials. By default, lawn-validate test skips container startup for these templates — it still validates the manifest and pulls images.

To run the full test, provide a validate config file:

# secrets.yaml (never commit this file)
env:
  RUNNER_TOKEN: "ghp_xxxxxxxxxxxx"
  REPO_URL: "https://github.com/your-org/your-repo"

lawn-validate test github-actions-runner --validate-config secrets.yaml

You can also place a validate.yaml file directly in the template's catalog directory. It's in .gitignore and is picked up automatically during local development.

Tests must be run one at a time. Each run spins up an isolated container engine — running multiple tests in parallel causes conflicts.

Listing templates

lawn-validate list shows all bundled templates:

lawn-validate list