/define-data

name: define-data
description: Standalone Phase 4 of SAP UI testing. Authors one tests/<PROGRAM>/test-cases/TC-XXX.data.md requirement spec per case marked dataRequired: yes — choosing the narrowest correct source (sql/static/generated/seeded), and generating upload fixtures in the EXACT file format the program parses (xlsx vs csv). Validates that every dataRequired declaration has a matching sidecar. Use when the user asks to define, author, or spec test data requirements (not to resolve concrete values — that is prepare-data).

Define Data — Phase 4 (of 7)

For a cross-system staged scenario, also load `multi-system-workflows`: declare only pre-existing inputs here. A key produced by an earlier system at run time belongs in the workflow JSON handoff, not a prepared-data requirement.

Phase order: analyze-and-plan (1) → explore-ui (2) → design-cases (3) → **define-data (4)** → prepare-data (5) → build-scripts (6) → run-scripts (7).

This phase produces `TC-XXX.data.md` requirement specs — the reusable, system-agnostic SHAPE of the data each case needs. It does NOT resolve concrete values (that is Phase 5, `prepare-data`) and does NOT write specs (Phase 6).

For bounded, self-contained support work, use `sap-task-helper` with explicit inputs, allowed writes, and an output contract.

Why this is its own phase

Data specs written as an afterthought at the end of a big case-writing session come out as one-line stubs ("cache key + status") that Phase 5 then has to throw away and rewrite from scratch. That is exactly what happened before this was split out. A `.data.md` is a real contract: it decides which of four sources each value comes from, whether an upload fixture is Excel or CSV, and which keys the spec (Phase 6) will reference. Getting the format wrong here means the program silently rejects the upload at run time and the "test" proves nothing. This phase exists so every data requirement gets deliberate attention, once, in the right format.

Non-negotiable execution gate

`prepare-data` (Phase 5), `build-scripts` (Phase 6), and `abapfs_run_playwright_tests` (Phase 7) all reject cases whose `.data.md` is missing, malformed, or references undeclared keys. Author every required sidecar here, correctly, before handing off.

Tool availability (read this if a tool seems missing)

**Naming:** when these docs say *call* `X`, `X` is a **tool** (you invoke it and get a result); *delegate to / invoke* `X` is an **agent** (a subagent you launch); *load / follow* `X` is a **skill** (a procedure you read). A name without a verb: see the overview's "Skills, tools, and agents" list.

The editor may hide tools until searched for. Before Step 0, ensure `abapfs_get_test_folder` and `abapfs_build_test_index` are available; if either is missing, search your available tools for it by name. If one cannot be found, tell the user.

Step 0 — Standalone bootstrap and input gate (mandatory)

> **Say before acting:** "Starting Step 0: standalone bootstrap and input gate."

1. Call `abapfs_get_test_folder` **before reading any artifact**. Treat the result as `<TEST_FOLDER>`; never infer it. 2. If unset, STOP and ask the user to run "ABAP FS: Enable SAP UI Testing Features". If not open in the workspace, STOP and ask them to add it. 3. Resolve `<PROGRAM>` from the request; if omitted, inspect `<TEST_FOLDER>/tests/*/test-cases/_index.md`. Auto-select only when exactly one candidate matches; otherwise ask. 4. **Enforce the Phase 3 input gate:** `_index.md`, `_findings.md`, `_units.md`, `_screens.md`, and every `TC-XXX.md` must exist. If `_index.md` is missing, STOP and follow `design-cases`. From `_index.md`, take the authoritative `Data required?` column — that is the list of cases needing a `.data.md`. Do NOT re-derive it by rereading every TC body. 5. Read `_findings.md`'s `## Input file format` — the fixture format, column count, and header names come from there. 6. Read `_units.md` — its "Effective inputs" (DB tables the program reads to validate rows, e.g. MARC/MARA existence) tell you which tables a `source: sql` requirement should query for genuinely valid values, so the data you spec actually passes the program's own validation.

> **Say before continuing:** "Step 0 completed. Evidence: test folder, program, `_index.md`, and required upstream artifacts confirmed. Next: Step 1 — enumerate data-required cases."

Step 1 — Enumerate the cases that need data

> **Say before acting:** "Starting Step 1: list every dataRequired: yes case and its data-key references."

• From `_index.md`, list every case with `Data required? = yes`. Each needs exactly one `TC-XXX.data.md`.
• For each such case, read its `TC-XXX.md` and collect every `<data-key: ...>` placeholder used in the state table, Steps, Expected Result, and the `## Post-test verification` SQL rows. Every placeholder becomes a `requires` key.
• Cases with `Data required? = no` get NO sidecar — creating one is an error `abapfs_build_test_index` rejects.

> **Say before continuing:** "Step 1 completed. Evidence: data-required cases and their referenced keys enumerated. Next: Step 2 — author each spec."

Step 2 — Author each `TC-XXX.data.md`

> **Say before acting:** "Starting Step 2: write a complete requirement spec for every data-required case."

**Frontmatter placement — the #1 cause of silent data failures. Read this first.** The `requires:` block MUST be a `---`-delimited YAML **frontmatter at the very top of the file** — literally the first bytes. The runtime parses ONLY a leading `---` block; a `requires:` block placed anywhere else parses to nothing, so `resolveTestData` returns zero keys and every `data.<key>` silently comes back `undefined` (surfacing much later as a confusing "value is not a string" in `setField`). When you copy the template below, reproduce the `---` … `---` as the actual start of the file:

• ✅ RIGHT — file begins with the frontmatter:

  ---
  tcId: TC-001
  requires:
    - key: sample_site
      ...