Backend: Spring-style test framework, hellocodenameone e2e server, API cleanup

.github/ci/apple-checks.json

@@ -43,7 +43,7 @@
       "!maven/cn1-applovin/**",
       "!maven/cn1-unity-levelplay/**",
       "!maven/core-unittests/**",
-      "vm/backend/demo/cn1ss/**",
+      "scripts/hellocodenameone/backend/**",
       "scripts/lib/cn1ss.sh"
     ],
     "push": [
@@ -89,7 +89,7 @@
       "!maven/cn1-applovin/**",
       "!maven/cn1-unity-levelplay/**",
       "!maven/core-unittests/**",
-      "vm/backend/demo/cn1ss/**",
+      "scripts/hellocodenameone/backend/**",
       "scripts/lib/cn1ss.sh"
     ]
   },
@@ -234,7 +234,7 @@
       "!maven/cn1-unity-levelplay/**",
       "!maven/core-unittests/**",
       "!docs/**",
-      "vm/backend/demo/cn1ss/**"
+      "scripts/hellocodenameone/backend/**"
     ],
     "push": [
       ".github/workflows/scripts-mac-catalyst.yml",
@@ -262,7 +262,7 @@
       "!maven/cn1-applovin/**",
       "!maven/cn1-unity-levelplay/**",
       "!maven/core-unittests/**",
-      "vm/backend/demo/cn1ss/**"
+      "scripts/hellocodenameone/backend/**"
     ]
   }
 }

.github/scripts/build_javadocs.sh

@@ -155,6 +155,13 @@ rm -rf "$BACKEND_STAGE" "$CN1_DIR/dist/backend-javadoc" "$CN1_DIR/backend-javado
 mkdir -p "$BACKEND_STAGE" "$CN1_DIR/dist/backend-javadoc"
 cp -r "$BACKEND_DIR/src/." "$BACKEND_STAGE/"
 cp -r "$BACKEND_DIR/impl/parparvm/." "$BACKEND_STAGE/"
+# The test library, codenameone-backend-test: its public package is the API a
+# backend's tests are written against, so it is documented here. Its translation
+# stubs stand in for the JUnit extension, and the JUnit subset it compiles against
+# is on the source path only, to resolve @ExtendWith -- JUnit is not ours to
+# document.
+cp -r "$BACKEND_DIR/test/src/." "$BACKEND_STAGE/"
+cp -r "$BACKEND_DIR/test/parparvm/." "$BACKEND_STAGE/"
 while IFS= read -r shared; do
   rel="${shared#"$CN1_DIR/src/"}"
   mkdir -p "$BACKEND_STAGE/$(dirname "$rel")"
@@ -201,7 +208,7 @@ python3 "$ROOT_DIR/scripts/check-backend-jdk-surface.py"
   --add-script "$ROOT_DIR/maven/javadoc-resources/highlight.min.js" \
   --add-script "$ROOT_DIR/maven/javadoc-resources/javadoc-highlight-init.js" \
   --release 8 \
-  -sourcepath "$BACKEND_STAGE:$ROOT_DIR/Ports/CLDC11/src:$ROOT_DIR/vm/JavaAPI/src" \
+  -sourcepath "$BACKEND_STAGE:$ROOT_DIR/Ports/CLDC11/src:$ROOT_DIR/vm/JavaAPI/src:$BACKEND_DIR/test/junit-shim" \
   -Xdoclint:all,-missing \
   -Xmaxerrs 10000 \
   -Xmaxwarns 10000 \
@@ -220,8 +227,17 @@ if [ -e "$CN1_DIR/dist/backend-javadoc/com/codename1/impl" ]; then
   echo "Backend JavaDoc generated com.codename1.impl output; the internal package must stay excluded." >&2
   exit 1
 fi
+"$ROOT_DIR/scripts/check-backend-javadoc-internals.sh" "$CN1_DIR/dist/backend-javadoc" html
 # The shared classes are the point of staging the core sources at all; a run
 # that lost them would publish a backend ORM with no Session to call.
+if [ ! -f "$CN1_DIR/dist/backend-javadoc/com/codename1/backend/test/BackendTest.html" ]; then
+  echo "Backend JavaDoc is missing the test library, com.codename1.backend.test; aborting." >&2
+  exit 1
+fi
+if [ -e "$CN1_DIR/dist/backend-javadoc/org/junit" ]; then
+  echo "Backend JavaDoc documented the JUnit subset; it is on the source path only." >&2
+  exit 1
+fi
 if [ ! -f "$CN1_DIR/dist/backend-javadoc/com/codename1/orm/session/Session.html" ]; then
   echo "Backend JavaDoc is missing the shared com.codename1.orm.session classes; aborting." >&2
   exit 1

.github/scripts/generate-quality-report.py

@@ -29,6 +29,9 @@
     Path("vm/backend/src"),
     Path("vm/backend/impl/javase"),
     Path("vm/backend/impl/parparvm"),
+    # maven/backend-test, built the same way from vm/backend/test.
+    Path("vm/backend/test/src"),
+    Path("vm/backend/test/javase"),
 ]
 
 DEFAULT_REPORT_TITLE = "✅ Continuous Quality Report"

.github/workflows/car-android.yml

@@ -25,7 +25,7 @@ name: Car (Android Auto) integration
       # emulator legs as well would buy nothing and cost a great deal: a change to
       # the ORM, the database layer or the HTTP parser cannot reach this
       # transport.
-      - 'vm/backend/demo/cn1ss/**'
+      - 'scripts/hellocodenameone/backend/**'
       - 'scripts/lib/cn1ss.sh'
   push:
     branches:
@@ -48,7 +48,7 @@ name: Car (Android Auto) integration
       # emulator legs as well would buy nothing and cost a great deal: a change to
       # the ORM, the database layer or the HTTP parser cannot reach this
       # transport.
-      - 'vm/backend/demo/cn1ss/**'
+      - 'scripts/hellocodenameone/backend/**'
       - 'scripts/lib/cn1ss.sh'
 
 concurrency:

.github/workflows/developer-guide-docs.yml

@@ -150,7 +150,7 @@ jobs:
         run: |
           set -euo pipefail
           xvfb-run -a mvn -B -ntp -f maven/pom.xml \
-            -pl core,javase,android,css-compiler,codenameone-maven-plugin,backend \
+            -pl core,javase,android,css-compiler,codenameone-maven-plugin,backend,backend-test \
             -am install \
             -Plocal-dev-javase \
             -DskipTests \

.github/workflows/linux-build-run.yml

@@ -127,7 +127,7 @@ jobs:
         run: |
           cd maven
           JAVA_HOME="$JDK_8_HOME" bash ../scripts/ci/retry.sh \
-            mvn -B -pl codenameone-maven-plugin,cn1-ads-mock -am \
+            mvn -B -pl codenameone-maven-plugin,cn1-ads-mock,backend,backend-test -am \
             -DskipTests '-Dmaven.javadoc.skip=true' '-Plocal-dev-javase' install
 
       - name: Build hellocodenameone-common (JDK 17)
@@ -142,12 +142,26 @@ jobs:
           bash scripts/ci/retry.sh \
             mvn -B -f scripts/hellocodenameone/pom.xml -pl common -am install -DskipTests '-Dmaven.javadoc.skip=true'
 
+      # The CI test server (scripts/hellocodenameone/backend) as a runnable copy the
+      # suite jobs run with plain java (CN1SS_SERVER_DIST). Built here, where the
+      # plugin and the backend runtime were just installed: the musl job's container
+      # has neither, and building them there -- every port, through the plugin's
+      # dependencies -- outlasted the suite's wait for the server.
+      - name: Build the test server
+        env:
+          CN1SS_BACKEND_SKIP_INSTALL: '1'
+        run: |
+          set -e
+          JAVA17_HOME="$JDK_17_HOME" scripts/hellocodenameone/backend/server.sh dist "$GITHUB_WORKSPACE/artifacts/cn1ss-server"
+          test -f artifacts/cn1ss-server/classes/META-INF/cn1-backend-main
+
       - name: Package suite classes
         run: |
           set -e
           tar czf suite-classes.tgz \
             scripts/hellocodenameone/common/target/classes \
-            maven/cn1-ads-mock/target/classes
+            maven/cn1-ads-mock/target/classes \
+            artifacts/cn1ss-server
       - name: Upload suite classes
         uses: actions/upload-artifact@v4
         with:
@@ -281,6 +295,8 @@ jobs:
         working-directory: vm
         env:
           CN1_SHOT_OUTPUT_DIR: ${{ github.workspace }}/artifacts/linux-port/raw
+          # The test server prepare-suite built (see "Build the test server" there).
+          CN1SS_SERVER_DIST: ${{ github.workspace }}/artifacts/cn1ss-server
           # Full app stdout/stderr -- the only evidence when the suite wedges
           # mid-run (uploaded with the screenshot artifact below).
           CN1_APP_LOG_TEE: ${{ github.workspace }}/artifacts/linux-port/raw/app-output.log
@@ -516,6 +532,7 @@ jobs:
             -e CN1_SHOT_OUTPUT_DIR=/cn1/artifacts/linux-port/raw-musl \
             -e CN1_APP_LOG_TEE=/cn1/artifacts/linux-port/raw-musl/app-output.log \
             -e CN1_REQUIRE_SUITE=true \
+            -e CN1SS_SERVER_DIST=/cn1/artifacts/cn1ss-server \
             -e LIBGL_ALWAYS_SOFTWARE=1 \
             -e RETRY_ONLY_MATCHING \
             docker.io/library/alpine:3.20 sh -ec '

.github/workflows/parparvm-tests-windows.yml

@@ -394,7 +394,7 @@ jobs:
               Write-Host "mvn failed; retrying in $delay s..."
               Start-Sleep -Seconds $delay
             }
-            mvn -B -pl windows,codenameone-maven-plugin,cn1-ads-mock -am -DskipTests '-Dmaven.javadoc.skip=true' '-Plocal-dev-javase' install
+            mvn -B -pl windows,codenameone-maven-plugin,cn1-ads-mock,backend,backend-test -am -DskipTests '-Dmaven.javadoc.skip=true' '-Plocal-dev-javase' install
             if ($LASTEXITCODE -eq 0) { $ok = $true; break }
           }
           if (-not $ok) { throw "mvn install failed after all retries" }
@@ -446,6 +446,30 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+      # The CI test server (scripts/hellocodenameone/backend), which the suite
+      # streams its screenshots to and drives its networking tests against. Built
+      # once here as a runnable copy, against the runtime and plugin the install
+      # above put in the local repository, and run with plain java by the capture
+      # steps (CN1SS_SERVER_DIST) -- this x64 one and the arm64 leg, which has no
+      # Maven repository of its own. Git Bash runs server.sh: a bare `bash` from a
+      # JVM can resolve to WSL's instead.
+      - name: Build the test server
+        shell: bash
+        env:
+          CN1SS_BACKEND_SKIP_INSTALL: '1'
+          JAVA17_HOME: ${{ env.JDK_17_HOME }}
+        run: |
+          scripts/hellocodenameone/backend/server.sh dist "$GITHUB_WORKSPACE/artifacts/cn1ss-server"
+          test -f "$GITHUB_WORKSPACE/artifacts/cn1ss-server/classes/META-INF/cn1-backend-main"
+
+      - name: Upload the test server
+        uses: ./.github/actions/upload-artifact-with-retry
+        with:
+          name: windows-cn1ss-server
+          path: artifacts/cn1ss-server
+          if-no-files-found: error
+          retention-days: 1
+
       # Publish the compiled (architecture-independent) core + port bytecode right
       # after building it, so the native arm64 screenshot leg can translate +
       # clang-cl-build an arm64 exe without rebuilding core -- codename1-core needs
@@ -465,8 +489,8 @@ jobs:
 
       # Build the ParparVM JavaAPI, then run the FULL hellocodenameone screenshot
       # suite over the cn1ss WebSocket: capturesHelloSuiteOverWebSocket builds the
-      # suite exe (app + core + port + nativeSources via clang-cl), starts a
-      # Cn1ssScreenshotServer, runs the exe (it renders each test Form offscreen
+      # suite exe (app + core + port + nativeSources via clang-cl), starts the
+      # cn1ss test server (scripts/hellocodenameone/backend), runs the exe (it renders each test Form offscreen
       # with Direct2D/DirectWrite and streams each PNG over com.codename1.io
       # WebSocket), waits for CN1SS:SUITE:FINISHED, and copies every received PNG
       # to CN1_SHOT_OUTPUT_DIR (~112 images). This is the CI equivalent of
@@ -491,6 +515,7 @@ jobs:
         shell: pwsh
         env:
           JDK_8_HOME: ${{ env.JDK_8_HOME }}
+          CN1SS_SERVER_DIST: ${{ github.workspace }}\artifacts\cn1ss-server
           CN1_SHOT_OUTPUT_DIR: ${{ github.workspace }}\artifacts\windows-port\raw
           CN1_PERFORMANCE_BINARY_OUT: ${{ github.workspace }}\artifacts\windows-port\raw\benchmark-app.exe
           # The suite's own translation, replayed by the performance gate below.
@@ -658,6 +683,12 @@ jobs:
       # The Kotlin 1.6.0 compiler cannot run on this runner's JDK 21 (arm64 has no
       # Temurin JDK 8/11), so the hellocodenameone-common bytecode is built once on
       # the x64 leg and reused here (it is architecture-independent).
+      - name: Restore the test server
+        uses: ./.github/actions/download-artifact-with-retry
+        with:
+          name: windows-cn1ss-server
+          path: artifacts/cn1ss-server
+
       - name: Restore hellocodenameone-common classes
         uses: ./.github/actions/download-artifact-with-retry
         with:
@@ -696,6 +727,7 @@ jobs:
         working-directory: vm
         shell: pwsh
         env:
+          CN1SS_SERVER_DIST: ${{ github.workspace }}\artifacts\cn1ss-server
           CN1_SHOT_OUTPUT_DIR: ${{ github.workspace }}\artifacts\windows-port\raw
           CN1_PERFORMANCE_BINARY_OUT: ${{ github.workspace }}\artifacts\windows-port\raw\benchmark-app.exe
           # The suite's own translation, replayed by the performance gate below.

.github/workflows/parparvm-tests.yml

@@ -22,6 +22,9 @@ on:
       - 'maven/build-engine/**'
       - 'maven/project-model/**'
       - 'maven/backend/**'
+      - 'maven/backend-test/**'
+      - 'scripts/hellocodenameone/pom.xml'
+      - 'scripts/hellocodenameone/backend/**'
       # The core classes the backend compiles as its own (the ORM and the entity
       # annotations, marked @SharedWithBackend and listed by
       # vm/backend/shared-sources.sh). They have no copy under vm/ any more, so
@@ -35,6 +38,9 @@ on:
       - 'CodenameOne/src/com/codename1/annotations/Id.java'
       - 'CodenameOne/src/com/codename1/annotations/Column.java'
       - 'CodenameOne/src/com/codename1/annotations/DbTransient.java'
+      - 'CodenameOne/src/com/codename1/annotations/JsonIgnore.java'
+      - 'CodenameOne/src/com/codename1/annotations/JsonProperty.java'
+      - 'CodenameOne/src/com/codename1/io/gzip/**'
       - '!vm/**/README.md'
       - '!vm/**/readme.md'
       - '!vm/**/docs/**'
@@ -60,6 +66,9 @@ on:
       - 'maven/build-engine/**'
       - 'maven/project-model/**'
       - 'maven/backend/**'
+      - 'maven/backend-test/**'
+      - 'scripts/hellocodenameone/pom.xml'
+      - 'scripts/hellocodenameone/backend/**'
       # The core classes the backend compiles as its own (the ORM and the entity
       # annotations, marked @SharedWithBackend and listed by
       # vm/backend/shared-sources.sh). They have no copy under vm/ any more, so
@@ -73,6 +82,9 @@ on:
       - 'CodenameOne/src/com/codename1/annotations/Id.java'
       - 'CodenameOne/src/com/codename1/annotations/Column.java'
       - 'CodenameOne/src/com/codename1/annotations/DbTransient.java'
+      - 'CodenameOne/src/com/codename1/annotations/JsonIgnore.java'
+      - 'CodenameOne/src/com/codename1/annotations/JsonProperty.java'
+      - 'CodenameOne/src/com/codename1/io/gzip/**'
       - '!vm/**/README.md'
       - '!vm/**/readme.md'
       - '!vm/**/docs/**'
@@ -314,7 +326,7 @@ jobs:
       - name: Install core + maven plugin for the backend contract
         working-directory: maven
         run: |
-          bash "$GITHUB_WORKSPACE/scripts/ci/retry.sh" mvn -B -pl core,backend,codenameone-maven-plugin \
+          bash "$GITHUB_WORKSPACE/scripts/ci/retry.sh" mvn -B -pl core,backend,backend-test,codenameone-maven-plugin \
             -am install -DskipTests -Plocal-dev-javase \
             -Dspotbugs.skip=true -Dpmd.skip=true -Dcheckstyle.skip=true \
             -Dmaven.javadoc.skip=true \
@@ -367,6 +379,10 @@ jobs:
           # toolchain regression fails the workflow rather than quietly
           # subtracting BackendDatabaseTest, BackendOrmTest and the rest from it.
           CN1_BACKEND_REQUIRED: 1
+          # BackendWebSocketIntegrationTest translates scripts/hellocodenameone/backend
+          # through server.sh, which would otherwise re-install the backend runtime
+          # the step above just installed from this same checkout.
+          CN1SS_BACKEND_SKIP_INSTALL: 1
 
       - name: Run ParparVM Benchmark
         working-directory: vm
@@ -485,6 +501,85 @@ jobs:
   # every case must be strictly green, NON-STRICT included, and the set that ran
   # has to match the committed manifest so the suite cannot quietly shrink to the
   # cases it happens to pass.
+  backend-compiled-tests:
+    # The backend test framework's two runners over one test source: surefire on
+    # the JVM, then the same classes translated by ParparVM into a native test
+    # binary (cn1:backend-test), the way an application's own tests run when it
+    # asks for -Dcn1.backend.compiledTests=true. The project is the CI test server,
+    # scripts/hellocodenameone/backend, so these are also its self-checks.
+    #
+    # The compiled leg leaves out the Mockito-based test classes on its own; the
+    # report check at the end is what proves the binary actually ran tests, since
+    # a goal that skipped would otherwise leave this job green.
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install native build tools
+        run: |
+          bash scripts/ci/apt-get-update.sh
+          sudo apt-get install -y clang zlib1g-dev libcurl4-openssl-dev libssl-dev libnghttp2-dev
+
+      - name: Set up JDK 8
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: '8'
+          cache: 'maven'
+      - name: Save JDK 8 Path
+        run: echo "JDK_8_HOME=$JAVA_HOME" >> $GITHUB_ENV
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - name: Save JDK 17 Path
+        run: echo "JDK_17_HOME=$JAVA_HOME" >> $GITHUB_ENV
+
+      # Gates off for the reason the vm-tests install step gives.
+      - name: Install the backend runtime, its test support and the plugin
+        working-directory: maven
+        run: |
+          bash "$GITHUB_WORKSPACE/scripts/ci/retry.sh" mvn -B -pl backend,backend-test,codenameone-maven-plugin \
+            -am install -DskipTests -Plocal-dev-javase \
+            -Dspotbugs.skip=true -Dpmd.skip=true -Dcheckstyle.skip=true \
+            -Dmaven.javadoc.skip=true \
+            -Dmaven.repo.local="$GITHUB_WORKSPACE/.m2-repo"
+        env:
+          JAVA_HOME: ${{ env.JDK_8_HOME }}
+
+      - name: Run the backend tests on the JVM and compiled
+        working-directory: scripts/hellocodenameone
+        run: |
+          mvn -B -Dcodename1.platform=backend -pl backend test \
+            -Dcn1.backend.compiledTests=true \
+            -Dmaven.repo.local="$GITHUB_WORKSPACE/.m2-repo"
+        env:
+          JAVA_HOME: ${{ env.JDK_17_HOME }}
+          JDK_8_HOME: ${{ env.JDK_8_HOME }}
+
+      - name: Check that both runners reported
+        working-directory: scripts/hellocodenameone/backend/target/surefire-reports
+        run: |
+          jvm=$(ls TEST-*.xml | grep -vc -- '-compiled.xml' || true)
+          compiled=$(ls TEST-*-compiled.xml 2>/dev/null | wc -l)
+          echo "JVM reports: $jvm, compiled reports: $compiled"
+          if [ "$jvm" -eq 0 ] || [ "$compiled" -eq 0 ]; then
+            echo "::error::a runner produced no test reports"
+            exit 1
+          fi
+
+      - name: Upload the test reports
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: backend-compiled-tests
+          path: scripts/hellocodenameone/backend/target/surefire-reports/**
+          if-no-files-found: warn
+          retention-days: 14
+
   backend-websocket-conformance:
     name: WebSocket conformance (Autobahn)
     runs-on: ubuntu-24.04