Skip to content

Add TESTING.md documenting test setup + caveats; reduce scattered comment clutter #487

Description

@sjvans

Add a top-level TESTING.md documenting the test setup and its caveats in one place, and trim the repeated explanatory comments now scattered across the test files.

Why

The test suite has accumulated a lot of hard-won, non-obvious knowledge that currently lives as long comment blocks duplicated across many files (~450+ comment lines in test/). The same caveats are re-explained repeatedly — e.g. the cds.spawn on sqlite skip rationale appears in ~7 places, the process.env.cds_requires_* config pattern in ~6, the Service Manager / multitenancy limitation in ~4. A single doc is easier to keep correct and lets the test files stay lean.

What TESTING.md should cover

  • How to run: sqlite (default) vs HANA; the env the HANA path needs; npm test / vitest invocation.
  • HANA specifics: single shared HDI container vs sqlite's per-file in-memory DB, and what that implies — serial file execution, outbox-settle in afterAll, retry: 2, raised timeouts (all gated on CI && HANA_DRIVER in vitest.config.mjs).
  • Sanctioned skips/exclusions (the only two, per Eliminate all test skips and CI test-subset exclusions (sqlite + HANA) #477): SAP Passport (sqlite-skip) and multitenancy on HANA (needs a bound Service Manager; excluded from the HANA job). Anything else is debt.
  • Test infrastructure: MyInMemorySpanExporter / MyInMemoryMetricReader (wired via .cdsrc.json profiles; must not require('@sap/cds') at module top; the reader mirrors production DELTA temporality), and the force-flush + poll (expectEventually / eventually) pattern for async span/metric assertions.
  • Config gotchas: the process.env.cds_requires_* load-order sensitivity (see Tests configure CDS via process.env.cds_requires_* string-JSON instead of profiles/config #486), the TELEMETRY_TEST_HANA flag, and why config must precede any @sap/cds require.
  • Known caveats: the pre-existing startup > NO_TELEMETRY=true local-env artifact, the internal-registry lockfile trap for @sap/* installs.

Then

Reduce the in-file comments to short pointers ("see TESTING.md — HANA shared-container caveats") rather than full re-explanations, keeping only what's needed to read the specific test.

Part of the test-quality cluster (#477 / #478 / #475 / #486).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions