From cf89c6e5bc1fa367976963ed9ce4d615760cfd89 Mon Sep 17 00:00:00 2001 From: Christian Georgi Date: Thu, 23 Jul 2026 13:50:18 +0200 Subject: [PATCH] Improve docs for `cds bind` in tests Triggered by a user issue: - Mention `cds bind --exec` for integration tests - Add a section in the cds.test docs about such cloud integration tests. --- node.js/cds-test.md | 10 ++++++++++ tools/cds-bind.md | 22 +++++++++++++--------- 2 files changed, 23 insertions(+), 9 deletions(-) diff --git a/node.js/cds-test.md b/node.js/cds-test.md index 7ecf182e86..af2b80f2c0 100644 --- a/node.js/cds-test.md +++ b/node.js/cds-test.md @@ -163,6 +163,16 @@ cds test The last one, `cds test` is a thin wrapper around [Node's built-in test runner](https://nodejs.org/api/test.html), which makes it easier to fetch tests and provides a cleaner output. +#### Testing with Cloud Services + +To run integration tests against cloud services (for example, SAP HANA), wrap the test execution with `cds bind --exec`: + +```sh +cds bind --exec -- node --test +``` + +[Learn more about hybrid testing with `cds bind`.](../tools/cds-bind#integration-tests){.learn-more} + ::: tip Writing runner-agnostic tests To keep your tests portable across different test runners, it's recommended to avoid using runner-specific features and stick to the common APIs provided by `cds.test`, in particular via [`cds.test.expect`](#expect), which are designed to work across different runners. This way, you can easily switch between different test runners as shown above without having to change your test code. -> Learn more in section [Runner-Agnostic Tests](#runner-agnostic-tests) below. ::: diff --git a/tools/cds-bind.md b/tools/cds-bind.md index a1086df927..0a0619e632 100644 --- a/tools/cds-bind.md +++ b/tools/cds-bind.md @@ -514,17 +514,21 @@ Learn how to do hybrid testing using the XSUAA or IAS + AMS service(s) in the [C `cds bind` can be handy for testing with real cloud services in your CI/CD pipeline. -Configure your required bindings for testing and save them to your project's _package.json_ file for your tests' profile: +#### Local: `cds bind --exec` + +For local hybrid testing, the simplest approach is to wrap your test command with `cds bind --exec`, which resolves bindings and provides them via `VCAP_SERVICES`: ```sh -cds bind -2 integration-test-hana -o package.json -4 integration-test +cds bind -2 integration-test-hana --profile integration-test --exec -- npm run integration-test ``` -No credentials are saved! +No credentials are written to disk. -In your CI/CD pipeline you can resolve the bindings and inject them into the test commands: +#### CI/CD Pipelines: Export Resolved Bindings -```sh +For CI/CD environments where you want explicit control, export the resolved credentials before running tests: + +```sh :line-numbers # Login cf auth $USER $PASSWORD # Optional if your bindings have org and space removed to be agnostic @@ -540,10 +544,10 @@ export cds_requires="$(cds env get requires --resolve-bindings)" # [!code highl npm run integration-test # [!code highlight] ``` -Some comments to the previous snippet: -- With `CDS_ENV` you specify the [configuration profile](../node.js/cds-env#profiles) for the test, where you previously put the service binding configuration. -- [`cds env get requires`](../node.js/cds-env#services) prints the `requires` section of the configuration as a JSON string. Through `--resolve-bindings`, it includes the credentials of the service bindings from the cloud. To make the credentials available for all subsequent `cds` commands and the tests, the `requires` JSON string is put into the `cds_requires` script variable. -- In `npm run integration-test` any test code can run, for example, [`cds.test`](../node.js/cds-test). +The following notes explain the highlighted lines: +- Line 7: With `CDS_ENV`, you specify the [configuration profile](../node.js/cds-env#profiles) for the test, where you previously put the service binding configuration. Note that setting the profile alone does not resolve any credentials yet. +- Line 10: `cds env get requires --resolve-bindings` prints the `requires` section of the configuration and resolves the credentials of the service bindings from the cloud. The script puts it into the `cds_requires` environment variable that is translated back to the [`cds.requires` configuration](../node.js/cds-env#services) by all subsequent `cds` commands and the tests. +- Line 13: In `npm run integration-test`, any test code can run, for example, `node --test` or `vitest` using [`cds.test`](../node.js/cds-test).