docs: add TESTING.md; trim duplicated test comments to pointers (#487)

[sjvans]

What

Consolidates the hard-won test-suite knowledge that was scattered (and duplicated) across test/** comment blocks into a single, authoritative top-level TESTING.md, then trims the duplicated in-file comments down to short pointers.

New TESTING.md covers:

• Running the tests (npm test / vitest, sqlite default; CI matrix Node 22/24 × cds 9/10; where the bookshop app lives)
• sqlite vs HANA (per-file in-memory DB vs one shared HDI container, and the implications: serial file execution, raised timeouts, retry: 2, outbox clear/settle; how the HANA path is signalled via TELEMETRY_TEST_HANA; HANA is a separate workflow_dispatch-only workflow, not PR CI)
• Config via .cdsrc.json profiles (not env) — the profile table + compose syntax + the Tests configure CDS via process.env.cds_requires_* string-JSON instead of profiles/config #486 load-order gotcha (don't reintroduce process.env.cds_*)
• In-memory test infrastructure (MyInMemorySpanExporter / MyInMemoryMetricReader, DELTA temporality, the no-require('@sap/cds')-at-top rule)
• Shared test helpers (test/utils.js from Centralize duplicated queue/test helpers (clearOutbox, flushSpans, eventually/expectEventually, meaningful) #488) and the flush+poll pattern
• HTTP instrumentation (Enable HTTP instrumentation in tests and assert on incoming spans #475) and why client requests are wrapped in asExternalClient
• The only two sanctioned skips (Eliminate all test skips and CI test-subset exclusions (sqlite + HANA) #477): SAP Passport on sqlite; multitenancy on HANA — plus the Eliminate all test skips and CI test-subset exclusions (sqlite + HANA) #477-tracked debt skips
• Known caveats (the startup > NO_TELEMETRY=true local-env artifact; the internal-registry lockfile trap)

Trimmed duplicated comments to pointers (comment-only, no logic change) in: tracing-scheduled, tracing-outboxed-batch, tracing-messaging-inboxed, tracing-messaging-persistent-outbox, tracing-messaging.js, tracing-mt, metrics-outbox-multitenant. The repeated cds.spawn on sqlite skip rationale, the shared-HANA-container outbox-bleed explanation, and the multitenancy Service-Manager note now live in TESTING.md; each site keeps a one-line pointer. Genuinely local rationale (timezone-bug explanation, per-test tree shapes, test/utils.js own doc comments) is left untouched.

README gets a one-line link to TESTING.md under the contributing section.

Notes

• No lib/behavior change. Test-file edits are comment-only (verified: every changed line in test/** starts with //). No change to test logic, assertions, config, vitest.config.mjs, .cdsrc.json, the exporters/reader, or the Eliminate all test skips and CI test-subset exclusions (sqlite + HANA) #477 gated skip logic.
• Full sqlite suite unchanged: 65 passed / 12 skipped.
• oxfmt --check clean; changed files lint clean; grep -c int.repositories.cloud.sap package-lock.json = 0 (lockfile untouched).
• No CHANGELOG entry (docs/test-only, not user-facing lib).

closes #487

[hyperspace-pr-bot]

Summary

The following content is AI-generated and provides a summary of the pull request:

---

docs: Add TESTING.md and trim duplicated test comments to pointers

Documentation

📚 Consolidates scattered, duplicated test-suite knowledge from across test/** comment blocks into a single authoritative TESTING.md, then trims those in-file comments down to short one-line pointers.

Changes

• TESTING.md (new): Single source of truth for the test suite covering:

  • How to run tests (npm test / vitest, sqlite default; CI matrix Node 22/24 × cds 9/10)
  • sqlite vs HANA isolation model (per-file in-memory DB vs shared HDI container, serial execution, raised timeouts, retry: 2, outbox bleed prevention)
  • HANA signalling via TELEMETRY_TEST_HANA and why tests branch on it instead of cds.env
  • Configuration via .cdsrc.json profiles (profile table + compose syntax + Tests configure CDS via process.env.cds_requires_* string-JSON instead of profiles/config #486 load-order gotcha)
  • In-memory test infrastructure (MyInMemorySpanExporter / MyInMemoryMetricReader, DELTA temporality, no-require('@sap/cds')-at-top rule)
  • Shared test helpers (test/utils.js from Centralize duplicated queue/test helpers (clearOutbox, flushSpans, eventually/expectEventually, meaningful) #488) and the flush+poll pattern
  • HTTP instrumentation (Enable HTTP instrumentation in tests and assert on incoming spans #475) and the asExternalClient wrapper
  • The only two sanctioned skips (Eliminate all test skips and CI test-subset exclusions (sqlite + HANA) #477): SAP Passport on sqlite; multitenancy on HANA
  • Known caveats (startup > NO_TELEMETRY=true local-env artifact; internal-registry lockfile trap)

• README.md: Adds a one-line link to TESTING.md under the contributing section.

• test/tracing-scheduled.test.js, test/tracing-outboxed-batch.test.js, test/tracing-messaging-inboxed.test.js, test/tracing-messaging-persistent-outbox.test.js: Multi-line skip rationale comments replaced with single-line pointers to TESTING.md → Sanctioned skips. Same for beforeEach outbox-clear comments.

• test/tracing-messaging.js: afterAll settle block and beforeEach outbox-clear block comments reduced to one-line pointers referencing TESTING.md → sqlite vs HANA.

• test/tracing-mt.test.js, test/metrics-outbox-multitenant.test.js: Multi-line Service Manager / HANA exclusion rationale trimmed to a single pointer line each.

⚠️ No logic changes. Every modified line in test/** is comment-only. Test assertions, config, vitest.config.mjs, .cdsrc.json, and skip conditions are all unchanged.

Jira Issues (ONLY add this section if JIRA issues are available)

Images and Links (ONLY add this section if the links are explicitly provided in the original content)

Related GitHub Issues: #475, #477, #486, #487, #488

---

• 🔄 Regenerate and Update Summary
• ✏️ Insert as PR Description (deletes this comment)
• 🗑️ Delete comment

PR Bot Information

Version: 1.29.33

• GithubContextProvider: Add TESTING.md documenting test setup + caveats; reduce scattered comment clutter #487
• Event Trigger: pull_request.opened
• File Content Strategy: Full file content
• Summary Prompt: Default Prompt
• Correlation ID: eaac1f50-9cd2-11f1-8aed-9dead314eb89
• GithubContextProvider: Tests configure CDS via process.env.cds_requires_* string-JSON instead of profiles/config #486
• GithubContextProvider: Centralize duplicated queue/test helpers (clearOutbox, flushSpans, eventually/expectEventually, meaningful) #488
• GithubContextProvider: Enable HTTP instrumentation in tests and assert on incoming spans #475
• LLM: anthropic--claude-4.6-sonnet
• Output Template: Default Template
• GithubContextProvider: Eliminate all test skips and CI test-subset exclusions (sqlite + HANA) #477

[hyperspace-pr-bot]

This is a clean, documentation-only PR. The changes are well-structured and accurate based on the code inspected. The TESTING.md content aligns with the actual implementation in test/utils.js, MyInMemorySpanExporter.js, MyInMemoryMetricReader.js, and the test files. The comment trimming in the test files correctly reduces duplication while preserving just enough context for readers to follow the pointer to TESTING.md.

No substantive issues were found — the logic in all modified test files is unchanged (comment-only edits as stated in the PR description), the TESTING.md accurately describes the infrastructure, and the README link is correctly placed.

PR Bot Information

Version: 1.29.33

• Correlation ID: eaac1f50-9cd2-11f1-8aed-9dead314eb89
• Event Trigger: pull_request.opened
• File Content Strategy: Full file content
• LLM: anthropic--claude-4.6-sonnet