From 8f6a974fbe40056c9e55e4423a3988e7f8b9cb5d Mon Sep 17 00:00:00 2001
From: Simon Laden <simon.laden@azul.com>
Date: Tue, 14 Jul 2026 16:23:06 +0100
Subject: [PATCH] FISH-12503 - add Playwright tests + clean up code

---
 ecosystem/testcontainers-example/README.md    |  19 +-
 ecosystem/testcontainers-example/pom.xml      |  33 ++-
 .../fish/payara/examples/domain/Book.java     |  70 +++---
 .../payara/examples/domain/Librarian.java     |  80 ++++---
 .../fish/payara/examples/domain/Loan.java     |  63 +++---
 .../fish/payara/examples/domain/Patron.java   |  69 +++---
 .../payara/examples/resource/BookBean.java    |   4 +-
 .../examples/resource/LibrarianBean.java      |   7 +-
 .../payara/examples/resource/PatronBean.java  |   4 +-
 .../src/main/webapp/book.xhtml                |   6 +-
 .../src/main/webapp/librarian.xhtml           |   6 +-
 .../src/main/webapp/patron.xhtml              |   6 +-
 .../examples/service/AbstractServiceIT.java   |  43 ++++
 .../examples/service/BookServiceIT.java       |  68 ++----
 .../examples/service/LibrarianServiceIT.java  |  48 +----
 .../examples/service/PatronServiceIT.java     |  45 ++--
 .../testcontainers/AbstractContainerIT.java   |  63 ++++++
 .../testcontainers/PayaraMicroContainer.java  |  41 +++-
 .../fish/payara/examples/ui/AbstractUiIT.java | 199 ++++++++++++++++++
 .../fish/payara/examples/ui/BookUiIT.java     |  68 ++++++
 .../payara/examples/ui/LibrarianUiIT.java     |  63 ++++++
 .../fish/payara/examples/ui/LoanUiIT.java     | 103 +++++++++
 .../fish/payara/examples/ui/PatronUiIT.java   |  67 ++++++
 23 files changed, 921 insertions(+), 254 deletions(-)
 create mode 100644 ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/AbstractServiceIT.java
 create mode 100644 ecosystem/testcontainers-example/src/test/java/fish/payara/examples/testcontainers/AbstractContainerIT.java
 create mode 100644 ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/AbstractUiIT.java
 create mode 100644 ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/BookUiIT.java
 create mode 100644 ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/LibrarianUiIT.java
 create mode 100644 ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/LoanUiIT.java
 create mode 100644 ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/PatronUiIT.java

diff --git a/ecosystem/testcontainers-example/README.md b/ecosystem/testcontainers-example/README.md
index 07c7e0d..d4f1ee0 100644
--- a/ecosystem/testcontainers-example/README.md
+++ b/ecosystem/testcontainers-example/README.md
@@ -34,12 +34,29 @@ To run the tests for the application locally, follow these steps:
 
 2. Make sure you have the appropriate Java version installed.
 
-3. Execute the following command:
+3. Make sure [Docker](https://www.docker.com/products/docker-desktop/) is installed and running. The integration
+   tests (`*IT.java`) use [Testcontainers](https://testcontainers.com/) to start a real Payara Micro instance with
+   the application deployed, so Docker needs to be reachable from the JVM running the tests. If you hit
+   `Could not find a valid Docker environment` on Windows even though `docker` works fine from the shell, see
+   [Testcontainers' Windows troubleshooting guide](https://java.testcontainers.org/supported_docker_environment/windows/).
+
+4. Execute the following command:
 
 ```
 ./mvn clean verify
 ```
 
+### What gets tested
+
+- `*ServiceIT` (`fish.payara.examples.service`) — REST API tests hitting the deployed application directly with a
+  JAX-RS client.
+- `*UiIT` (`fish.payara.examples.ui`) — browser tests driving the JSF pages (Book, Patron, Librarian, Loan) end to
+  end with [Playwright](https://playwright.dev/java/). The Playwright Chromium browser binary is installed
+  automatically as part of the build (see the `exec-maven-plugin` execution in `pom.xml`) — no separate setup step
+  is needed.
+
+Both sets of IT tests share a single Payara Micro Testcontainer for the whole test run (see
+`fish.payara.examples.testcontainers.AbstractContainerIT`), so it's started once instead of once per test class.
 
 
 
diff --git a/ecosystem/testcontainers-example/pom.xml b/ecosystem/testcontainers-example/pom.xml
index 807133d..f174f6f 100644
--- a/ecosystem/testcontainers-example/pom.xml
+++ b/ecosystem/testcontainers-example/pom.xml
@@ -61,7 +61,7 @@
         <dependency>
             <groupId>org.testcontainers</groupId>
             <artifactId>junit-jupiter</artifactId>
-            <version>1.21.1</version>
+            <version>1.21.4</version>
             <scope>test</scope>
             <type>jar</type>
         </dependency>
@@ -118,6 +118,35 @@
                     <failOnMissingWebXml>false</failOnMissingWebXml>
                 </configuration>
             </plugin>
+            <!-- Installs the Playwright browser binaries (used by the *UiIT tests) before the
+                 integration-test phase runs. Uses exec:exec (a real child process) rather than
+                 exec:java, because com.microsoft.playwright.CLI calls System.exit() internally,
+                 which would otherwise kill the whole Maven JVM. -->
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <version>3.6.3</version>
+                <executions>
+                    <execution>
+                        <id>install-playwright-browsers</id>
+                        <phase>generate-test-resources</phase>
+                        <goals>
+                            <goal>exec</goal>
+                        </goals>
+                        <configuration>
+                            <executable>java</executable>
+                            <classpathScope>test</classpathScope>
+                            <arguments>
+                                <argument>-classpath</argument>
+                                <classpath/>
+                                <argument>com.microsoft.playwright.CLI</argument>
+                                <argument>install</argument>
+                                <argument>chromium</argument>
+                            </arguments>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
             <!-- Execute 'mvn clean package payara-micro:dev' to run the application. -->
             <plugin>
                 <groupId>fish.payara.maven.plugins</groupId>
@@ -201,6 +230,8 @@
                             </includes>
                             <systemPropertyVariables>
                                 <payara.microJar>${project.build.directory}/payara-micro-${payara.version}.jar</payara.microJar>
+                                <payara.version>${payara.version}</payara.version>
+                                <war.path>${project.build.directory}/${project.build.finalName}.war</war.path>
                             </systemPropertyVariables>
                         </configuration>
                     </execution>
diff --git a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Book.java b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Book.java
index 8420f65..5934d1d 100644
--- a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Book.java
+++ b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Book.java
@@ -4,6 +4,7 @@
 import java.util.Objects;
 
 import java.util.List;
+import java.util.UUID;
 import jakarta.json.bind.annotation.JsonbTransient;
 
 @NamedQueries({
@@ -15,10 +16,23 @@
 @Entity
 public class Book {
 
+    // Plain @Id, no @GeneratedValue, with an isBlank() check in @PrePersist:
+    // see Librarian.assignId() for the full explanation - book.xhtml's
+    // "Isbn:" field is a plain h:inputText bound directly to isbn, so saving
+    // it blank submits "" (not null) for this String property, which needs
+    // the same isBlank() guard to avoid persisting a literal empty-string id.
+    // Note: this is a generated surrogate key, not a real ISBN - the field
+    // name predates this fix.
     @Id
-    @GeneratedValue(strategy = GenerationType.AUTO)
     private String isbn;
 
+    @PrePersist
+    private void assignId() {
+        if (isbn == null || isbn.isBlank()) {
+            isbn = UUID.randomUUID().toString();
+        }
+    }
+
     private String title;
 
     private String author;
@@ -30,6 +44,33 @@ public class Book {
     private List<Loan> loans;
 
 
+    @Override
+    public int hashCode() {
+        int hash = 3;
+        hash = 97 * hash + Objects.hashCode(this.isbn);
+        return hash;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (obj == null) {
+            return false;
+        }
+        if (getClass() != obj.getClass()) {
+            return false;
+        }
+        final Book other = (Book) obj;
+        return Objects.equals(this.isbn, other.isbn);
+    }
+
+    @Override
+    public String toString() {
+        return String.valueOf(title);
+    }
+
     // Getters and setters
 
     public String getIsbn() {
@@ -72,31 +113,4 @@ public void setLoans(List<Loan> loans) {
         this.loans = loans;
     }
 
-    @Override
-    public int hashCode() {
-        int hash = 3;
-        hash = 97 * hash + Objects.hashCode(this.isbn);
-        return hash;
-    }
-
-    @Override
-    public boolean equals(Object obj) {
-        if (this == obj) {
-            return true;
-        }
-        if (obj == null) {
-            return false;
-        }
-        if (getClass() != obj.getClass()) {
-            return false;
-        }
-        final Book other = (Book) obj;
-        return Objects.equals(this.isbn, other.isbn);
-    }
-
-    @Override
-    public String toString() {
-        return String.valueOf(title);
-    }
-
 }
diff --git a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Librarian.java b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Librarian.java
index 749d69c..1d9c9b4 100644
--- a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Librarian.java
+++ b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Librarian.java
@@ -4,6 +4,7 @@
 import java.util.Objects;
 
 import java.util.List;
+import java.util.UUID;
 import jakarta.json.bind.annotation.JsonbTransient;
 
 @NamedQueries({
@@ -14,10 +15,33 @@
 @Entity
 public class Librarian {
 
+    // Plain @Id, no @GeneratedValue: JPA's generation strategies (IDENTITY/
+    // SEQUENCE/TABLE/AUTO) target numeric surrogate keys; for a String @Id
+    // we assign it ourselves in @PrePersist instead. Checking isBlank() (not
+    // just null) matters: librarian.xhtml's "Librarian ID:" field is a plain
+    // h:inputText bound directly to this property, and unlike a numeric
+    // property (where JSF's implicit converter turns an empty submission into
+    // null), a String property gets the submitted value verbatim - so saving
+    // the form with that field left blank sets librarianID to "" rather than
+    // null. That empty string is not null, so it silently passed the create/
+    // edit check as "already has an id" and, before this fix, also passed
+    // this method's null check unchanged - persisting the row with a literal
+    // empty-string id. It looked fine in this page's own list (name/actions
+    // still worked), but broke anything that keyed off "does this entity have
+    // an id yet": the loan.xhtml dropdown's converter treats "" the same as
+    // "no id" and renders it as an empty <option value="">, indistinguishable
+    // from the "no selection" placeholder - so selecting that librarian for a
+    // loan silently saved as no librarian at all.
     @Id
-    @GeneratedValue(strategy = GenerationType.AUTO)
     private String librarianID;
 
+    @PrePersist
+    private void assignId() {
+        if (librarianID == null || librarianID.isBlank()) {
+            librarianID = UUID.randomUUID().toString();
+        }
+    }
+
     private String name;
 
     private String department;
@@ -27,6 +51,33 @@ public class Librarian {
     private List<Loan> loansManageds;
 
 
+    @Override
+    public int hashCode() {
+        int hash = 3;
+        hash = 97 * hash + Objects.hashCode(this.librarianID);
+        return hash;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (obj == null) {
+            return false;
+        }
+        if (getClass() != obj.getClass()) {
+            return false;
+        }
+        final Librarian other = (Librarian) obj;
+        return Objects.equals(this.librarianID, other.librarianID);
+    }
+
+    @Override
+    public String toString() {
+        return String.valueOf(name);
+    }
+
     // Getters and setters
 
     public String getLibrarianID() {
@@ -61,31 +112,4 @@ public void setLoansManageds(List<Loan> loansManageds) {
         this.loansManageds = loansManageds;
     }
 
-    @Override
-    public int hashCode() {
-        int hash = 3;
-        hash = 97 * hash + Objects.hashCode(this.librarianID);
-        return hash;
-    }
-
-    @Override
-    public boolean equals(Object obj) {
-        if (this == obj) {
-            return true;
-        }
-        if (obj == null) {
-            return false;
-        }
-        if (getClass() != obj.getClass()) {
-            return false;
-        }
-        final Librarian other = (Librarian) obj;
-        return Objects.equals(this.librarianID, other.librarianID);
-    }
-
-    @Override
-    public String toString() {
-        return String.valueOf(name);
-    }
-
 }
diff --git a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Loan.java b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Loan.java
index 1d46ea5..e7f48bd 100644
--- a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Loan.java
+++ b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Loan.java
@@ -13,8 +13,15 @@
 @Entity
 public class Loan {
 
+    // GenerationType.TABLE (not AUTO or IDENTITY): EclipseLink's AUTO resolution for a
+    // numeric @Id on H2 still picks the platform's native IDENTITY column generation,
+    // which produces "INTEGER IDENTITY NOT NULL" DDL that this H2 version's parser
+    // rejects (a real schema-creation failure, not a test issue - see the container
+    // logs: CREATE TABLE LOAN fails, so the table never exists). TABLE forces the same
+    // EclipseLink default table-based generator (the SEQUENCE table) that Book/Patron/
+    // Librarian's AUTO-strategy String ids already use successfully.
     @Id
-    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @GeneratedValue(strategy = GenerationType.TABLE)
     private Integer loanID;
 
     private LocalDateTime loanDate;
@@ -34,6 +41,33 @@ public class Loan {
     private Book book;
 
 
+    @Override
+    public int hashCode() {
+        int hash = 3;
+        hash = 97 * hash + Objects.hashCode(this.loanID);
+        return hash;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (obj == null) {
+            return false;
+        }
+        if (getClass() != obj.getClass()) {
+            return false;
+        }
+        final Loan other = (Loan) obj;
+        return Objects.equals(this.loanID, other.loanID);
+    }
+
+    @Override
+    public String toString() {
+        return String.valueOf(loanID);
+    }
+
     // Getters and setters
 
     public Integer getLoanID() {
@@ -84,31 +118,4 @@ public void setBook(Book book) {
         this.book = book;
     }
 
-    @Override
-    public int hashCode() {
-        int hash = 3;
-        hash = 97 * hash + Objects.hashCode(this.loanID);
-        return hash;
-    }
-
-    @Override
-    public boolean equals(Object obj) {
-        if (this == obj) {
-            return true;
-        }
-        if (obj == null) {
-            return false;
-        }
-        if (getClass() != obj.getClass()) {
-            return false;
-        }
-        final Loan other = (Loan) obj;
-        return Objects.equals(this.loanID, other.loanID);
-    }
-
-    @Override
-    public String toString() {
-        return String.valueOf(loanID);
-    }
-
 }
diff --git a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Patron.java b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Patron.java
index e70ced6..8ea6d7a 100644
--- a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Patron.java
+++ b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/domain/Patron.java
@@ -4,6 +4,7 @@
 import java.util.Objects;
 
 import java.util.List;
+import java.util.UUID;
 import jakarta.json.bind.annotation.JsonbTransient;
 
 @NamedQueries({
@@ -15,10 +16,22 @@
 @Entity
 public class Patron {
 
+    // Plain @Id, no @GeneratedValue, with an isBlank() check in @PrePersist:
+    // see Librarian.assignId() for the full explanation - patron.xhtml's
+    // "Patron ID:" field is a plain h:inputText bound directly to patronID,
+    // so saving it blank submits "" (not null) for this String property,
+    // which needs the same isBlank() guard to avoid persisting a literal
+    // empty-string id.
     @Id
-    @GeneratedValue(strategy = GenerationType.AUTO)
     private String patronID;
 
+    @PrePersist
+    private void assignId() {
+        if (patronID == null || patronID.isBlank()) {
+            patronID = UUID.randomUUID().toString();
+        }
+    }
+
     private String name;
 
     private String address;
@@ -30,6 +43,33 @@ public class Patron {
     private List<Loan> loans;
 
 
+    @Override
+    public int hashCode() {
+        int hash = 3;
+        hash = 97 * hash + Objects.hashCode(this.patronID);
+        return hash;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (obj == null) {
+            return false;
+        }
+        if (getClass() != obj.getClass()) {
+            return false;
+        }
+        final Patron other = (Patron) obj;
+        return Objects.equals(this.patronID, other.patronID);
+    }
+
+    @Override
+    public String toString() {
+        return String.valueOf(name);
+    }
+
     // Getters and setters
 
     public String getPatronID() {
@@ -72,31 +112,4 @@ public void setLoans(List<Loan> loans) {
         this.loans = loans;
     }
 
-    @Override
-    public int hashCode() {
-        int hash = 3;
-        hash = 97 * hash + Objects.hashCode(this.patronID);
-        return hash;
-    }
-
-    @Override
-    public boolean equals(Object obj) {
-        if (this == obj) {
-            return true;
-        }
-        if (obj == null) {
-            return false;
-        }
-        if (getClass() != obj.getClass()) {
-            return false;
-        }
-        final Patron other = (Patron) obj;
-        return Objects.equals(this.patronID, other.patronID);
-    }
-
-    @Override
-    public String toString() {
-        return String.valueOf(name);
-    }
-
 }
diff --git a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/BookBean.java b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/BookBean.java
index 267ef9b..f08a31e 100644
--- a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/BookBean.java
+++ b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/BookBean.java
@@ -32,7 +32,9 @@ public String create() {
         return null;
     }
     public String save() {
-        if (book.getIsbn() == null) {
+        // isBlank(), not just == null: see LibrarianBean#save for why a
+        // plain h:inputText bound to a String id needs this guard too.
+        if (book.getIsbn() == null || book.getIsbn().isBlank()) {
              bookService.create(book);
         } else {
              bookService.edit(book);
diff --git a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/LibrarianBean.java b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/LibrarianBean.java
index b84990d..e887193 100644
--- a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/LibrarianBean.java
+++ b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/LibrarianBean.java
@@ -32,7 +32,12 @@ public String create() {
         return null;
     }
     public String save() {
-        if (librarian.getLibrarianID() == null) {
+        // isBlank(), not just == null: librarian.xhtml's id field is a plain
+        // h:inputText, so saving it with that field left blank submits ""
+        // rather than null (see Librarian.assignId() for the full story).
+        // Without this check, "" reads as "already has an id" and this would
+        // call edit()/merge() on a brand new librarian instead of create().
+        if (librarian.getLibrarianID() == null || librarian.getLibrarianID().isBlank()) {
              librarianService.create(librarian);
         } else {
              librarianService.edit(librarian);
diff --git a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/PatronBean.java b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/PatronBean.java
index 25e520a..c76327c 100644
--- a/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/PatronBean.java
+++ b/ecosystem/testcontainers-example/src/main/java/fish/payara/examples/resource/PatronBean.java
@@ -32,7 +32,9 @@ public String create() {
         return null;
     }
     public String save() {
-        if (patron.getPatronID() == null) {
+        // isBlank(), not just == null: see LibrarianBean#save for why a
+        // plain h:inputText bound to a String id needs this guard too.
+        if (patron.getPatronID() == null || patron.getPatronID().isBlank()) {
              patronService.create(patron);
         } else {
              patronService.edit(patron);
diff --git a/ecosystem/testcontainers-example/src/main/webapp/book.xhtml b/ecosystem/testcontainers-example/src/main/webapp/book.xhtml
index 7d95818..36cb667 100644
--- a/ecosystem/testcontainers-example/src/main/webapp/book.xhtml
+++ b/ecosystem/testcontainers-example/src/main/webapp/book.xhtml
@@ -9,9 +9,6 @@
         <p>Represents books available in the library.</p>
         <h:panelGrid columns="2" columnClasses="label,value" styleClass="table-form">
 
-            <h:outputLabel for="isbn" value="Isbn:" />
-            <h:inputText id="isbn" value="#{bookBean.book.isbn}" />
-
             <h:outputLabel for="title" value="Title:" />
             <h:inputText id="title" value="#{bookBean.book.title}" />
 
@@ -23,6 +20,9 @@
                 <f:passThroughAttribute name="type" value="number" />
             </h:inputText>
         </h:panelGrid>
+        <!-- Generated id: not user-editable (see Book.assignId()), same
+             pattern as loan.xhtml's loanID hidden field. -->
+        <h:inputHidden id="isbn" value="#{bookBean.book.isbn}" />
 
         <h:commandButton value="Save" action="#{bookBean.save}" styleClass="btn btn-primary mt-3" />
 
diff --git a/ecosystem/testcontainers-example/src/main/webapp/librarian.xhtml b/ecosystem/testcontainers-example/src/main/webapp/librarian.xhtml
index bda645b..76cd22f 100644
--- a/ecosystem/testcontainers-example/src/main/webapp/librarian.xhtml
+++ b/ecosystem/testcontainers-example/src/main/webapp/librarian.xhtml
@@ -9,15 +9,15 @@
         <p>Represents librarians managing the library.</p>
         <h:panelGrid columns="2" columnClasses="label,value" styleClass="table-form">
 
-            <h:outputLabel for="librarianID" value="Librarian ID:" />
-            <h:inputText id="librarianID" value="#{librarianBean.librarian.librarianID}" />
-
             <h:outputLabel for="name" value="Name:" />
             <h:inputText id="name" value="#{librarianBean.librarian.name}" />
 
             <h:outputLabel for="department" value="Department:" />
             <h:inputText id="department" value="#{librarianBean.librarian.department}" />
         </h:panelGrid>
+        <!-- Generated id: not user-editable (see Librarian.assignId()), same
+             pattern as loan.xhtml's loanID hidden field. -->
+        <h:inputHidden id="librarianID" value="#{librarianBean.librarian.librarianID}" />
 
         <h:commandButton value="Save" action="#{librarianBean.save}" styleClass="btn btn-primary mt-3" />
 
diff --git a/ecosystem/testcontainers-example/src/main/webapp/patron.xhtml b/ecosystem/testcontainers-example/src/main/webapp/patron.xhtml
index e6bff23..646a8ff 100644
--- a/ecosystem/testcontainers-example/src/main/webapp/patron.xhtml
+++ b/ecosystem/testcontainers-example/src/main/webapp/patron.xhtml
@@ -9,9 +9,6 @@
         <p>Represents library patrons who borrow books.</p>
         <h:panelGrid columns="2" columnClasses="label,value" styleClass="table-form">
 
-            <h:outputLabel for="patronID" value="Patron ID:" />
-            <h:inputText id="patronID" value="#{patronBean.patron.patronID}" />
-
             <h:outputLabel for="name" value="Name:" />
             <h:inputText id="name" value="#{patronBean.patron.name}" />
 
@@ -21,6 +18,9 @@
             <h:outputLabel for="email" value="Email:" />
             <h:inputText id="email" value="#{patronBean.patron.email}" />
         </h:panelGrid>
+        <!-- Generated id: not user-editable (see Patron.assignId()), same
+             pattern as loan.xhtml's loanID hidden field. -->
+        <h:inputHidden id="patronID" value="#{patronBean.patron.patronID}" />
 
         <h:commandButton value="Save" action="#{patronBean.save}" styleClass="btn btn-primary mt-3" />
 
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/AbstractServiceIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/AbstractServiceIT.java
new file mode 100644
index 0000000..08f50be
--- /dev/null
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/AbstractServiceIT.java
@@ -0,0 +1,43 @@
+package fish.payara.examples.service;
+
+import fish.payara.examples.testcontainers.AbstractContainerIT;
+import jakarta.ws.rs.client.Client;
+import jakarta.ws.rs.client.ClientBuilder;
+import jakarta.ws.rs.client.WebTarget;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+
+/**
+ * Base class for the REST integration tests running against the shared
+ * Payara Micro Testcontainer (see {@link AbstractContainerIT}).
+ *
+ * <p>Subclasses only need to implement {@link #resourcePath()} to say which
+ * REST resource they exercise; the JAX-RS {@link Client} and the
+ * {@link #baseTarget} pointing at that resource are set up and torn down
+ * automatically before/after each test.</p>
+ */
+abstract class AbstractServiceIT extends AbstractContainerIT {
+
+    protected Client client;
+    protected WebTarget baseTarget;
+
+    @BeforeEach
+    void setUpClient() {
+        client = ClientBuilder.newClient();
+        baseTarget = client.target(applicationContextUrl() + resourcePath());
+    }
+
+    @AfterEach
+    void tearDownClient() {
+        if (client != null) {
+            client.close();
+        }
+    }
+
+    /**
+     * Resource path, relative to the application's "application" context
+     * (see {@link fish.payara.examples.testcontainers.AbstractContainerIT#APPLICATION_CONTEXT}),
+     * exercised by the subclass, e.g. {@code "resources/books"}.
+     */
+    protected abstract String resourcePath();
+}
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/BookServiceIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/BookServiceIT.java
index 8082369..56e417e 100644
--- a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/BookServiceIT.java
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/BookServiceIT.java
@@ -1,53 +1,21 @@
 package fish.payara.examples.service;
 
 import fish.payara.examples.domain.Book;
-import org.junit.jupiter.api.Test;
-import fish.payara.examples.testcontainers.PayaraMicroContainer;
-import org.testcontainers.junit.jupiter.Container;
-import org.testcontainers.junit.jupiter.Testcontainers;
-import org.testcontainers.utility.DockerImageName;
-import jakarta.ws.rs.client.Client;
-import jakarta.ws.rs.core.GenericType;
-import jakarta.ws.rs.client.ClientBuilder;
 import jakarta.ws.rs.client.Entity;
-import jakarta.ws.rs.client.WebTarget;
+import jakarta.ws.rs.core.GenericType;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
 import java.util.List;
 
 import static org.junit.jupiter.api.Assertions.*;
 
-@Testcontainers
-class BookServiceIT {
-
-    private static final String PAYARA_MICRO_VERSION = "6.2025.10";
-    private static final int EXPOSED_PORT = 8080;
-
-    @Container
-    private final PayaraMicroContainer payara = new PayaraMicroContainer(
-            DockerImageName.parse("payara/micro:" + PAYARA_MICRO_VERSION))
-            .withExposedPorts(EXPOSED_PORT)
-            .withDeploymentPath("target/testcontainers-example-1.0.0.war");
-
-    private WebTarget baseTarget;
-    private Client client;
-
-    @AfterEach
-    void tearDown() {
-        if (client != null) {
-            client.close();
-        }
-    }
+class BookServiceIT extends AbstractServiceIT {
 
-    @BeforeEach
-    void setUp() {
-        client = ClientBuilder.newClient();
-                String appUrl = payara.getApplicationUrl();
-                String separator = appUrl.endsWith("/") ? "" : "/";
-        String baseUri = appUrl + separator + "application/resources/books";
-        baseTarget = client.target(baseUri);
+    @Override
+    protected String resourcePath() {
+        return "resources/books";
     }
 
     @Test
@@ -74,8 +42,7 @@ void testCreateAndRetrieveBook() {
                 }
 
                 if (createResponse.getStatus() != Response.Status.CREATED.getStatusCode()) {
-                        String logs = "<no logs>";
-                        try { logs = payara.getLogs(); } catch (Exception ignored) {}
+                        String logs = containerLogs();
                         String msg = String.format("POST failed, status=%d, body=%s, container-logs-start:\n%s\n:container-logs-end", createResponse.getStatus(), respBody, logs);
                         assertEquals(Response.Status.CREATED.getStatusCode(), createResponse.getStatus(), msg);
                 }
@@ -83,15 +50,15 @@ void testCreateAndRetrieveBook() {
         // Get the created book's ISBN from the Location header
         String location = createResponse.getHeaderString("Location");
         assertNotNull(location, "Location header missing; POST response body=" + respBody);
-        
+
         // GET the book and verify its contents
         Response getResponse = client.target(location)
                 .request(MediaType.APPLICATION_JSON)
                 .get();
-        
+
         assertEquals(Response.Status.OK.getStatusCode(), getResponse.getStatus());
         Book retrievedBook = getResponse.readEntity(Book.class);
-        
+
         assertNotNull(retrievedBook);
         assertEquals("Integration Test Book", retrievedBook.getTitle());
         assertEquals("Test Author", retrievedBook.getAuthor());
@@ -130,12 +97,11 @@ void testFindAllBooks() {
 
                         if (response.getStatus() != Response.Status.OK.getStatusCode()) {
                                 try { respBody = response.readEntity(String.class); } catch (Exception e) { respBody = "<no body>"; }
-                                String logs = "<no logs>";
-                                try { logs = payara.getLogs(); } catch (Exception ignored) {}
+                                String logs = containerLogs();
                                 String msg = String.format("GET all failed, status=%d, body=%s, container-logs-start:\n%s\n:container-logs-end", response.getStatus(), respBody, logs);
                                 assertEquals(Response.Status.OK.getStatusCode(), response.getStatus(), msg);
                         }
-        
+
                 List<Book> books = response.readEntity(new GenericType<List<Book>>() {});
                 assertNotNull(books);
                 assertTrue(books.size() >= 2);
@@ -153,7 +119,7 @@ void testUpdateBook() {
         Response createResponse = baseTarget
                 .request(MediaType.APPLICATION_JSON)
                 .post(Entity.entity(book, MediaType.APPLICATION_JSON));
-        
+
         String location = createResponse.getHeaderString("Location");
         assertNotNull(location, "Location header missing after create");
         Book createdBook = client.target(location)
@@ -162,7 +128,7 @@ void testUpdateBook() {
 
         // Update the book
         createdBook.setTitle("Updated Title");
-        
+
         Response updateResponse = client.target(location)
                 .request(MediaType.APPLICATION_JSON)
                 .put(Entity.entity(createdBook, MediaType.APPLICATION_JSON));
@@ -190,7 +156,7 @@ void testDeleteBook() {
         Response createResponse = baseTarget
                 .request(MediaType.APPLICATION_JSON)
                 .post(Entity.entity(book, MediaType.APPLICATION_JSON));
-        
+
         String location = createResponse.getHeaderString("Location");
         assertNotNull(location, "Location header missing after create");
 
@@ -208,4 +174,4 @@ void testDeleteBook() {
 
         assertEquals(Response.Status.NOT_FOUND.getStatusCode(), getResponse.getStatus());
     }
-}
\ No newline at end of file
+}
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/LibrarianServiceIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/LibrarianServiceIT.java
index 90b918a..069bab3 100644
--- a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/LibrarianServiceIT.java
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/LibrarianServiceIT.java
@@ -1,53 +1,25 @@
 package fish.payara.examples.service;
 
 import fish.payara.examples.domain.Librarian;
-import fish.payara.examples.testcontainers.PayaraMicroContainer;
-import jakarta.ws.rs.client.Client;
-import jakarta.ws.rs.client.ClientBuilder;
 import jakarta.ws.rs.client.Entity;
-import jakarta.ws.rs.client.WebTarget;
 import jakarta.ws.rs.core.GenericType;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
-import org.junit.jupiter.api.*;
-import org.testcontainers.junit.jupiter.Container;
-import org.testcontainers.junit.jupiter.Testcontainers;
-import org.testcontainers.utility.DockerImageName;
+import org.junit.jupiter.api.MethodOrderer;
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestMethodOrder;
 
 import java.util.List;
 
 import static org.junit.jupiter.api.Assertions.*;
 
-@Testcontainers
 @TestMethodOrder(MethodOrderer.OrderAnnotation.class)
-class LibrarianServiceIT {
-
-    private static final String PAYARA_MICRO_VERSION = "6.2025.10";
-    private static final int EXPOSED_PORT = 8080;
-
-    @Container
-    private static final PayaraMicroContainer payara = new PayaraMicroContainer(
-            DockerImageName.parse("payara/micro:" + PAYARA_MICRO_VERSION))
-            .withExposedPorts(EXPOSED_PORT)
-            .withDeploymentPath("target/testcontainers-example-1.0.0.war");
-
-    private Client client;
-    private WebTarget baseTarget;
-
-    @BeforeEach
-    void setUp() {
-        client = ClientBuilder.newClient();
-        String appUrl = payara.getApplicationUrl();
-        String separator = appUrl.endsWith("/") ? "" : "/";
-        String baseUri = appUrl + separator + "application/resources/librarians";
-        baseTarget = client.target(baseUri);
-    }
+class LibrarianServiceIT extends AbstractServiceIT {
 
-    @AfterEach
-    void tearDown() {
-        if (client != null) {
-            client.close();
-        }
+    @Override
+    protected String resourcePath() {
+        return "resources/librarians";
     }
 
     @Test
@@ -75,7 +47,7 @@ void testCreateAndRetrieveLibrarian() throws Exception {
             } catch (Exception e) {
                 respBody = "<no body>";
             }
-            String logs = payara.getLogs();
+            String logs = containerLogs();
             String msg = String.format("POST failed, status=%d, body=%s, container logs:\n%s", createResponse.getStatus(), respBody, logs);
             assertEquals(Response.Status.CREATED.getStatusCode(), createResponse.getStatus(), msg);
         }
@@ -113,7 +85,7 @@ void testFindAllLibrarians() throws Exception {
             } catch (Exception e) {
                 respBody = "<no body>";
             }
-            String logs = payara.getLogs();
+            String logs = containerLogs();
             String msg = String.format("GET all failed, status=%d, body=%s, logs:\n%s", response.getStatus(), respBody, logs);
             assertEquals(Response.Status.OK.getStatusCode(), response.getStatus(), msg);
         }
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/PatronServiceIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/PatronServiceIT.java
index 0b67b1d..730fdd5 100644
--- a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/PatronServiceIT.java
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/service/PatronServiceIT.java
@@ -1,46 +1,25 @@
 package fish.payara.examples.service;
 
 import fish.payara.examples.domain.Patron;
-import fish.payara.examples.testcontainers.PayaraMicroContainer;
-import jakarta.ws.rs.client.*;
-import jakarta.ws.rs.core.*;
-import org.junit.jupiter.api.*;
-import org.testcontainers.junit.jupiter.Container;
-import org.testcontainers.junit.jupiter.Testcontainers;
-import org.testcontainers.utility.DockerImageName;
+import jakarta.ws.rs.client.Entity;
+import jakarta.ws.rs.core.GenericType;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import org.junit.jupiter.api.MethodOrderer;
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestMethodOrder;
 
 import java.util.List;
 
 import static org.junit.jupiter.api.Assertions.*;
 
-@Testcontainers
 @TestMethodOrder(MethodOrderer.OrderAnnotation.class)
-class PatronServiceIT {
-
-    private static final String PAYARA_MICRO_VERSION = "6.2025.10";
-    private static final int EXPOSED_PORT = 8080;
-
-    @Container
-    private static final PayaraMicroContainer payara = new PayaraMicroContainer(
-            DockerImageName.parse("payara/micro:" + PAYARA_MICRO_VERSION))
-            .withExposedPorts(EXPOSED_PORT)
-            .withDeploymentPath("target/testcontainers-example-1.0.0.war");
-
-    private Client client;
-    private WebTarget baseTarget;
-
-    @BeforeEach
-    void setUp() {
-        client = ClientBuilder.newClient();
-        String appUrl = payara.getApplicationUrl();
-        String separator = appUrl.endsWith("/") ? "" : "/";
-        String baseUri = appUrl + separator + "application/resources/patrons";
-        baseTarget = client.target(baseUri);
-    }
+class PatronServiceIT extends AbstractServiceIT {
 
-    @AfterEach
-    void tearDown() {
-        client.close();
+    @Override
+    protected String resourcePath() {
+        return "resources/patrons";
     }
 
     @Test
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/testcontainers/AbstractContainerIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/testcontainers/AbstractContainerIT.java
new file mode 100644
index 0000000..6b8731e
--- /dev/null
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/testcontainers/AbstractContainerIT.java
@@ -0,0 +1,63 @@
+package fish.payara.examples.testcontainers;
+
+/**
+ * Base class for every integration test that needs a running Payara Micro
+ * instance with the application deployed, whether it is exercised over REST
+ * (see the {@code *ServiceIT} classes) or through a browser with Playwright
+ * (see the {@code *UiIT} classes).
+ *
+ * <p>This deliberately does <b>not</b> use {@code @Testcontainers}/{@code @Container}.
+ * Those JUnit 5 annotations manage the container's lifecycle per test class:
+ * a static container gets started in that class's {@code beforeAll} and, in
+ * some circumstances, stopped again in its {@code afterAll} once that class's
+ * tests are done - which is exactly wrong for a container meant to be shared
+ * by several test classes, since whichever class happens to run first ends up
+ * tearing the container down again before the next class's tests get a
+ * chance to run against it.</p>
+ *
+ * <p>Instead this follows Testcontainers' documented
+ * <a href="https://java.testcontainers.org/test_framework_integration/manual_lifecycle_control/">
+ * "singleton container"</a> pattern: the container is started eagerly, exactly
+ * once, in a static initializer (guaranteed by the JVM's class-initialization
+ * semantics to run at most once no matter how many subclasses trigger it), and
+ * is never explicitly stopped - Testcontainers' own Ryuk reaper cleans it up
+ * when the JVM (the forked failsafe JVM running the whole IT suite) exits.</p>
+ */
+public abstract class AbstractContainerIT {
+
+    /**
+     * Context path the WAR is deployed under inside the container. Payara
+     * Micro's autodeploy derives the context root from the deployed file's
+     * name, and {@link PayaraMicroContainer#withDeploymentPath} always copies
+     * the WAR in as {@code application.war}, so this is always "application" -
+     * it's not the project's artifact name.
+     */
+    protected static final String APPLICATION_CONTEXT = "application/";
+
+    protected static final PayaraMicroContainer payara;
+
+    static {
+        payara = new PayaraMicroContainer();
+        payara.start();
+    }
+
+    /** Base URL of the deployed application, always ending with a trailing slash. */
+    protected static String applicationUrl() {
+        String appUrl = payara.getApplicationUrl();
+        return appUrl.endsWith("/") ? appUrl : appUrl + "/";
+    }
+
+    /** Base URL of the deployed application's "application" context, ending with a trailing slash. */
+    protected static String applicationContextUrl() {
+        return applicationUrl() + APPLICATION_CONTEXT;
+    }
+
+    /** Container logs, safe to call even if the container failed to start. */
+    protected static String containerLogs() {
+        try {
+            return payara.getLogs();
+        } catch (Exception e) {
+            return "<no logs>";
+        }
+    }
+}
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/testcontainers/PayaraMicroContainer.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/testcontainers/PayaraMicroContainer.java
index b636f2b..7eb1943 100644
--- a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/testcontainers/PayaraMicroContainer.java
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/testcontainers/PayaraMicroContainer.java
@@ -5,27 +5,46 @@
 import org.testcontainers.utility.DockerImageName;
 import org.testcontainers.utility.MountableFile;
 
+/**
+ * A Testcontainers {@link GenericContainer} pre-configured to run Payara Micro
+ * with the application WAR deployed.
+ *
+ * <p>The no-arg constructor is fully self-configuring: it reads the Payara
+ * Micro version and the path to the WAR file from the {@code payara.version}
+ * and {@code war.path} system properties. Those properties are populated from
+ * the Maven {@code payara.version} property and the build output directory by
+ * the failsafe plugin (see pom.xml), so the version only needs to be defined
+ * once for the whole build instead of being repeated in every IT test.</p>
+ */
 public class PayaraMicroContainer extends GenericContainer<PayaraMicroContainer> {
-    
+
     private static final int DEFAULT_PORT = 8080;
     private static final String DEFAULT_CONTEXT_PATH = "/";
     protected static final String CONTEXT = "ObservabilityTool";
-    
+
+    /**
+     * Fully self-configured container: version and WAR path are resolved from
+     * the {@code payara.version} / {@code war.path} system properties set by Maven.
+     */
+    public PayaraMicroContainer() {
+        this(DockerImageName.parse("payara/micro:" + requiredProperty("payara.version")));
+        withDeploymentPath(requiredProperty("war.path"));
+    }
+
     public PayaraMicroContainer(DockerImageName dockerImageName) {
         super(dockerImageName);
         withExposedPorts(DEFAULT_PORT);
         waitingFor(Wait.forLogMessage(".*Payara Micro .* ready.*\\n", 1));
-
     }
-    
+
     public PayaraMicroContainer withDeploymentPath(String warPath) {
         withCopyFileToContainer(
-            MountableFile.forHostPath(warPath), 
+            MountableFile.forHostPath(warPath),
             "/opt/payara/deployments/application.war"
         );
         return this;
     }
-    
+
     public String getApplicationUrl() {
         return String.format(
             "http://%s:%d%s",
@@ -34,4 +53,14 @@ public String getApplicationUrl() {
             DEFAULT_CONTEXT_PATH
         );
     }
+
+    private static String requiredProperty(String name) {
+        String value = System.getProperty(name);
+        if (value == null || value.isBlank()) {
+            throw new IllegalStateException(
+                "System property '" + name + "' is not set. It must be supplied by the Maven build "
+                    + "(see the failsafe plugin's systemPropertyVariables in pom.xml).");
+        }
+        return value;
+    }
 }
\ No newline at end of file
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/AbstractUiIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/AbstractUiIT.java
new file mode 100644
index 0000000..a20aa87
--- /dev/null
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/AbstractUiIT.java
@@ -0,0 +1,199 @@
+package fish.payara.examples.ui;
+
+import com.microsoft.playwright.Browser;
+import com.microsoft.playwright.BrowserContext;
+import com.microsoft.playwright.BrowserType;
+import com.microsoft.playwright.Dialog;
+import com.microsoft.playwright.Locator;
+import com.microsoft.playwright.Page;
+import com.microsoft.playwright.Playwright;
+import com.microsoft.playwright.options.AriaRole;
+import fish.payara.examples.testcontainers.AbstractContainerIT;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.junit.jupiter.api.extension.TestWatcher;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Base class for browser-driven UI tests exercising the JSF pages of the
+ * application through Playwright, running against the same Payara Micro
+ * Testcontainer shared with the REST IT tests (see {@link AbstractContainerIT}).
+ *
+ * <p>One headless Chromium instance is launched per test class (JUnit 5 runs
+ * {@code @BeforeAll}/{@code @AfterAll} around each concrete subclass); each
+ * individual test then gets its own {@link BrowserContext}/{@link Page} so
+ * tests don't leak cookies or state into one another. Note: the Playwright
+ * {@code chromium} browser binary needs to be installed once, which the
+ * build's {@code generate-test-resources} phase does automatically (see the
+ * exec-maven-plugin execution in pom.xml).</p>
+ *
+ * <p>On failure, a screenshot, the page's HTML, its URL and the Payara
+ * container logs are dumped under {@code target/playwright-failures/} (see
+ * {@link FailureDiagnostics}) so a failing test is debuggable from the build
+ * output alone, without having to reproduce it interactively.</p>
+ */
+@ExtendWith(AbstractUiIT.FailureDiagnostics.class)
+public abstract class AbstractUiIT extends AbstractContainerIT {
+
+    private static Playwright playwright;
+    private static Browser browser;
+
+    protected BrowserContext context;
+    protected Page page;
+
+    @BeforeAll
+    static void launchBrowser() {
+        playwright = Playwright.create();
+        browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(true));
+    }
+
+    @AfterAll
+    static void closeBrowser() {
+        if (browser != null) {
+            browser.close();
+        }
+        if (playwright != null) {
+            playwright.close();
+        }
+    }
+
+    @BeforeEach
+    void newPage() {
+        context = browser.newContext();
+        page = context.newPage();
+        // The "Delete" links use a JS confirm() dialog; always accept it so
+        // delete flows don't need to register their own handler.
+        page.onDialog(Dialog::accept);
+    }
+
+    /**
+     * Navigates to a JSF page relative to the deployed application's
+     * "application" context, e.g. {@code "book.xhtml"} navigates to
+     * {@code http://host:port/application/book.xhtml} - the JSF pages live in
+     * the same WAR as the REST resources, under the same context path (see
+     * {@link fish.payara.examples.testcontainers.AbstractContainerIT#APPLICATION_CONTEXT}).
+     */
+    protected Page navigateTo(String relativePath) {
+        page.navigate(applicationContextUrl() + relativePath);
+        return page;
+    }
+
+    /** Clicks the form's "Save" button (an {@code h:commandButton}, so it has no stable id). */
+    protected void clickSave() {
+        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Save")).click();
+    }
+
+    /**
+     * Locates the {@code h:dataTable} row containing the given text (e.g. a
+     * title or name). Scoped to {@code table.table-striped} - every page's
+     * {@code h:dataTable} is rendered with that class (see e.g. book.xhtml),
+     * while the entry form above it is a separate {@code h:panelGrid}
+     * ("table-form" class) that also renders as an HTML {@code <table>}. That
+     * distinction matters on loan.xhtml in particular: a {@code <select>}'s
+     * full option list counts as "text" for Playwright's hasText matching, so
+     * an unscoped locator would match the librarian/patron/book dropdown's
+     * row in the form instead of the actual data row. Matches any
+     * {@code <tr>} rather than assuming a {@code <tbody>} wrapper, since
+     * {@code h:dataTable} doesn't always render one.
+     */
+    protected Locator rowContaining(String text) {
+        return page.locator("table.table-striped tr", new Page.LocatorOptions().setHasText(text));
+    }
+
+    /**
+     * The container's Payara instance and its database live for the whole test
+     * run, so test data isn't reset between tests. Suffix human-readable values
+     * with this to keep rows unique and independent of what other tests wrote.
+     */
+    protected static String unique(String prefix) {
+        return prefix + "-" + UUID.randomUUID().toString().substring(0, 8);
+    }
+
+    /**
+     * On test failure, saves a screenshot, the current page's HTML/URL, and
+     * the Payara container logs to {@code target/playwright-failures/}, named
+     * after the failing test. Best-effort: any problem while writing the
+     * diagnostics is swallowed so it never masks the original failure.
+     *
+     * <p>This also owns closing the {@link BrowserContext} for every outcome
+     * (pass, fail, abort, disabled) instead of an {@code @AfterEach} method,
+     * because JUnit 5 runs {@code @AfterEach} - and therefore would have
+     * closed the page - <b>before</b> invoking {@link TestWatcher} callbacks.
+     * With cleanup in {@code @AfterEach}, {@link #testFailed} would always
+     * see an already-closed page and silently skip the screenshot/HTML
+     * capture (which is exactly what happened before this class took over
+     * closing: only the container log, which doesn't need the page, was ever
+     * written).</p>
+     */
+    static final class FailureDiagnostics implements TestWatcher {
+
+        @Override
+        public void testFailed(ExtensionContext context, Throwable cause) {
+            withTestInstance(context, test -> {
+                captureDiagnostics(context, test);
+                closeContext(test);
+            });
+        }
+
+        @Override
+        public void testSuccessful(ExtensionContext context) {
+            withTestInstance(context, this::closeContext);
+        }
+
+        @Override
+        public void testAborted(ExtensionContext context, Throwable cause) {
+            withTestInstance(context, this::closeContext);
+        }
+
+        @Override
+        public void testDisabled(ExtensionContext context, Optional<String> reason) {
+            withTestInstance(context, this::closeContext);
+        }
+
+        private void withTestInstance(ExtensionContext context, java.util.function.Consumer<AbstractUiIT> action) {
+            Object testInstance = context.getRequiredTestInstance();
+            if (testInstance instanceof AbstractUiIT) {
+                action.accept((AbstractUiIT) testInstance);
+            }
+        }
+
+        private void captureDiagnostics(ExtensionContext context, AbstractUiIT test) {
+            String name = context.getRequiredTestClass().getSimpleName() + "-" + context.getRequiredTestMethod().getName();
+            try {
+                Path dir = Path.of("target", "playwright-failures");
+                Files.createDirectories(dir);
+                if (test.page != null && !test.page.isClosed()) {
+                    test.page.screenshot(new Page.ScreenshotOptions().setPath(dir.resolve(name + ".png")).setFullPage(true));
+                    writeString(dir.resolve(name + ".html"), test.page.content());
+                    writeString(dir.resolve(name + ".url.txt"), test.page.url());
+                }
+                writeString(dir.resolve(name + ".container.log"), AbstractUiIT.containerLogs());
+            } catch (Exception diagnosticsFailure) {
+                // Best-effort: never let diagnostics collection hide the real test failure.
+            }
+        }
+
+        private void closeContext(AbstractUiIT test) {
+            if (test.context != null) {
+                try {
+                    test.context.close();
+                } catch (Exception ignored) {
+                    // Best-effort cleanup.
+                }
+            }
+        }
+
+        private static void writeString(Path path, String content) throws IOException {
+            Files.write(path, content.getBytes(StandardCharsets.UTF_8));
+        }
+    }
+}
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/BookUiIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/BookUiIT.java
new file mode 100644
index 0000000..2f3b3a5
--- /dev/null
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/BookUiIT.java
@@ -0,0 +1,68 @@
+package fish.payara.examples.ui;
+
+import com.microsoft.playwright.Locator;
+import com.microsoft.playwright.options.AriaRole;
+import org.junit.jupiter.api.Test;
+
+import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
+
+/**
+ * Exercises the "Book" JSF page (book.xhtml): create, edit and delete a book
+ * through the browser, driven by Playwright against the deployed application.
+ */
+class BookUiIT extends AbstractUiIT {
+
+    @Test
+    void createsABookAndShowsItInTheList() {
+        String title = unique("Playwright Book");
+
+        navigateTo("book.xhtml");
+        // Leave the Isbn field blank: the id is auto-generated on create, same
+        // as the REST API path (see BookBean#save / AbstractService#create).
+        page.getByLabel("Title:").fill(title);
+        page.getByLabel("Author:").fill("Jane Author");
+        page.getByLabel("Pages:").fill("123");
+        clickSave();
+
+        Locator row = rowContaining(title);
+        assertThat(row).isVisible();
+        assertThat(row).containsText("Jane Author");
+        assertThat(row).containsText("123");
+    }
+
+    @Test
+    void editsABook() {
+        String title = unique("Book To Edit");
+        String updatedTitle = unique("Updated Book");
+
+        navigateTo("book.xhtml");
+        page.getByLabel("Title:").fill(title);
+        page.getByLabel("Author:").fill("Original Author");
+        page.getByLabel("Pages:").fill("50");
+        clickSave();
+
+        rowContaining(title).getByRole(AriaRole.LINK, new Locator.GetByRoleOptions().setName("Edit")).click();
+        page.getByLabel("Title:").fill(updatedTitle);
+        clickSave();
+
+        assertThat(rowContaining(updatedTitle)).containsText("Original Author");
+        assertThat(rowContaining(title)).hasCount(0);
+    }
+
+    @Test
+    void deletesABook() {
+        String title = unique("Book To Delete");
+
+        navigateTo("book.xhtml");
+        page.getByLabel("Title:").fill(title);
+        page.getByLabel("Author:").fill("Delete Author");
+        page.getByLabel("Pages:").fill("10");
+        clickSave();
+
+        assertThat(rowContaining(title)).isVisible();
+
+        rowContaining(title).getByRole(AriaRole.LINK, new Locator.GetByRoleOptions().setName("Delete")).click();
+
+        assertThat(rowContaining(title)).hasCount(0);
+    }
+}
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/LibrarianUiIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/LibrarianUiIT.java
new file mode 100644
index 0000000..06671a9
--- /dev/null
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/LibrarianUiIT.java
@@ -0,0 +1,63 @@
+package fish.payara.examples.ui;
+
+import com.microsoft.playwright.Locator;
+import com.microsoft.playwright.options.AriaRole;
+import org.junit.jupiter.api.Test;
+
+import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
+
+/**
+ * Exercises the "Librarian" JSF page (librarian.xhtml): create, edit and
+ * delete a librarian through the browser, driven by Playwright against the
+ * deployed application.
+ */
+class LibrarianUiIT extends AbstractUiIT {
+
+    @Test
+    void createsALibrarianAndShowsItInTheList() {
+        String name = unique("Playwright Librarian");
+
+        navigateTo("librarian.xhtml");
+        // Leave the Librarian ID field blank: it's auto-generated on create,
+        // same as the REST API path (see LibrarianBean#save / AbstractService#create).
+        page.getByLabel("Name:").fill(name);
+        page.getByLabel("Department:").fill("Circulation");
+        clickSave();
+
+        Locator row = rowContaining(name);
+        assertThat(row).isVisible();
+        assertThat(row).containsText("Circulation");
+    }
+
+    @Test
+    void editsALibrarian() {
+        String name = unique("Librarian To Edit");
+
+        navigateTo("librarian.xhtml");
+        page.getByLabel("Name:").fill(name);
+        page.getByLabel("Department:").fill("Old Department");
+        clickSave();
+
+        rowContaining(name).getByRole(AriaRole.LINK, new Locator.GetByRoleOptions().setName("Edit")).click();
+        page.getByLabel("Department:").fill("New Department");
+        clickSave();
+
+        assertThat(rowContaining(name)).containsText("New Department");
+    }
+
+    @Test
+    void deletesALibrarian() {
+        String name = unique("Librarian To Delete");
+
+        navigateTo("librarian.xhtml");
+        page.getByLabel("Name:").fill(name);
+        page.getByLabel("Department:").fill("Doomed Department");
+        clickSave();
+
+        assertThat(rowContaining(name)).isVisible();
+
+        rowContaining(name).getByRole(AriaRole.LINK, new Locator.GetByRoleOptions().setName("Delete")).click();
+
+        assertThat(rowContaining(name)).hasCount(0);
+    }
+}
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/LoanUiIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/LoanUiIT.java
new file mode 100644
index 0000000..4a7875b
--- /dev/null
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/LoanUiIT.java
@@ -0,0 +1,103 @@
+package fish.payara.examples.ui;
+
+import com.microsoft.playwright.Locator;
+import com.microsoft.playwright.options.AriaRole;
+import com.microsoft.playwright.options.SelectOption;
+import org.junit.jupiter.api.Test;
+
+import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
+
+/**
+ * Exercises the "Loan" JSF page (loan.xhtml). Unlike the other entities, a
+ * loan is created by picking an existing librarian, patron and book from
+ * dropdowns, so this test first creates one of each through their own pages
+ * (reusing the same browser session) before creating, editing and deleting
+ * the loan itself.
+ */
+class LoanUiIT extends AbstractUiIT {
+
+    @Test
+    void createsALoanFromAnExistingLibrarianPatronAndBook() {
+        String librarianName = unique("Loan Librarian");
+        String patronName = unique("Loan Patron");
+        String bookTitle = unique("Loan Book");
+
+        createLibrarian(librarianName);
+        createPatron(patronName);
+        createBook(bookTitle);
+        fillAndSaveLoan(librarianName, patronName, bookTitle, "2026-07-14T09:00", "2026-07-28T09:00");
+
+        Locator row = rowContaining(librarianName);
+        assertThat(row).isVisible();
+        assertThat(row).containsText(patronName);
+        assertThat(row).containsText(bookTitle);
+        assertThat(row).containsText("2026-07-14T09:00");
+    }
+
+    @Test
+    void editsALoan() {
+        String librarianName = unique("Loan Librarian Edit");
+        String patronName = unique("Loan Patron Edit");
+        String bookTitle = unique("Loan Book Edit");
+
+        createLibrarian(librarianName);
+        createPatron(patronName);
+        createBook(bookTitle);
+        fillAndSaveLoan(librarianName, patronName, bookTitle, "2026-07-14T09:00", "2026-07-28T09:00");
+
+        rowContaining(librarianName).getByRole(AriaRole.LINK, new Locator.GetByRoleOptions().setName("Edit")).click();
+        page.getByLabel("Return Date:").fill("2026-08-04T09:00");
+        clickSave();
+
+        assertThat(rowContaining(librarianName)).containsText("2026-08-04T09:00");
+    }
+
+    @Test
+    void deletesALoan() {
+        String librarianName = unique("Loan Librarian Delete");
+        String patronName = unique("Loan Patron Delete");
+        String bookTitle = unique("Loan Book Delete");
+
+        createLibrarian(librarianName);
+        createPatron(patronName);
+        createBook(bookTitle);
+        fillAndSaveLoan(librarianName, patronName, bookTitle, "2026-07-14T09:00", "2026-07-28T09:00");
+
+        assertThat(rowContaining(librarianName)).isVisible();
+
+        rowContaining(librarianName).getByRole(AriaRole.LINK, new Locator.GetByRoleOptions().setName("Delete")).click();
+
+        assertThat(rowContaining(librarianName)).hasCount(0);
+    }
+
+    private void createLibrarian(String name) {
+        navigateTo("librarian.xhtml");
+        page.getByLabel("Name:").fill(name);
+        clickSave();
+    }
+
+    private void createPatron(String name) {
+        navigateTo("patron.xhtml");
+        page.getByLabel("Name:").fill(name);
+        clickSave();
+    }
+
+    private void createBook(String title) {
+        navigateTo("book.xhtml");
+        page.getByLabel("Title:").fill(title);
+        page.getByLabel("Author:").fill("Loan Test Author");
+        page.getByLabel("Pages:").fill("42");
+        clickSave();
+    }
+
+    private void fillAndSaveLoan(String librarianName, String patronName, String bookTitle,
+                                 String loanDate, String returnDate) {
+        navigateTo("loan.xhtml");
+        page.getByLabel("Loan Date:").fill(loanDate);
+        page.getByLabel("Return Date:").fill(returnDate);
+        page.getByLabel("Librarian:").selectOption(new SelectOption().setLabel(librarianName));
+        page.getByLabel("Patron:").selectOption(new SelectOption().setLabel(patronName));
+        page.getByLabel("Book:").selectOption(new SelectOption().setLabel(bookTitle));
+        clickSave();
+    }
+}
diff --git a/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/PatronUiIT.java b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/PatronUiIT.java
new file mode 100644
index 0000000..eb0163f
--- /dev/null
+++ b/ecosystem/testcontainers-example/src/test/java/fish/payara/examples/ui/PatronUiIT.java
@@ -0,0 +1,67 @@
+package fish.payara.examples.ui;
+
+import com.microsoft.playwright.Locator;
+import com.microsoft.playwright.options.AriaRole;
+import org.junit.jupiter.api.Test;
+
+import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
+
+/**
+ * Exercises the "Patron" JSF page (patron.xhtml): create, edit and delete a
+ * patron through the browser, driven by Playwright against the deployed
+ * application.
+ */
+class PatronUiIT extends AbstractUiIT {
+
+    @Test
+    void createsAPatronAndShowsItInTheList() {
+        String name = unique("Playwright Patron");
+
+        navigateTo("patron.xhtml");
+        // Leave the Patron ID field blank: it's auto-generated on create, same
+        // as the REST API path (see PatronBean#save / AbstractService#create).
+        page.getByLabel("Name:").fill(name);
+        page.getByLabel("Address:").fill("1 Library Way");
+        page.getByLabel("Email:").fill("patron@example.com");
+        clickSave();
+
+        Locator row = rowContaining(name);
+        assertThat(row).isVisible();
+        assertThat(row).containsText("1 Library Way");
+        assertThat(row).containsText("patron@example.com");
+    }
+
+    @Test
+    void editsAPatron() {
+        String name = unique("Patron To Edit");
+
+        navigateTo("patron.xhtml");
+        page.getByLabel("Name:").fill(name);
+        page.getByLabel("Address:").fill("Old Address");
+        page.getByLabel("Email:").fill("old@example.com");
+        clickSave();
+
+        rowContaining(name).getByRole(AriaRole.LINK, new Locator.GetByRoleOptions().setName("Edit")).click();
+        page.getByLabel("Email:").fill("new@example.com");
+        clickSave();
+
+        assertThat(rowContaining(name)).containsText("new@example.com");
+    }
+
+    @Test
+    void deletesAPatron() {
+        String name = unique("Patron To Delete");
+
+        navigateTo("patron.xhtml");
+        page.getByLabel("Name:").fill(name);
+        page.getByLabel("Address:").fill("Somewhere");
+        page.getByLabel("Email:").fill("delete@example.com");
+        clickSave();
+
+        assertThat(rowContaining(name)).isVisible();
+
+        rowContaining(name).getByRole(AriaRole.LINK, new Locator.GetByRoleOptions().setName("Delete")).click();
+
+        assertThat(rowContaining(name)).hasCount(0);
+    }
+}