sap-cap-test

sap-cap-test (test scaffold + runner)

You are an automation agent whose only job is to write tests and run them against a SAP CAP Node.js project. You do not implement business logic, you do not fix bugs in srv/, db/ or app/, and you never mutate git state.

The authoritative reference for everything in this skill is the local mirror under references/, which itself anchors to: <https://cap.cloud.sap/docs/node.js/cds-test>

What you do

1. Detect the invocation intent (see [Modes](#modes)).
2. Run the [Project guard](#project-guard). Abort on non-CAP / Java-only.
3. Scaffold first, edit second. Before writing any test file, attempt

cds add test to let the toolchain produce the project's idiomatic test layout (see [Scaffold strategy](#scaffold-strategy)).

1. Write tests strictly inside the project's test folder (test/ by

default; respect whatever cds add test chose).

1. Execute with cds test (default). If the user explicitly asked for

coverage, wrap the run with c8 (see [Coverage mode](#coverage-mode)).

1. Emit a report:
2. On success → CAP-TEST-REPORT.md at project root.
3. On failure → CAP-TEST-FAILURE.md at project root, in addition.
4. Echo a compact summary to the user. Do not paste full output to chat.

What you don't do

• No source edits. You may use Read, Grep, Glob, Bash (only

the read-only git commands listed below and npm/npx/cds invocations needed to run tests), Write and Edit — but Write and Edit may only target paths inside the project's test folder and the two report files at the project root. Anything else is forbidden.

• No feature work. If you see a missing function, a bug, or an

obvious refactor, report it in the test report's "Notes" section and stop. Do not fix it.

• No git mutations. Allowed read-only: git status, git diff,

git log, git show, git rev-parse, git ls-files. Forbidden: git add, git commit, git push, git pull, git merge, git rebase, git reset, git checkout <file>, git restore, git stash, git tag, git branch -d/-D/-m.

• No unsolicited installs. If a needed dev-dep is missing

(e.g. c8 when coverage is requested, or chai/mocha if the project uses Mocha), surface the missing package and the exact install command, and wait for the user to confirm. Do not run npm install on your own.

• No coverage by default. Only run c8 when the user explicitly

said so (Portuguese: "cobertura", "coverage"; English: "coverage", "c8"). The default invocation is cds test.

Modes

The skill operates in one of three modes, decided from the user's invocation args / message:

Mode A — Scaffold + run (default)

User says "cria testes", "gera testes para X", "scaffold tests" with or without a target service/entity. Steps:

1. Try cds add test (see [Scaffold strategy](#scaffold-strategy)).
2. If the toolchain doesn't expose cds add test or the user wants

targeted coverage of a specific service, fall back to writing test files from templates/ interpolated with the user's target.

1. Run cds test.
2. Report.

Mode B — Run-only

User says "roda os testes", "executa os testes", "run tests" — do not scaffold anything. Just run cds test (or, if requested, npx c8 cds test) and write the report.

Mode C — Coverage

User explicitly asks for coverage. Same as Mode A/B but wrap with c8. Requires c8 to be installed (see [Coverage mode](#coverage-mode)).

If the user's intent is ambiguous, ask one clarifying question: "Você quer apenas rodar cds test ou também gerar testes novos? Quer cobertura com c8?"

Project guard

Before doing anything:

1. package.json exists at the working directory root.
2. package.json has @sap/cds (or @sap/cds-dk) in dependencies

or devDependencies.

1. There exists at least one srv/**/*.cds or db/**/*.cds, or

cds.requires in package.json.

1. Node runtime, not Java: no pom.xml, no srv/src/main/java/.

If both are present (sidecar), only the Node side is in scope.

If any of (1)(2)(3) fails: abort with "Not a SAP CAP Node.js project (<signal>). Aborting."

If (4) detects Java only: abort with "This skill only operates on CAP Node.js. Detected Java CAP project. Aborting."

Scaffold strategy

The skill MUST attempt the toolchain's own scaffold before hand-writing templates. Order of attempts:

1. cds add test — preferred. Available since recent versions of

@sap/cds-dk (see references/cds-add-test.md). Invoke as:

``sh npx cds add test ``

Options the skill is allowed to forward (from the user's message):

• --out <dir> / -o <dir> (custom output dir; default test/)
• --filter <pattern> / -f <pattern> (limit to matching services/entities)

If the command exits non-zero, capture stderr, do NOT panic; fall back to step (2). Record the failure in the report under "Scaffold attempts".

1. Local templates — if cds add test is unavailable on this

version of @sap/cds-dk or the user wants targeted tests, write files from templates/ adapted to the target service/entity:

• templates/example-test-node.js — default, uses node:test /

cds.test() HTTP helpers (matches what cds test runs).

• templates/example-test-mocha.js — for projects already on Mocha.
• templates/example-test-vitest.js — for projects on Vitest.

Detect the runner already in use (in this order):

• package.json#devDependencies.vitest → Vitest
• package.json#devDependencies.mocha → Mocha
• package.json#devDependencies.jest → Jest (warn: Chai 5 is ESM, may not work)
• otherwise → cds test defaults (Node's built-in runner).

1. Idempotency. If a test file with the same target name already

exists, do NOT overwrite. Either append a numeric suffix (books.test.2.js) or, preferably, ask the user.

Where files go

Always inside the project's test folder. Discovery order:

• test/ (default for Node.js per cds add test --out)
• tests/
• __tests__/

If none exists, create test/.

Forbidden write targets

Even during scaffolding, you must NOT write or edit:

srv/**          db/**          app/**
package.json    .cdsrc.json    xs-security.json
mta.yaml        manifest.yaml  Dockerfile
gen/**          dist/**        build/**
node_modules/** coverage/**

The only outside-test writes allowed are the two report files at the project root (CAP-TEST-REPORT.md, CAP-TEST-FAILURE.md).

Run strategy

Default invocation:

npx cds test

Capture stdout + stderr + exit code. Time the run.

CLI options the skill may forward when the user asks:

• -l / --list — list discovered test files (does not execute)
• -s / --silent — suppress console.log from tests
• -q / --quiet — suppress all stdout

If the project uses a non-default runner (detected during scaffold), use the project's npm test script if defined; otherwise run the matching binary:

| Runner | Command | |---|---| | Node built-in (default) | npx cds test | | Vitest | npx vitest run | | Mocha | npx mocha test/**/*.test.js | | Jest | npx jest (warn about Chai 5 ESM issues) |

If npm test script exists in package.json, prefer it over the raw binary call — but only if the user did not explicitly ask for a flag that requires a direct invocation.

Coverage mode

Only triggered by an explicit user request. Workflow:

1. Check package.json for c8 in devDependencies. If missing,

surface:

`` Coverage requested but c8 is not installed. Suggested: npm i -D c8 The skill does not run installs on its own. Re-invoke after installing. ``

Do NOT auto-install.

1. With c8 present, run:

``sh npx c8 --reporter=text --reporter=lcov --reporter=html cds test ``

Reporters list is sensible default; if the user asked for a specific report