feat: run and test against java by PDT42 · Pull Request #85 · cap-js/cds-test

PDT42 · 2026-04-28T13:27:40Z

Based on original changes from @BobdenOs fork: https://github.com/BobdenOs/cds-test/tree/feat/java

Description

This PR adds the "run tests against a CAP Java app" feature, based on the changes from the fork linked above.

Requirements

Running cds-test tests against a Java app requires:

Managing the Lifecycle of the Java app-runtime from within the test-runtime
Exposing the app-runtime's database to the test-runtime (e.g. to make cds.ql work)
Exposing the app-runtime's runtime model to the test-runtime (e.g. to make cds.entities(...) work)

The goal must be to create a developer experience, where there is no distinguishable difference between writing tests for a node app and writing tests for a java app - as long as the two apps share the same .cds model. Additionally, the test setup must be easy to comprehend, robust and reliable. Developers must be able to trust their test setup explicitly; i.e. it must not introduce unnecessary obfuscation; it must be easy to prove that the test setup it-self isn't the root cause of test failures.

Solution

This PR introduces a Java "run-mode". This mode will be selected in environments where cds.env.profiles.includes('java'). Selecting the java runner will cause cds.exec to be overridden for the cds.test(...) run.

The overridden exec will:

Locate the Java app to test against
- ... by lookup relative to cds.root based on artifactid from pom.xml
Construct and inject a @hcql based dbProxy service into the Java app-runtime model
- ... exposes the tables of those entities from the cds.linked model that will become part of schema-h2.sql
Override the registered cds.env.requires.db in the test-runtime ...
- ... specifying a custom service implementation (java-hcql.js) that will intercept all queries sent to db during cds.test(...) and route them to the dbProxy we injected into the Java app-runtime
- ... extend and override the cds.model of the test runtime, to include .drafts and make them accessible via cds.entities(db.schema.namespace.activeEntity.drafts)

sequenceDiagram
    participant W as test-worker
    participant J as java.js
    participant Lock as .mvn-build.lock
    participant H as java-hcql.js
    participant App as CAP Java App
    participant DB as Java H2

    Note over W,App: Setup — serialized across parallel workers

    W->>J: cds.exec()
    J->>Lock: open('wx') [exclusive create — polls every 500ms until free]
    Lock-->>J: acquired

    J->>J: buildDatabaseProxy() → dbProxy CSN
    alt model changed or JAR absent
        J->>App: mvn package -DskipTests
        App-->>J: JAR ready
    end

    J->>Lock: unlink() [finally — always released]
    J->>App: java -jar app-exec.jar --server.port=N
    App-->>J: HTTP 200 (startup ping)
    J->>J: cds.env.requires.db = java-hcql.js
    J->>H: cds.connect.to('db')
    J-->>W: { server, url }

    Note over W,DB: Test execution
    W->>H: req.query (original entity names)
    H->>H: JSON-serialize → regex-rewrite all entity name positions via proxyMap
    H->>H: normalize null comparisons
    H->>App: POST /hcql/dbProxy
    App->>DB: SQL
    DB-->>App: rows
    App-->>H: { data: [...] }
    H-->>W: result

    Note over W,App: Cleanup — cds.shutdown() in after() hook
    W->>W: delete cds.services.db + cds.db
    W->>App: app.kill()
    App-->>W: exit [awaited unless CDS_ENV_TEST_SKIP_AWAIT_SHUTDOWN]

I updated the directory structure of test to separate java, node and cds-test tests cleanly.

Implementation Details

Updated `test` directory structure

test
├── lib
│   └── <feature>.test.js                      ← unit tests for cds-test
└── runtime
    ├── java
    │   ├── app                                ← java test app (schema, services, ...)
    │   │   ├── test
    │   │   │   └── sample.test.js             ← test realistic usage of cds-test in a java app
    │   │   └── ...
    │   └── <feature>.test.js                  ← cds-test feature tests in a java app
    └── node
        ├── app                                ← node test app (schema, services, ...)
        │   ├── test
        │   │   └── sample.test.js             ← test realistic usage of cds-test in a node app
        │   └── ...
        └── <feature>.test.js                  ← cds-test feature tests in a node app

Specific changes compared to https://github.com/BobdenOs/cds-test/tree/feat/java

Renamed the proxy service we inject into the app-runtime: db -> dbProxy

Calling the service db is neat for the test-runtime, because we physically place a db in the runtime model, that could be auto discovered. However, the real injection is done via cds.env manipulation every time. Using the pre-occupied db prefix introduces complexity in the app-runtime. IMO it is cleaner to make the proxy nature of the service explicit in the runtime model and the db spoofing + intercept -> re-route obvious, yet transparent in the test-runtime.
Resolved the .drafts, .texts gap

The implementation from the fork used the definitions that are easily available from cds.load, cds.linked and the various cds.compile.for.xyz transformations. I didn't find a way to naturally get access to .drafts and .texts (which we know will be part of schema-h2.sql) by any combination and order of existing transformations - and eventually stopped trying. The main problem seems to be that compile.for.java does not use compile.for.lean_drafts and running compile.for.java early does not get us anything use-full, since we need to construct and inject a proxy service .csn that will and can pass through compile.for.java again, without raising reference issues ... I found that it is easier to construct relevant proxy entities without using existing utilities. Similar reasoning holds for .texts. The solution I ended up with could be seen as a kind of compile.for.hcql_db_proxy ...
Changed java.js to re-compile only when a model change is detected; will not switch to spring-boot

.jar and db-proxy.json freshness are guaranteed by a flock inspired .mvn-build.lock preventing concurrent builds by parallel workers and using db-proxy.json as a hash equivalent to establish whether or not re-compilation is required, after acquiring the lock.
Changed entity name rewriting to cover all CQN name positions

The fork rewrites only the top-level query target by mutating the CQN object directly. This misses entity names in deeper positions — ref arrays, "id": navigation steps within infix filters, and column refs with entity-qualified paths. The PR serializes the full CQN to JSON and rewrites all occurrences via a regex covering subqueries, joins and any nesting depth. Rewriting is purely data-driven via proxyMap, with no dependency on req.path resolution.
Added null comparison normalization before forwarding CQN to Java HCQL

Java HCQL rejects = {"val":null} silently — queries testing for null return no results instead of an error. The PR rewrites = {"val":null} → "is","null" and != {"val":null} → "is not","null" at the JSON level before sending, covering all nesting depths in a single pass.
Manually injecting a proxy entity for DRAFT.DraftAdministrativeData when required to enable INSERT.info(Entity.drafts)

No model that is shared between the test- und the java-runtime includes this, easily accessible.
Introduced an up_ filter for children of managed compositions in data.reset.

These would usually only be added during cds.linked, but for flows they are added earlier and make it into the db model. They will always be deleted transitively, when deleting the parent. Java does not allow targeting them with directly; i.e.: fails when sending DELETE via @hcql. This workaround prevents the erroneous request.

Notes

Complexity introduced by compile/for/lean_drafts vs cds-compiler/lib/transform/draft/odata
Could consider trying to enable cds.ql: SELECT.localized
Java GET /health afterEach?

# Conflicts: # lib/cds-test.js

Split test/app into test/node-app (pure Node, no pom.xml) and test/java-app (minimal Spring Boot app for java.js integration tests). The pom.xml presence in test/app was causing CDS's project-nature detection to activate the java profile for all tests, replacing cds.exec with the Java launcher even in Node-only CI environments. - git mv test/app → test/node-app; Java files → test/java-app - Add test/java-app with minimal bookshop model and sample-java.it.js - Add .github/workflows/java.yml (SAP Machine JDK 21, Maven cache) - sample-java.it.js uses .it.js suffix to stay out of chest discovery

…eat/java

BobdenOs · 2026-05-19T07:07:15Z

+				<executions>
+					<execution>
+						<id>cds.npm-ci</id>
+						<goals>
+							<goal>npm</goal>
+						</goals>
+						<configuration>
+							<arguments>ci</arguments>
+						</configuration>
+					</execution>
+					<execution>
+						<id>cds.clean</id>
+						<goals>
+							<goal>clean</goal>
+						</goals>
+					</execution>
+
+					<execution>
+						<id>cds.resolve</id>
+						<goals>
+							<goal>resolve</goal>
+						</goals>
+					</execution>
+
+					<execution>
+						<id>cds.build</id>
+						<goals>
+							<goal>cds</goal>
+						</goals>
+						<configuration>
+							<commands>
+								<command>build --for java</command>
+								<command>deploy --to h2 --with-mocks --dry --out "${project.basedir}/src/main/resources/schema-h2.sql"</command>
+							</commands>
+						</configuration>
+					</execution>


It should be possible to delete all these steps. It should also fix the setup step Warm npm cache for Java app as it would remove the npm ci execution on the mvn build. The build --for java step can be run once outside of the mvn build.

BobdenOs · 2026-05-19T12:13:54Z

+      // Java HCQL rejects `= {"val":null}`:
+      // -> globally convert to `is "null"`
+      json = json.replace(/"=",{"val":null}/g,  '"is","null"')
+      json = json.replace(/"!=",{"val":null}/g, '"is not","null"')


Should be followed up as part of HCQL specification.

BobdenOs · 2026-05-19T12:15:06Z

+      // CQN JSON can include (fully qualified) db-entity-names in only two places:
+      //   As the first element of a `ref` array, always preceeded by '[' 
+      //   > e.g.: ["db.bookshop.Books"...]
+      //   As an id in a navigation segment, always preceeded by '"id":'
+      //   > e.g.: {"id":"bookshop.Books",...}
+      // -> Use replace instead of parsing the CQN, to inject proxy-entity-refs
+      for (const [from, to] of Object.entries(proxyMap))
+        json = json.replace(new RegExp(`(?<=\\[|"id":)"${from.replace(/\./g, '\\.')}"`, 'g'), `"${to}"`)


With HCQL@2 of java the service should be local name aware. Which might enable the removal of this fully qualified name conversion.

BobdenOs · 2026-05-19T12:18:15Z

+      // Normalize INSERT values (single-row) → entries
+      if (query.INSERT?.values && query.INSERT.columns) {
+        query.INSERT.entries = [
+          query.INSERT.columns.reduce((entry, column, index) => {
+            entry[column] = query.INSERT.values[index]
+            return entry
+          }, {})
+        ]
+        delete query.INSERT.values
+      }


Is the same as rows shouldn't duplicate it.

BobdenOs · 2026-05-19T13:42:34Z

+      }
+
+      const id = cds.utils.uuid()
+      inFlight.set(id, query)


I wouldn't do this. All the requests should be failing and reject their promises already. So collecting them and having them throw all the other active requests doesn't really help as it will fill the logs with duplicate information. Just having a clean error message that explains that the app crashed should be enough.

BobdenOs · 2026-05-19T13:44:58Z

+    if (def['@cds.persistence.skip'] === true) return false
+    if (def['@cds.persistence.exists']) return false
+
+    // Exclude service projections — only DB-layer views get a proxy entity


This sounds like it will prevent certain things from working.

BobdenOs · 2026-05-21T09:03:03Z

+      - name: Install Java app npm dependencies
+        run: npm ci
+        working-directory: test/runtime/java/app


This step looks like it shouldn't be necessary. Did you make sure to add the test app into the workspace configuration ?

I don't want to replicate cds.resolve;

BobdenOs and others added 8 commits March 14, 2025 10:42

Allow java apps to use cds-test

d760fcc

fix direct database access queries

77e88b2

ignore flow internal entities

442d6ef

Bump java version and use app-exec.jar when available

9ee40c2

Resolve conflicts

59c5f86

remove before timeout config

05f8eb9

switch from open to access for exists check

d1860d2

feat: extract artifact id from pom.xml

0462a55

PDT42 changed the title ~~Feat/java~~ feat: run and test against java Apr 28, 2026

Merge branch 'main' into feat/java

a8ac948

# Conflicts: # lib/cds-test.js

PDT42 force-pushed the feat/java branch from e8ba1d5 to a8ac948 Compare April 28, 2026 15:17

PDT42 added 19 commits April 28, 2026 17:21

chore: format

efd4915

test/gen: verify data.reset works with java

5e647cd

chore/gen: fix specified version

aefe19f

chore/gen: iterate on workflows

ae24f51

chore/gen: iterate on workflows

8a76c0e

chore/gen: iterate on workflows

ea83ffb

chore: ensure test is imported

8cf8568

test: refactor test

65b2775

chore/gen: iterate on workflows

ec77f58

chore/gen: iterate on workflows

2277713

chore/gen: iterate on workflows

7712c78

chore/gen: iterate on workflows

3ff1de5

chore/gen: iterate on workflows

07b8dc6

chore/gen: iterate on workflows

d59a5f8

chore/gen: iterate on workflows

09fc951

chore/gen: iterate on workflows

cedb2f2

chore/gen: iterate on workflows

7416983

chore/gen: iterate on workflows

3f22f5a

PDT42 added 3 commits May 12, 2026 18:53

feat: enable accessing draft admin data via cds.ql

6987c82

fix: injection timing

0eba589

fix: add missing type check

3b44fc4

PDT42 marked this pull request as ready for review May 12, 2026 21:19

PDT42 added 7 commits May 13, 2026 20:31

feat: (try to) capture java app crash

3ae06dc

chore: ignore proxy definitions

54ae308

fix: skip crash test in ci

669f5b5

test: remove poc

3287cb2

chore: fix spelling

005a470

Merge branch 'feat/java' of https://github.com/cap-js/cds-test into f…

d01bc66

…eat/java

chore: shift complexity

5bbdd03

PDT42 mentioned this pull request May 19, 2026

feat: Allow java apps to use cds-test #14

Draft

chore: move generate proxy to parent pom

9bb8ca3

BobdenOs reviewed May 21, 2026

View reviewed changes

sjvans requested review from agoerler and danjoa May 21, 2026 13:45

PDT42 added 14 commits May 21, 2026 22:23

fix: use file reference

38b2460

fix: use file reference

2cd0a67

fix: increase default mocha timout

d04cf0b

chore: remove redundant npm ci

4721cfb

chore: add test apps as workspaces

3be1b6a

chore: adjust to workspaces

6682b52

fix: update lock-file

f1e44bf

fix: registry

609ce5c

chore: revert optimism

bb3d343

chore: remove cleanup step

f694694

chore: make it even worse

60d228e

chore: try exposing cds binary from root

ef15298

chore: restore state from before trying to use workspaces

668d735

I don't want to replicate cds.resolve;

chore: reduce hcql tests to local impl

78a02f8

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: run and test against java#85

feat: run and test against java#85
PDT42 wants to merge 197 commits into
mainfrom
feat/java

PDT42 commented Apr 28, 2026 •

edited

Loading

Uh oh!

BobdenOs May 19, 2026

Uh oh!

BobdenOs May 19, 2026

Uh oh!

BobdenOs May 19, 2026

Uh oh!

BobdenOs May 19, 2026

Uh oh!

BobdenOs May 19, 2026

Uh oh!

BobdenOs May 19, 2026

Uh oh!

BobdenOs May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

PDT42 commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Requirements

Solution

Updated test directory structure

Specific changes compared to https://github.com/BobdenOs/cds-test/tree/feat/java

Notes

Uh oh!

BobdenOs May 19, 2026

Choose a reason for hiding this comment

Uh oh!

BobdenOs May 19, 2026

Choose a reason for hiding this comment

Uh oh!

BobdenOs May 19, 2026

Choose a reason for hiding this comment

Uh oh!

BobdenOs May 19, 2026

Choose a reason for hiding this comment

Uh oh!

BobdenOs May 19, 2026

Choose a reason for hiding this comment

Uh oh!

BobdenOs May 19, 2026

Choose a reason for hiding this comment

Uh oh!

BobdenOs May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

PDT42 commented Apr 28, 2026 •

edited

Loading

Updated `test` directory structure