/helpers-reference

name: helpers-reference
description: Reference for the bundled SAP Testing runtime (SapSession, SapArtifacts, resolveTestData, buildFixture, format helpers), importable in specs as "@sap-testing/runtime". Use when the user asks how a helper works or why a capability seems missing. Load sap-webgui for rendering, locator, theme, iframe, and control-behavior guidance.

Helpers Reference

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

Non-negotiable execution gate

Using a helper does not bypass the SAP Testing phase requirements. The `abapfs_run_playwright_tests` tool verifies required steps, artifacts, data caches, and script checks and **will reject the run** if any are missing, stale, incomplete, or unverified. A helper or escape-hatch workaround cannot bypass this validation.

Why

Helpers are load-bearing. Every test in this project depends on them. A hidden bug here — a silent-swallow wait, a locator that matches the wrong element, a popup guard that dismisses a real error — makes hundreds of tests lie in unison. Treat this API like any other production dependency you can't patch yourself: understand it precisely, use it correctly, and know exactly what to do when it doesn't cover something.

**Read this before assuming a capability is missing.** The runtime is deliberately generic and fairly complete; most "I need a new helper" instincts are actually "I haven't found the right existing one yet."

Use this reference for runtime API contracts. For WebGUI rendering behavior, locator stability, accessible names, iframes, themes, dialogs, ALV, and uploads, load `sap-webgui`.

Where this actually lives (important — read this first)

Unlike test artifacts, the runtime is NOT a file in the configured test folder or workspace. Only its `@sap-testing/runtime` API and type declarations are exposed; runtime implementation files cannot be read or edited from the workspace. See "When a capability is genuinely missing" below.

What you CAN see: the type declarations surfaced via `@sap-testing/runtime` (real IntelliSense/type-checking while you write a spec), and the method reference below (this file + `build-scripts` §2). Between the two, you should never need to guess a method's existence or signature.

Standalone context rule

For a general API question, answer directly from this reference. If the user wants you to inspect, write, or fix a real test artifact, first complete the standalone bootstrap in the relevant phase workflow:

1. Call `abapfs_get_test_folder` and use its returned absolute path as `<TEST_FOLDER>`. 2. Resolve the program/TC-ID from the request and artifacts under `<TEST_FOLDER>/tests/`; never depend on a prior chat. 3. Confirm the exact `connectionId` before any system-specific diagnosis.

For findings/code errors follow `analyze-and-plan`; for screen-map errors follow `explore-ui`; for test-case errors follow `design-cases`; for data-spec errors follow `define-data`; for data/cache errors follow `prepare-data`; for spec translation errors follow `build-scripts`; and for execution failures follow `run-scripts`.

Modules

| Module | Purpose | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SapSession` | Main class — actions + assertions, including `sap.se16n()` business-visible table proof required by `verification: sql|mixed` specs | | `SapArtifacts` | Verify AL11 files and capture spool text — **unverified against a real system, see `build-scripts` §2 before relying on either**. Jobs/IDocs/table rows are NOT covered here — use `## Post-test verification` (see `design-cases`) for those | | `resolveTestData` | Reads `.data.md` + per-system cache at run time | | `buildFixture` | Deterministic Excel/CSV generator, powers `source: "generated"` | | `padNumericId`, `stripLeadingZeros`, `relativeDate`, `isRelativeDateToken` | Pure formatting helpers | | `parseFrontmatter` | YAML-frontmatter parsing shared by `.data.md` and `TC-*.md` |

`sap.se16n()` is supporting visual evidence, not an SQL replacement. SQL/mixed cases declare every expected table in `se16nTables` and call it once per listed table after the business action with key-addressable criteria; Phase 7 still executes authoritative SQL. Never use it for data preparation.

`sap.se16