The .haiku file format

A .haiku file is plain text with YAML frontmatter at the top and the test steps in plain English below. The filename — not the frontmatter — chooses the target.

Filename rules

Every spec must use the <base>.<platform>.haiku pattern:

login.ios.haiku          # iOS UI test
test_parser.py.haiku     # Python test
cache.rs.haiku           # Rust test

Plain .haiku files (with no platform extension) are rejected by the CLI:

$ haiku recite foo.haiku
✗ foo.haiku: missing platform extension. Use <name>.ios.haiku for UI tests or
  <name>.<lang>.haiku for backend tests. …

Recognised extensions:

Extension	Target
`.ios.haiku`	iOS Simulator
`.macos.haiku`	macOS (coming)
`.web.haiku`	Web (coming)
`.android.haiku`	Android (coming)
`.py.haiku`	Python
`.rs.haiku`	Rust
`.go.haiku`	Go (experimental)
`.ts.haiku` / `.tsx.haiku`	TypeScript (experimental)
`.java.haiku`	Java (experimental)
`.rb.haiku`	Ruby (experimental)

Frontmatter

YAML between --- delimiters at the top of the file.

---
intent: Verify that a user can launch Maps and search for a known landmark
tags: [smoke, maps]
critical: true
target:
  bundle_id: com.apple.Maps
  device: iPhone 17
---

Field	Required	Notes
`intent`	yes	One-line description of what this test proves
`tags`	no	Free-form list — useful for grouping in CI
`critical`	no	When `true`, signals that a failure should block a deploy
`verify`	no	iOS-specific final-assertion natural-language string
`target`	depends	Required for `.ios.haiku` (`bundle_id`, `device`)
`sources`	no	Backend specs only — ordered list of source files the test exercises, most-called first
`target.module`	no	Backend specs only — dotted module path (e.g. `services.user_service`)
`target.context`	no	Backend specs only — extra module paths to feed the compiler

iOS frontmatter

---
intent: Search for a landmark in Maps
target:
  bundle_id: com.apple.Maps
  device: iPhone 17
---

bundle_id must be reverse-DNS (e.g. com.apple.Maps).
device must be an installed simulator name. Run xcrun simctl list devices available to see yours.

Backend frontmatter

---
intent: Verifies the haiku file parser correctly reads .haiku files
sources:
  - ../src/haiku_parser.rs
tags: [parser]
---

Backend specs don't need a target.platform field — the filename carries that. Use sources: to tell Haiku which files the test exercises, in most-called-first order.

Body

Steps live below the closing ---. One step per line, plain English. Blank lines and lines starting with # are ignored.

Launch the app
Tap the search bar
Type "Statue of Liberty"
Verify the search result appears

There's no fixed verb list — Haiku's compiler infers intent from context. See the Actions reference for examples of UI-side phrasings that work today.

Older specs included target.platform in the frontmatter (e.g. platform: ios_simulator). The field is still accepted for backward compatibility but is no longer required — the filename's extension is the canonical signal. New specs should omit it.