Test Anatomy
Every test in a suite starts with metadata — fields that identify the test and control whether it runs. These appear at the top level of each test definition.
tests:
- name: Login returns token
description: Verify that valid credentials return a JWT token
tags: [smoke, auth]
skipped: false
services: ...
setup: ...
execution: ...
assertions: ...
Fields
| Field | Required | Description |
|---|---|---|
name | yes | Unique name within the suite, shown in reports and used for filtering |
description | no | Human-readable explanation of what the test verifies |
tags | no | Labels for filtering (e.g., [smoke, auth]) |
skipped | no | Set true to disable the test without deleting it |
Name
The name identifies your test everywhere — CLI output, HTML reports, IDE test runner, cloud dashboard. It's also what --filter matches against.
Keep names descriptive. "Login returns token" tells you exactly what's being tested. "test1" doesn't. When a test fails at 2 AM in CI, you'll appreciate the clarity.
Tags
Tags let you group tests across suites and run just a subset. A test can have any number of tags.
- name: Login test
tags: [smoke, auth, api]
# Run all tests tagged "smoke"
spark run ./tests --tags smoke
# Run tests tagged "smoke" OR "api"
spark run ./tests --tags smoke,api
Skipping
Set skipped: true to temporarily disable a test. It still appears in reports as "skipped" but doesn't execute. Useful when a test is broken and you don't want it blocking your suite.
- name: Broken test
skipped: true
Skipped tests are still visible in reports so you don't forget about them. They just don't run.