You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2026/09/03 16:42:12 UTC
(causeway) 03/16: docs(webcomponents): add Petclinic run and test scripts
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch htmx
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 39607fd9249996b832df3dd391b0a8340e307c0a
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Thu Sep 3 09:19:03 2026 +0100
docs(webcomponents): add Petclinic run and test scripts
---
viewers/webcomponents/README.adoc | 14 ++--
.../sample-htmx-petclinic/README.adoc | 28 +++----
viewers/webcomponents/sample-htmx-petclinic/run.sh | 31 ++++++++
.../webcomponents/sample-htmx-petclinic/test.sh | 47 ++++++++++++
.../webcomponents/sample-vue-petclinic/README.adoc | 88 ++++++++++++++++++++++
viewers/webcomponents/sample-vue-petclinic/run.sh | 31 ++++++++
viewers/webcomponents/sample-vue-petclinic/test.sh | 47 ++++++++++++
7 files changed, 263 insertions(+), 23 deletions(-)
diff --git a/viewers/webcomponents/README.adoc b/viewers/webcomponents/README.adoc
index 0a4f3fa382b..0449054433d 100644
--- a/viewers/webcomponents/README.adoc
+++ b/viewers/webcomponents/README.adoc
@@ -106,17 +106,19 @@ The listing should include `META-INF/resources/causeway-webcomponents/index.mjs`
The preferred manual test serves the page and GraphQL endpoint from the same Causeway application origin.
This avoids cross-origin and authentication-cookie differences that can obscure component behavior.
-The repository provides `viewers/webcomponents/sample-htmx-petclinic` as the cohesive generic-viewer reference application and `viewers/webcomponents/sample-html` as the stable low-level vanilla-component fixture.
-The Petclinic application supplies deterministic JPA/H2 data, real rich GraphQL, four exact-logical-type HTML-authored pages, retained effective menu and grid fallbacks, canonical HTMX routes, and a side-by-side current Wicket viewer.
-Start Petclinic from the repository root with:
+The repository provides HTMX and Vue Petclinic applications over one shared deterministic JPA/H2 domain and rich GraphQL contract, plus `viewers/webcomponents/sample-html` as the stable low-level vanilla-component fixture.
+Start either Petclinic viewer from the repository root with:
[source,shell]
----
-mvn -f viewers/webcomponents/pom.xml -Prun-sample-htmx-petclinic
+./viewers/webcomponents/sample-htmx-petclinic/run.sh
+./viewers/webcomponents/sample-vue-petclinic/run.sh
----
-Open `http://localhost:8080/htmx`, or open `/wicket/` and sign in as `sven` with password `pass` for comparison.
-See link:sample-htmx-petclinic/README.adoc[`sample-htmx-petclinic/README.adoc`] and link:htmx/README.adoc[`htmx/README.adoc`] for routes, provenance, customization, and acceptance contracts.
+Run only one application at a time because both use port 8080 by default.
+Open `http://localhost:8080/htmx` for HTMX or `http://localhost:8080/vue/` for Vue.
+The HTMX application also exposes `/wicket/`; sign in as `sven` with password `pass` for comparison.
+See link:sample-htmx-petclinic/README.adoc[`sample-htmx-petclinic/README.adoc`], link:sample-vue-petclinic/README.adoc[`sample-vue-petclinic/README.adoc`], link:htmx/README.adoc[`htmx/README.adoc`], and link:vue/README.adoc[`vue/README.adoc`] for routes, customization, and acceptance contracts.
The vanilla sample supplies its own deterministic JPA/H2 data, the same rich GraphQL endpoint, packaged foundation modules, and stable low-level automation hooks.
Start it from the repository root with:
diff --git a/viewers/webcomponents/sample-htmx-petclinic/README.adoc b/viewers/webcomponents/sample-htmx-petclinic/README.adoc
index 9bff4fd3626..ee529fea235 100644
--- a/viewers/webcomponents/sample-htmx-petclinic/README.adoc
+++ b/viewers/webcomponents/sample-htmx-petclinic/README.adoc
@@ -17,13 +17,16 @@ Owner and service actions demonstrate canonical descriptions, parameter-prompt d
== Run
-Use JDK 17 or later.
+Use JDK 17 or later and run this command from the repository root:
[source,bash]
----
-mvn -f viewers/webcomponents/pom.xml -Prun-sample-htmx-petclinic
+./viewers/webcomponents/sample-htmx-petclinic/run.sh
----
+The script respects an existing `JAVA_HOME`, discovers JDK 21 through macOS `/usr/libexec/java_home` when `JAVA_HOME` is unset, and uses `MVN` instead of `mvn` when that environment variable is supplied.
+Pass Maven properties such as `-Dspring-boot.run.arguments=--server.port=9090` to the script when needed.
+
The root URL redirects to `http://localhost:8080/htmx`.
The Wicket comparison is available at `http://localhost:8080/wicket/`.
Sign in to Wicket with username `sven` and password `pass`; the bypass authenticator accepts the demonstration credentials.
@@ -44,31 +47,22 @@ This secured configuration enables Spring CSRF protection and intentionally omit
The opt-in `playwright` profile adds Playwright for Java only to the dedicated browser-test source set, so ordinary reactor builds do not resolve a browser or compile the Playwright suite.
Playwright runs Chromium headlessly by default and does not take foreground focus.
-Install the profile's reactor dependencies and Chromium once:
+Run the integration, secured integration, and complete headless UI suites from the repository root:
[source,bash]
----
-mvn -f viewers/webcomponents/pom.xml -pl htmx -am install -DskipTests
-mvn -f viewers/webcomponents/sample-htmx-petclinic/pom.xml \
- -Pplaywright \
- -Dexec.mainClass=com.microsoft.playwright.CLI \
- -Dexec.classpathScope=test \
- -Dexec.args="install chromium" \
- test-compile exec:java
+./viewers/webcomponents/sample-htmx-petclinic/test.sh
----
-Run the complete headless UI suite from the web-components reactor:
+Install Playwright Chromium on the first run when necessary:
[source,bash]
----
-mvn -f viewers/webcomponents/pom.xml \
- -pl sample-htmx-petclinic -am \
- -Pplaywright \
- -Dtest=PetClinicHtmxPlaywrightTest \
- -Dsurefire.failIfNoSpecifiedTests=false \
- test
+./viewers/webcomponents/sample-htmx-petclinic/test.sh --install-browser
----
+Any arguments after `--install-browser` are passed to the Maven test invocation.
+
Add `-Dcauseway.viewer.webcomponents.htmx.component-toolkit=native` to run the same suite through complete explicit-native reference, read-only field, editor, and ordinary-action rollback.
Set `-Dplaywright.headless=false` only when deliberately debugging in a visible browser.
Set `-Dplaywright.chromium.executable=/absolute/path/to/chromium` or `-Dplaywright.chromium.channel=chrome` to use an installed browser instead of Playwright's bundled Chromium.
diff --git a/viewers/webcomponents/sample-htmx-petclinic/run.sh b/viewers/webcomponents/sample-htmx-petclinic/run.sh
new file mode 100755
index 00000000000..a31b218eb28
--- /dev/null
+++ b/viewers/webcomponents/sample-htmx-petclinic/run.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+if [[ -z "${JAVA_HOME:-}" && -x /usr/libexec/java_home ]]; then
+ export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
+fi
+
+exec "${MVN:-mvn}" \
+ -f "$ROOT/viewers/webcomponents/pom.xml" \
+ -Prun-sample-htmx-petclinic \
+ "$@"
diff --git a/viewers/webcomponents/sample-htmx-petclinic/test.sh b/viewers/webcomponents/sample-htmx-petclinic/test.sh
new file mode 100755
index 00000000000..5d1c3a7d3ad
--- /dev/null
+++ b/viewers/webcomponents/sample-htmx-petclinic/test.sh
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+MVN="${MVN:-mvn}"
+POM="$ROOT/viewers/webcomponents/pom.xml"
+MODULE="sample-htmx-petclinic"
+PROFILE="playwright"
+
+if [[ -z "${JAVA_HOME:-}" && -x /usr/libexec/java_home ]]; then
+ export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
+fi
+
+if [[ "${1:-}" == "--install-browser" ]]; then
+ shift
+ "$MVN" -f "$POM" -pl htmx -am install -DskipTests
+ "$MVN" -f "$ROOT/viewers/webcomponents/sample-htmx-petclinic/pom.xml" -P"$PROFILE" \
+ -DskipTests test-compile \
+ -Dexec.mainClass=com.microsoft.playwright.CLI \
+ -Dexec.classpathScope=test \
+ -Dexec.args="install chromium" \
+ exec:java
+fi
+
+exec "$MVN" -f "$POM" -pl "$MODULE" -am -P"$PROFILE" \
+ -Dtest=PetClinicHtmxApplication_IntegTest,PetClinicHtmxSecuredApplication_IntegTest,PetClinicHtmxPlaywrightTest,PetClinicHtmxSecuredPlaywrightTest \
+ -Dsurefire.failIfNoSpecifiedTests=false \
+ test \
+ "$@"
diff --git a/viewers/webcomponents/sample-vue-petclinic/README.adoc b/viewers/webcomponents/sample-vue-petclinic/README.adoc
new file mode 100644
index 00000000000..7d8f3cb55e8
--- /dev/null
+++ b/viewers/webcomponents/sample-vue-petclinic/README.adoc
@@ -0,0 +1,88 @@
+= Vue Petclinic reference application
+
+// Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.
+// See the NOTICE file distributed with this work for additional information regarding copyright ownership.
+// The ASF licenses this file to you under the Apache License, Version 2.0.
+
+This module is the executable reference application for the generic Vue web-component viewer.
+It uses the shared deterministic Petclinic domain, the Causeway GraphQL endpoint, Vue 3, Vue Router 4, and the framework-neutral `cw-` elements.
+The Vue application owns its HTML document, stable shell, router, history fallback, theme, and exact logical-type page registration.
+The semantic web components remain authoritative for metadata, values, validation, interactions, collections, previews, and results.
+
+== Run
+
+Use JDK 21 and run this command from the repository root:
+
+[source,bash]
+----
+./viewers/webcomponents/sample-vue-petclinic/run.sh
+----
+
+Open these URLs after Spring Boot starts:
+
+* `http://localhost:8080/vue/` uses the default Vaadin component policy.
+* `http://localhost:8080/vue/?toolkit=native` uses the native component policy.
+* `http://localhost:8080/vue/object/petclinic.PetOwner/s_owner-mary` opens Mary Smith through the custom Vue owner page.
+* `http://localhost:8080/vue/object/petclinic.Pet/s_pet-basil` opens Basil through the generic `<cw-object>` fallback page.
+* `http://localhost:8080/graphiql` opens GraphiQL.
+
+Pass Maven properties to the script when needed.
+For example, this uses port 9090:
+
+[source,bash]
+----
+./viewers/webcomponents/sample-vue-petclinic/run.sh \
+ -Dspring-boot.run.arguments=--server.port=9090
+----
+
+The script respects an existing `JAVA_HOME`, discovers JDK 21 through macOS `/usr/libexec/java_home` when `JAVA_HOME` is unset, and uses `MVN` instead of `mvn` when that environment variable is supplied.
+
+== Test
+
+The test script runs the Spring integration tests and the Playwright acceptance suite.
+Playwright uses headless Chromium by default and does not take foreground focus.
+
+Run the suite with:
+
+[source,bash]
+----
+./viewers/webcomponents/sample-vue-petclinic/test.sh
+----
+
+Install Playwright Chromium on the first run when necessary:
+
+[source,bash]
+----
+./viewers/webcomponents/sample-vue-petclinic/test.sh --install-browser
+----
+
+The browser suite covers the stable application shell, direct links, refresh, back and forward navigation, custom-page precedence, generic fallback, invalid and absent objects, semantic navigation and results, menus, keyboard skip navigation, and both toolkit policies.
+Set `-Dplaywright.headless=false` only when deliberately debugging in a visible browser.
+Set `-Dplaywright.chromium.executable=/absolute/path/to/chromium` or `-Dplaywright.chromium.channel=chrome` to use an installed browser.
+Any arguments after `--install-browser` are passed to the Maven test invocation.
+
+== Rebuild the Vue frontend
+
+Production Vue assets are committed under `src/main/resources/static/vue` so running the application does not require a Vite development server.
+After changing files under `frontend`, regenerate the locked production output from the repository root:
+
+[source,bash]
+----
+mvn -pl viewers/webcomponents/sample-vue-petclinic \
+ -am \
+ -Pregenerate-vue-petclinic \
+ package
+----
+
+The profile runs `npm ci` and the production Vite build.
+The frontend config treats `cw-` names as native custom elements and deduplicates Vue and Vue Router while consuming the local viewer package.
+
+== Application structure
+
+`frontend/index.html` is the application-owned HTML document.
+`frontend/src/App.vue` declares the stable GraphQL provider, menus, loading and announcement regions, default result outlet, and keyed router view.
+`frontend/src/pages/PetOwnerPage.vue` is an exact-type custom page for `petclinic.PetOwner`.
+Other domain types remain unregistered and therefore demonstrate the generic route-page fallback.
+`PetClinicVueRouteController` forwards only the intended client routes to the production `index.html` without capturing GraphQL or static assets.
+
+The generic Vue viewer package and its application integration contract are documented in `../vue/README.adoc`.
diff --git a/viewers/webcomponents/sample-vue-petclinic/run.sh b/viewers/webcomponents/sample-vue-petclinic/run.sh
new file mode 100755
index 00000000000..2042b0160db
--- /dev/null
+++ b/viewers/webcomponents/sample-vue-petclinic/run.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+if [[ -z "${JAVA_HOME:-}" && -x /usr/libexec/java_home ]]; then
+ export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
+fi
+
+exec "${MVN:-mvn}" \
+ -f "$ROOT/viewers/webcomponents/pom.xml" \
+ -Prun-sample-vue-petclinic \
+ "$@"
diff --git a/viewers/webcomponents/sample-vue-petclinic/test.sh b/viewers/webcomponents/sample-vue-petclinic/test.sh
new file mode 100755
index 00000000000..d943e14f72d
--- /dev/null
+++ b/viewers/webcomponents/sample-vue-petclinic/test.sh
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+MVN="${MVN:-mvn}"
+POM="$ROOT/viewers/webcomponents/pom.xml"
+MODULE="sample-vue-petclinic"
+PROFILE="playwright-vue"
+
+if [[ -z "${JAVA_HOME:-}" && -x /usr/libexec/java_home ]]; then
+ export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
+fi
+
+if [[ "${1:-}" == "--install-browser" ]]; then
+ shift
+ "$MVN" -f "$POM" -pl "$MODULE" -am install -DskipTests
+ "$MVN" -f "$ROOT/viewers/webcomponents/sample-vue-petclinic/pom.xml" -P"$PROFILE" \
+ -DskipTests test-compile \
+ -Dexec.mainClass=com.microsoft.playwright.CLI \
+ -Dexec.classpathScope=test \
+ -Dexec.args="install chromium" \
+ exec:java
+fi
+
+exec "$MVN" -f "$POM" -pl "$MODULE" -am -P"$PROFILE" \
+ -Dtest=PetClinicVueApplicationIntegTest,PetClinicVuePlaywrightTest \
+ -Dsurefire.failIfNoSpecifiedTests=false \
+ test \
+ "$@"