Testing Jakarta Faces Applications: Unit, Integration and Browser Tests

package org.example.bookshelf.web;

import jakarta.faces.application.FacesMessage;
import jakarta.faces.context.FacesContext;

/** Static helper of the kind older code bases have: it reaches the context through the thread. */
public final class Messages {

    private Messages() {
    }

    public static void info(String summary) {
        FacesContext.getCurrentInstance()
                .addMessage(null, new FacesMessage(FacesMessage.SEVERITY_INFO, summary, null));
    }
}

package org.example.bookshelf.web;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.mockito.ArgumentMatchers.isNull;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.mockStatic;
import static org.mockito.Mockito.verify;

import jakarta.faces.application.FacesMessage;
import jakarta.faces.context.FacesContext;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.mockito.MockedStatic;

class MessagesTest {

    @Test
    void infoAddsAGlobalMessage() {
        FacesContext context = mock(FacesContext.class);
        // FacesContext.getCurrentInstance() is a static method that reads a thread-local:
        // mockStatic replaces it for the duration of the try block, on this thread only.
        try (MockedStatic<FacesContext> faces = mockStatic(FacesContext.class)) {
            faces.when(FacesContext::getCurrentInstance).thenReturn(context);

            Messages.info("Saved");

            ArgumentCaptor<FacesMessage> message = ArgumentCaptor.forClass(FacesMessage.class);
            verify(context).addMessage(isNull(), message.capture());
            assertEquals("Saved", message.getValue().getSummary());
            assertEquals(FacesMessage.SEVERITY_INFO, message.getValue().getSeverity());
        }
    }
}

package org.example.bookshelf.service;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;

import jakarta.enterprise.event.Event;
import java.util.List;
import java.util.Optional;
import org.example.bookshelf.model.Book;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;

@ExtendWith(MockitoExtension.class)
class BookServiceTest {

    @Mock
    BookRepository repository;

    @Mock
    Event<BookBorrowed> borrowed;

    @Test
    void searchMatchesTitleOrAuthorIgnoringCase() {
        when(repository.findAll()).thenReturn(List.of(
                new Book(1, "Emma", "Jane Austen", 1815),
                new Book(2, "Dracula", "Bram Stoker", 1897)));
        BookService service = new BookService(repository, borrowed);

        assertEquals(List.of("Emma"), service.search("AUSTEN").stream().map(Book::title).toList());
        assertEquals(2, service.search("  ").size());
    }

    @Test
    void borrowingFiresAnEvent() {
        when(repository.findById(2)).thenReturn(Optional.of(new Book(2, "Emma", "Jane Austen", 1815)));
        BookService service = new BookService(repository, borrowed);

        service.borrow(2, "ana");

        verify(borrowed).fire(new BookBorrowed(2, "ana"));
    }

    @Test
    void borrowingNeedsAReader() {
        BookService service = new BookService(repository, borrowed);

        assertThrows(IllegalArgumentException.class, () -> service.borrow(2, " "));

        verifyNoInteractions(repository);
        verify(borrowed, never()).fire(org.mockito.ArgumentMatchers.any());
    }
}

package org.example.bookshelf.web;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import jakarta.validation.ConstraintViolation;
import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.ValidatorFactory;
import java.util.Set;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

class ReviewBeanConstraintsTest {

    private static ValidatorFactory factory;
    private static Validator validator;

    @BeforeAll
    static void createValidator() {
        factory = Validation.buildDefaultValidatorFactory();
        validator = factory.getValidator();
    }

    @AfterAll
    static void closeFactory() {
        factory.close();
    }

    @Test
    void aShortCommentIsValid() {
        ReviewBean bean = new ReviewBean();
        bean.setComment("Lovely.");

        assertTrue(validator.validate(bean).isEmpty());
    }

    @Test
    void aLongCommentViolatesTheSizeConstraint() {
        ReviewBean bean = new ReviewBean();
        bean.setComment("x".repeat(201));

        Set<ConstraintViolation<ReviewBean>> violations = validator.validate(bean);

        assertEquals(1, violations.size());
        ConstraintViolation<ReviewBean> violation = violations.iterator().next();
        assertEquals("comment", violation.getPropertyPath().toString());
        assertEquals("size must be between 0 and 200", violation.getMessage());
    }
}

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.seleniumhq.selenium</groupId>
                <artifactId>selenium-bom</artifactId>
                <version>${selenium.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>org.jboss.arquillian.extension</groupId>
                <artifactId>arquillian-drone-bom</artifactId>
                <version>${drone.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>org.jboss.arquillian.graphene</groupId>
                <artifactId>graphene-webdriver</artifactId>
                <version>${graphene.version}</version>
                <type>pom</type>
            </dependency>
            <dependency>
                <groupId>org.jboss.arquillian</groupId>
                <artifactId>arquillian-bom</artifactId>
                <version>${arquillian.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.jboss.arquillian.junit5</groupId>
            <artifactId>arquillian-junit5-container</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.apache.tomee</groupId>
            <artifactId>arquillian-tomee-embedded</artifactId>
            <version>${tomee.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.apache.tomee</groupId>
            <artifactId>tomee-embedded</artifactId>
            <version>${tomee.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

<?xml version="1.0" encoding="UTF-8"?>
<arquillian xmlns="http://jboss.org/schema/arquillian"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
    <container qualifier="tomee" default="true">
        <configuration>
            <property name="httpPort">8753</property>
            <property name="stopPort">8754</property>
            <property name="dir">target/tomee-embedded</property>
            <property name="appWorkingDir">target/arquillian-work</property>
        </configuration>
    </container>
    <extension qualifier="webdriver">
        <property name="browser">chrome</property>
        <property name="chromeArguments">--headless=new --window-size=1280,900 --lang=en-US --remote-debugging-port=8756</property>
        <property name="chromeDriverBinary">../se-cache/chromedriver/mac-arm64/155.0.8059.39/chromedriver</property>
    </extension>
</arquillian>

package org.example.bookshelf.it;

import java.io.File;
import org.jboss.shrinkwrap.api.ShrinkWrap;
import org.jboss.shrinkwrap.api.asset.EmptyAsset;
import org.jboss.shrinkwrap.api.asset.StringAsset;
import org.jboss.shrinkwrap.api.spec.WebArchive;

/** Packs only what the test needs: the classes, the bundle, the config files and the page under test. */
final class BookshelfDeployments {

    private static final File WEBAPP = new File("../shelf/src/main/webapp");

    /**
     * A small page written for the test. It calls the record accessor as a method, {@code book.title()}:
     * the embedded TomEE 10 is a Jakarta EE 10 server, whose Expression Language cannot read record components
     * as properties ({@code book.title}), which EL 6.0 in Jakarta EE 11 can.
     */
    private static final String TITLES = """
            <html xmlns="http://www.w3.org/1999/xhtml"
                  xmlns:h="jakarta.faces.html"
                  xmlns:ui="jakarta.faces.facelets">
            <h:head><title>Titles</title></h:head>
            <h:body>
                <h:form id="titles">
                    <ui:repeat value="#{catalogueBean.books}" var="book">
                        <p class="title">#{book.title()}</p>
                    </ui:repeat>
                </h:form>
            </h:body>
            </html>
            """;

    /** The catalogue search with Ajax, written for EE 10 in the same way as {@link #TITLES}. */
    private static final String SEARCH = """
            <html xmlns="http://www.w3.org/1999/xhtml"
                  xmlns:h="jakarta.faces.html"
                  xmlns:f="jakarta.faces.core"
                  xmlns:ui="jakarta.faces.facelets">
            <h:head><title>Search</title></h:head>
            <h:body>
                <h:form id="catalogue">
                    <h:inputText id="query" value="#{catalogueBean.query}"/>
                    <h:commandButton id="search" value="Search" action="#{catalogueBean.search}">
                        <f:ajax execute="@form" render="results"/>
                    </h:commandButton>
                    <h:panelGroup id="results" layout="block">
                        <h:messages/>
                        <ui:repeat value="#{catalogueBean.books}" var="book">
                            <p class="title">#{book.title()}</p>
                        </ui:repeat>
                    </h:panelGroup>
                </h:form>
            </h:body>
            </html>
            """;

    private BookshelfDeployments() {
    }

    static WebArchive catalogue() {
        return ShrinkWrap.create(WebArchive.class, "bookshelf.war")
                .addPackages(true, "org.example.bookshelf")
                .addAsResource(new File("../shelf/src/main/resources/org/example/bookshelf/messages.properties"),
                        "org/example/bookshelf/messages.properties")
                .addAsWebInfResource(new File(WEBAPP, "WEB-INF/web.xml"))
                .addAsWebInfResource(new File(WEBAPP, "WEB-INF/faces-config.xml"))
                .addAsWebInfResource(new File(WEBAPP, "WEB-INF/templates/layout.xhtml"), "templates/layout.xhtml")
                .addAsWebInfResource(EmptyAsset.INSTANCE, "beans.xml")
                .addAsWebResource(new StringAsset(TITLES), "titles.xhtml")
                .addAsWebResource(new StringAsset(SEARCH), "search.xhtml");
    }
}

package org.example.bookshelf.it;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import jakarta.enterprise.event.Observes;
import jakarta.inject.Inject;
import java.util.ArrayList;
import java.util.List;
import org.example.bookshelf.service.BookBorrowed;
import org.example.bookshelf.service.BookService;
import org.jboss.arquillian.container.test.api.Deployment;
import org.jboss.arquillian.junit5.ArquillianExtension;
import org.jboss.shrinkwrap.api.spec.WebArchive;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

/** In-container mode: the test class is deployed with the application and CDI injects into it. */
@ExtendWith(ArquillianExtension.class)
class BookServiceIT {

    @Deployment
    static WebArchive deployment() {
        return BookshelfDeployments.catalogue().addClass(BookServiceIT.class);
    }

    @Inject
    BookService service;

    static final List<BookBorrowed> seen = new ArrayList<>();

    void onBorrowed(@Observes BookBorrowed event) {
        seen.add(event);
    }

    @Test
    void theContainerInjectsTheRealServiceAndTheRealEventBus() {
        assertEquals(5, service.catalogue().size());

        service.borrow(2, "ana");

        assertEquals(1, seen.size());
        assertTrue(seen.get(0).reader().equals("ana"));
    }
}

package org.example.bookshelf.it;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.net.URI;
import java.net.URL;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import org.jboss.arquillian.container.test.api.Deployment;
import org.jboss.arquillian.container.test.api.RunAsClient;
import org.jboss.arquillian.junit5.ArquillianExtension;
import org.jboss.arquillian.test.api.ArquillianResource;
import org.jboss.shrinkwrap.api.spec.WebArchive;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

/** Client mode: the archive is deployed as it is and the test talks to it over HTTP from the test JVM. */
@ExtendWith(ArquillianExtension.class)
class CataloguePageIT {

    @Deployment(testable = false)
    static WebArchive deployment() {
        return BookshelfDeployments.catalogue();
    }

    @ArquillianResource
    URL base;

    @Test
    @RunAsClient
    void theCatalogueIsRenderedByTheRealFacesServlet() throws Exception {
        HttpResponse<String> response = HttpClient.newHttpClient().send(
                HttpRequest.newBuilder(URI.create(base + "titles.xhtml")).build(),
                HttpResponse.BodyHandlers.ofString());

        assertEquals(200, response.statusCode());
        assertTrue(response.body().contains("Pride and Prejudice"));
        assertTrue(response.body().contains("jakarta.faces.ViewState"));
    }
}

    <extension qualifier="webdriver">
        <property name="browser">chrome</property>
        <property name="chromeArguments">--headless=new --window-size=1280,900 --lang=en-US --remote-debugging-port=8756</property>
        <property name="chromeDriverBinary">../se-cache/chromedriver/mac-arm64/155.0.8059.39/chromedriver</property>
    </extension>

package org.example.bookshelf.it;

import static org.jboss.arquillian.graphene.Graphene.waitGui;
import static org.junit.jupiter.api.Assertions.assertEquals;

import java.net.URL;
import java.util.List;
import org.jboss.arquillian.container.test.api.Deployment;
import org.jboss.arquillian.container.test.api.RunAsClient;
import org.jboss.arquillian.drone.api.annotation.Drone;
import org.jboss.arquillian.graphene.Graphene;
import org.jboss.arquillian.junit5.ArquillianExtension;
import org.jboss.arquillian.test.api.ArquillianResource;
import org.jboss.shrinkwrap.api.spec.WebArchive;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.support.FindBy;

/** Drone starts and stops the browser and injects it; Graphene adds the waits for Ajax and page objects. */
@ExtendWith(ArquillianExtension.class)
@RunAsClient
class CatalogueGrapheneIT {

    @Deployment(testable = false)
    static WebArchive deployment() {
        return BookshelfDeployments.catalogue();
    }

    @Drone
    WebDriver browser;

    @ArquillianResource
    URL base;

    @FindBy(id = "catalogue:query")
    WebElement query;

    @FindBy(id = "catalogue:search")
    WebElement search;

    @Test
    void searchFiltersTheCatalogueWithAjax() {
        browser.get(base + "search.xhtml");
        query.sendKeys("austen");

        // Graphene.guardAjax runs the click, then fails unless an Ajax request was started and has finished
        Graphene.guardAjax(search).click();

        List<WebElement> titles = browser.findElements(By.cssSelector("p.title"));
        assertEquals(2, titles.size());
        waitGui().until(d -> d.findElement(By.cssSelector("p.title")).getText().equals("Pride and Prejudice"));
    }
}

package org.example.bookshelf.e2e;

import java.io.File;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Map;
import org.apache.catalina.Context;
import org.apache.catalina.LifecycleException;
import org.apache.catalina.startup.Tomcat;

/** Starts the unpacked WAR on an embedded Tomcat once per JVM and hands out its base URL. */
public final class BookshelfServer {

    private static Tomcat tomcat;
    private static String baseUrl;

    /** A second, separately configured application: its own port, context parameters and lifetime. */
    public record Running(Tomcat tomcat, String url) implements AutoCloseable {
        @Override
        public void close() {
            try {
                tomcat.stop();
                tomcat.destroy();
            } catch (LifecycleException ignored) {
                // shutting down
            }
        }
    }

    public static Running start(int port, Map<String, String> contextParameters) {
        try {
            Path base = Files.createTempDirectory("bookshelf-tomcat");
            Tomcat server = new Tomcat();
            server.setBaseDir(base.toString());
            server.setPort(port);
            server.getServer().setPort(-1);
            server.getConnector();
            Context context = server.addWebapp("/bookshelf", new File("target/webapp").getAbsolutePath());
            contextParameters.forEach(context::addParameter);
            server.start();
            return new Running(server, "http://localhost:" + port + "/bookshelf");
        } catch (Exception e) {
            throw new IllegalStateException("Cannot start the application", e);
        }
    }

    private BookshelfServer() {
    }

    public static synchronized String url() {
        if (baseUrl == null) {
            // -Dbookshelf.url=... tests an application that is already running somewhere else
            baseUrl = System.getProperty("bookshelf.url");
            if (baseUrl == null) {
                baseUrl = startEmbedded();
            }
        }
        return baseUrl;
    }

    private static String startEmbedded() {
        int port = Integer.getInteger("bookshelf.port", 8750);
        try {
            Path base = Files.createTempDirectory("bookshelf-tomcat");
            tomcat = new Tomcat();
            tomcat.setBaseDir(base.toString());
            tomcat.setPort(port);
            tomcat.getServer().setPort(-1);          // no shutdown port
            tomcat.getConnector();
            Context context = tomcat.addWebapp("/bookshelf", new File("target/webapp").getAbsolutePath());
            context.addParameter("jakarta.faces.PROJECT_STAGE", System.getProperty("bookshelf.stage", "Production"));
            tomcat.start();
            Runtime.getRuntime().addShutdownHook(new Thread(BookshelfServer::stop));
            return "http://localhost:" + port + "/bookshelf";
        } catch (Exception e) {
            throw new IllegalStateException("Cannot start the application", e);
        }
    }

    private static synchronized void stop() {
        try {
            if (tomcat != null) {
                tomcat.stop();
                tomcat.destroy();
            }
        } catch (LifecycleException ignored) {
            // shutting down
        }
    }
}

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
                xmlns:h="jakarta.faces.html"
                xmlns:f="jakarta.faces.core"
                xmlns:ui="jakarta.faces.facelets"
                xmlns:pt="jakarta.faces.passthrough"
                template="/WEB-INF/templates/layout.xhtml">
    <ui:define name="content">
        <h1>Catalogue</h1>
        <h:form id="catalogue">
            <h:outputLabel for="query" value="Search"/>
            <h:inputText id="query" value="#{catalogueBean.query}" pt:data-testid="query"/>
            <h:commandButton id="search" value="#{msg['catalogue.search']}" action="#{catalogueBean.search}"
                             pt:data-testid="search">
                <f:ajax execute="@form" render="books messages"/>
            </h:commandButton>
            <h:messages id="messages" globalOnly="false" errorClass="error" infoClass="info"
                        warnClass="warn"/>
            <h:dataTable id="books" value="#{catalogueBean.books}" var="book">
                <h:column><f:facet name="header">Title</f:facet><h:outputText value="#{book.title}" styleClass="title"/></h:column>
                <h:column><f:facet name="header">Author</f:facet>#{book.author}</h:column>
                <h:column><f:facet name="header">Year</f:facet>#{book.year}</h:column>
                <h:column>
                    <h:commandButton id="borrow" value="Borrow" action="#{catalogueBean.borrow(book.id)}"
                                     pt:data-testid="borrow-#{book.id}">
                        <f:ajax execute="@this" render=":catalogue:messages"/>
                    </h:commandButton>
                </h:column>
            </h:dataTable>
        </h:form>
    </ui:define>
</ui:composition>

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
                xmlns:h="jakarta.faces.html"
                xmlns:f="jakarta.faces.core"
                xmlns:ui="jakarta.faces.facelets"
                xmlns:pt="jakarta.faces.passthrough"
                template="/WEB-INF/templates/layout.xhtml">
    <ui:define name="content">
        <h1>Review a book</h1>
        <h:form id="review">
            <h:messages id="messages" errorClass="error" infoClass="info"/>
            <h:outputLabel for="isbn" value="ISBN"/>
            <h:inputText id="isbn" value="#{reviewBean.isbn}" required="true" validator="bookshelf.isbnLength"
                         pt:data-testid="isbn"/>
            <h:outputLabel for="rating" value="Rating"/>
            <h:inputText id="rating" value="#{reviewBean.rating}" required="true" pt:data-testid="rating">
                <f:validateLongRange minimum="1" maximum="5"/>
            </h:inputText>
            <h:outputLabel for="comment" value="Comment"/>
            <h:inputTextarea id="comment" value="#{reviewBean.comment}" pt:data-testid="comment"/>
            <h:commandButton id="submit" value="Save" action="#{reviewBean.submit}" pt:data-testid="save-review">
                <f:ajax execute="@form" render="@form"/>
            </h:commandButton>
            <h:outputText id="saved" value="#{reviewBean.saved}" pt:data-testid="saved"/>
        </h:form>
    </ui:define>
</ui:composition>

package org.example.bookshelf.e2e;

import java.time.Duration;
import org.openqa.selenium.JavascriptExecutor;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.support.ui.WebDriverWait;

/** Knows when a Jakarta Faces Ajax request has finished: counts the events faces.ajax reports. */
public final class FacesAjax {

    private static final String INSTALL = """
            if (!window.__ajax) {
              window.__ajax = { pending: 0, finished: 0, errors: [] };
              faces.ajax.addOnEvent(function (event) {
                if (event.status === 'begin') { window.__ajax.pending++; }
                if (event.status === 'success') { window.__ajax.pending--; window.__ajax.finished++; }
              });
              faces.ajax.addOnError(function (error) {
                window.__ajax.pending--;
                window.__ajax.errors.push(error.status + ': ' + error.description);
              });
            }
            """;

    private FacesAjax() {
    }

    /** Call once after each full page load (a full page load discards the script's state). */
    public static void install(WebDriver driver) {
        ((JavascriptExecutor) driver).executeScript(INSTALL);
    }

    /** Waits until no Faces Ajax request is in flight. Call it right after the action that starts one. */
    public static void waitIdle(WebDriver driver) {
        new WebDriverWait(driver, Duration.ofSeconds(10)).until(d -> {
            Object pending = ((JavascriptExecutor) d).executeScript("return window.__ajax ? window.__ajax.pending : -1");
            return Long.valueOf(0).equals(pending);
        });
    }

    public static long finished(WebDriver driver) {
        return (Long) ((JavascriptExecutor) driver).executeScript("return window.__ajax.finished");
    }
}

package org.example.bookshelf.e2e;

import java.util.Map;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeDriverService;
import org.openqa.selenium.chrome.ChromeOptions;

/** A headless Chrome whose ports and language are fixed, so that parallel builds do not collide. */
public final class PinnedChrome {

    private PinnedChrome() {
    }

    public static WebDriver create() {
        ChromeOptions options = new ChromeOptions();
        options.addArguments("--headless=new", "--window-size=1280,900", "--lang=en-US",
                "--remote-debugging-port=" + Integer.getInteger("chrome.debug.port", 8752));
        options.setExperimentalOption("prefs", Map.of("intl.accept_languages", "en-US"));
        ChromeDriverService service = new ChromeDriverService.Builder()
                .usingPort(Integer.getInteger("webdriver.port", 8751))
                .build();
        return new ChromeDriver(service, options);
    }
}

package org.example.bookshelf.e2e;

import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.openqa.selenium.WebDriver;

/** One headless Chrome per test class. */
abstract class BrowserTest {

    protected static WebDriver driver;
    protected static String base;

    @BeforeAll
    static void startBrowser() {
        base = BookshelfServer.url();
        driver = PinnedChrome.create();
    }

    @AfterAll
    static void stopBrowser() {
        if (driver != null) {
            driver.quit();
        }
    }

    protected static void open(String path) {
        driver.get(base + path);
        FacesAjax.install(driver);
    }
}

package org.example.bookshelf.e2e;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.List;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;

class CatalogueSeleniumIT extends BrowserTest {

    // Ids of components inside a form are prefixed with the form id: catalogue:query.
    // By.id takes the id as it is; in a CSS selector the colon must be escaped, so use an attribute selector.
    private static final By QUERY = By.id("catalogue:query");
    private static final By SEARCH = By.cssSelector("[data-testid='search']");
    // Only the cells that carry the class title: an empty h:dataTable still renders one filler row.
    private static final By ROWS = By.cssSelector("[id='catalogue:books'] .title");
    private static final By MESSAGES = By.id("catalogue:messages");

    @BeforeEach
    void openTheCatalogue() {
        open("/index.xhtml");
    }

    @Test
    void theCatalogueListsAllTheBooks() {
        assertEquals(5, driver.findElements(ROWS).size());
    }

    @Test
    void searchNarrowsTheTableWithoutReloadingThePage() {
        driver.findElement(QUERY).sendKeys("austen");
        driver.findElement(SEARCH).click();
        FacesAjax.waitIdle(driver);

        assertEquals(2, driver.findElements(ROWS).size());
        assertEquals(1, FacesAjax.finished(driver));       // the same page: the counter survived
    }

    @Test
    void anEmptySearchShowsAWarning() {
        driver.findElement(QUERY).sendKeys("zzz");
        driver.findElement(SEARCH).click();
        FacesAjax.waitIdle(driver);

        assertEquals(0, driver.findElements(ROWS).size());
        assertTrue(driver.findElement(MESSAGES).getText().contains("Nothing found"));
    }

    @Test
    void borrowingABookShowsAConfirmation() {
        driver.findElement(By.cssSelector("[data-testid='borrow-2']")).click();
        FacesAjax.waitIdle(driver);

        assertEquals("Borrowed book 2", driver.findElement(MESSAGES).getText().strip());
    }

    @Test
    void rowsKeepTheirContentAfterAnAjaxUpdate() {
        List<String> before = driver.findElements(ROWS).stream().map(row -> row.getText()).toList();
        driver.findElement(By.cssSelector("[data-testid='borrow-1']")).click();
        FacesAjax.waitIdle(driver);

        assertEquals(before, driver.findElements(ROWS).stream().map(row -> row.getText()).toList());
    }

    @Test
    void theBrowserKnowsWhichProjectStageItIsTesting() {
        // faces.getProjectStage() returns Application.getProjectStage() without a request to the server
        Object stage = ((org.openqa.selenium.JavascriptExecutor) driver).executeScript("return faces.getProjectStage();");

        assertEquals("Production", stage);
    }
}

package org.example.bookshelf.e2e;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;

class ReviewSeleniumIT extends BrowserTest {

    private static final By ISBN = By.id("review:isbn");
    private static final By RATING = By.id("review:rating");
    private static final By SAVE = By.cssSelector("[data-testid='save-review']");
    private static final By MESSAGES = By.id("review:messages");
    private static final By SAVED = By.cssSelector("[data-testid='saved']");

    @BeforeEach
    void openTheForm() {
        open("/review.xhtml");
    }

    private void fill(String isbn, String rating) {
        driver.findElement(ISBN).sendKeys(isbn);
        driver.findElement(RATING).sendKeys(rating);
    }

    @Test
    void aShortIsbnIsRejectedWithTheLocalisedMessage() {
        fill("12345", "4");
        driver.findElement(SAVE).click();
        FacesAjax.waitIdle(driver);

        assertTrue(driver.findElement(MESSAGES).getText().contains("ISBN must have 13 digits, but \"12345\" has 5."));
        assertEquals("", driver.findElement(SAVED).getText());
    }

    @Test
    void anOutOfRangeRatingIsRejected() {
        fill("9780306406157", "9");
        driver.findElement(SAVE).click();
        FacesAjax.waitIdle(driver);

        assertTrue(driver.findElement(MESSAGES).getText().contains("not between the expected values of 1 and 5"));
    }

    @Test
    void aValidReviewIsSavedAndTheFormIsKept() {
        fill("9780306406157", "5");
        driver.findElement(SAVE).click();
        FacesAjax.waitIdle(driver);

        assertEquals("Saved review 5/5 for 9780306406157", driver.findElement(SAVED).getText());
        assertEquals("9780306406157", driver.findElement(ISBN).getAttribute("value"));
    }

    @Test
    void theViewStateFieldSurvivesTheAjaxUpdate() {
        String before = viewState();
        fill("9780306406157", "5");
        driver.findElement(SAVE).click();
        FacesAjax.waitIdle(driver);

        // With server-side state saving the id of the saved view stays the same for the life of the view
        assertEquals(before, viewState());
    }

    private String viewState() {
        return driver.findElement(By.cssSelector("input[name='jakarta.faces.ViewState']")).getAttribute("value");
    }
}

package org.example.bookshelf.e2e;

import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import com.microsoft.playwright.Browser;
import com.microsoft.playwright.BrowserContext;
import com.microsoft.playwright.BrowserType;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Playwright;
import com.microsoft.playwright.Request;
import com.microsoft.playwright.Response;
import java.nio.file.Path;
import java.util.regex.Pattern;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

class ReviewPlaywrightIT {

    private static Playwright playwright;
    private static Browser browser;

    private BrowserContext context;
    private Page page;

    @BeforeAll
    static void launch() {
        playwright = Playwright.create();
        // channel "chrome" drives the Chrome that is installed; without it Playwright uses its own download
        browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setChannel("chrome").setHeadless(true));
    }

    @AfterAll
    static void close() {
        browser.close();
        playwright.close();
    }

    @BeforeEach
    void openTheForm() {
        context = browser.newContext(new Browser.NewContextOptions().setLocale("en-US"));
        context.tracing().start(new com.microsoft.playwright.Tracing.StartOptions().setScreenshots(true).setSnapshots(true));
        page = context.newPage();
        page.navigate(BookshelfServer.url() + "/review.xhtml");
    }

    @AfterEach
    void closeTheContext(org.junit.jupiter.api.TestInfo info) {
        context.tracing().stop(new com.microsoft.playwright.Tracing.StopOptions()
                .setPath(Path.of("target", "traces", info.getTestMethod().orElseThrow().getName() + ".zip")));
        context.close();
    }

    @Test
    void aShortIsbnIsRejected() {
        page.getByLabel("ISBN").fill("12345");
        page.getByLabel("Rating").fill("4");
        page.getByTestId("save-review").click();

        // The assertion retries until it passes or times out: no explicit wait for the Ajax request
        assertThat(page.locator("[id='review:messages']"))
                .containsText("ISBN must have 13 digits, but \"12345\" has 5.");
        assertThat(page.getByTestId("saved")).hasText("");
    }

    @Test
    void aValidReviewIsSaved() {
        page.getByTestId("isbn").fill("9780306406157");
        page.getByTestId("rating").fill("5");
        page.getByTestId("save-review").click();

        assertThat(page.getByTestId("saved")).hasText("Saved review 5/5 for 9780306406157");
        assertThat(page.getByTestId("isbn")).hasValue("9780306406157");
    }

    @Test
    void thePartialResponseIsXmlThatUpdatesTheForm() {
        page.getByTestId("isbn").fill("9780306406157");
        page.getByTestId("rating").fill("5");

        Response response = page.waitForResponse(
                r -> r.request().method().equals("POST")
                        && r.request().postData().contains("jakarta.faces.partial.ajax=true"),
                () -> page.getByTestId("save-review").click());

        Request request = response.request();
        assertTrue(request.headers().get("faces-request").equals("partial/ajax"));
        assertTrue(response.headers().get("content-type").startsWith("text/xml"));
        assertTrue(response.text().contains("<partial-response"));
        assertTrue(response.text().contains("<update id=\"review\">"));
        assertTrue(Pattern.compile("Saved review 5/5").matcher(response.text()).find());
    }
}

deployment.adapter=org.example.bookshelf.e2e.BookshelfDeployment
webdriver.adapter=org.example.bookshelf.e2e.PinnedChromeAdapter
webdriver.browser=chrome
webdriver.headless=true
timeout.ajax=10

package org.example.bookshelf.e2e;

import org.primefaces.selenium.spi.DeploymentAdapter;

/** Tells PrimeFaces Selenium how to start the application and where it is. */
public class BookshelfDeployment implements DeploymentAdapter {

    @Override
    public void startup() {
        BookshelfServer.url();
    }

    @Override
    public String getBaseUrl() {
        return BookshelfServer.url() + "/";           // PrimeFaces Selenium appends the page location
    }

    @Override
    public void shutdown() {
        // the server stops with the JVM
    }
}

package org.example.bookshelf.e2e;

import org.openqa.selenium.WebDriver;
import org.primefaces.selenium.internal.ConfigProvider;
import org.primefaces.selenium.spi.WebDriverAdapter;

/** Replaces the default adapter, which downloads a driver with WebDriverManager and picks free ports. */
public class PinnedChromeAdapter implements WebDriverAdapter {

    @Override
    public void initialize(ConfigProvider configProvider) {
        // nothing to download: Selenium Manager resolves the driver
    }

    @Override
    public WebDriver createWebDriver() {
        return PinnedChrome.create();
    }
}

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
                xmlns:h="jakarta.faces.html"
                xmlns:f="jakarta.faces.core"
                xmlns:ui="jakarta.faces.facelets"
                xmlns:pt="jakarta.faces.passthrough"
                xmlns:p="primefaces"
                template="/WEB-INF/templates/layout.xhtml">
    <ui:define name="content">
        <h1>Shelf (PrimeFaces)</h1>
        <h:form id="shelf">
            <p:growl id="growl" life="30000"/>

            <p:dataTable id="books" widgetVar="booksTable" value="#{catalogueBean.books}" var="book"
                         paginator="true" rows="2" paginatorPosition="bottom">
                <p:column headerText="Title"><h:outputText value="#{book.title}"/></p:column>
                <p:column headerText="Author"><h:outputText value="#{book.author}"/></p:column>
                <p:column headerText="Borrow">
                    <p:commandButton id="borrow" value="Borrow" action="#{catalogueBean.borrow(book.id)}"
                                     process="@this" update=":shelf:growl" pt:data-testid="borrow-#{book.id}"/>
                </p:column>
            </p:dataTable>

            <p:commandButton id="open" type="button" value="Review" onclick="PF('reviewDialog').show()"
                             pt:data-testid="open-review"/>
            <p:dialog id="dialog" widgetVar="reviewDialog" header="Review a book" modal="true" showEffect="none"
                      hideEffect="none">
                <h:panelGrid columns="2">
                    <p:outputLabel for="isbn" value="ISBN"/>
                    <p:inputText id="isbn" value="#{reviewBean.isbn}" required="true" validator="bookshelf.isbnLength"
                                 pt:data-testid="isbn"/>
                    <p:outputLabel for="genre" value="Genre"/>
                    <p:selectOneMenu id="genre" widgetVar="genreMenu" value="#{catalogueBean.query}">
                        <f:selectItem itemLabel="Any" itemValue=""/>
                        <f:selectItem itemLabel="Gothic" itemValue="gothic"/>
                        <f:selectItem itemLabel="Romance" itemValue="romance"/>
                    </p:selectOneMenu>
                </h:panelGrid>
                <p:commandButton id="save" value="Save" action="#{reviewBean.submit}" update="growl isbn"
                                 oncomplete="if (!args.validationFailed) PF('reviewDialog').hide()"
                                 pt:data-testid="save-review"/>
            </p:dialog>
        </h:form>
    </ui:define>
</ui:composition>

package org.example.bookshelf.e2e;

import org.openqa.selenium.WebElement;
import org.openqa.selenium.support.FindBy;
import org.primefaces.selenium.AbstractPrimePage;
import org.primefaces.selenium.component.CommandButton;
import org.primefaces.selenium.component.DataTable;
import org.primefaces.selenium.component.Dialog;
import org.primefaces.selenium.component.InputText;
import org.primefaces.selenium.component.SelectOneMenu;

/** The page object of shelf.xhtml: one typed field per component, found by the client id. */
public class ShelfPage extends AbstractPrimePage {

    @FindBy(id = "shelf:books")
    DataTable books;

    @FindBy(id = "shelf:open")
    CommandButton openReview;

    @FindBy(id = "shelf:dialog")
    Dialog dialog;

    @FindBy(id = "shelf:isbn")
    InputText isbn;

    @FindBy(id = "shelf:genre")
    SelectOneMenu genre;

    @FindBy(id = "shelf:save")
    CommandButton save;

    // p:growl renders its messages into a container next to the form, not inside the component's own element
    @FindBy(css = "[id='shelf:growl_container'] .ui-growl-message")
    WebElement growlMessage;

    @Override
    public String getLocation() {
        return "shelf.xhtml";
    }
}

package org.example.bookshelf.e2e;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;

import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;
import org.primefaces.selenium.AbstractPrimePageTest;
import org.primefaces.selenium.PrimeSelenium;

class ShelfPrimeIT extends AbstractPrimePageTest {

    @Test
    void theTablePagesTwoRowsAtATime(ShelfPage page) {
        assertEquals(2, page.books.getRows().size());
        assertEquals("Pride and Prejudice", page.books.getCell(0, 0).getWebElement().getText());

        page.books.selectPage(2);                       // an Ajax request: the library waits for it

        assertEquals("Frankenstein", page.books.getCell(0, 0).getWebElement().getText());
    }

    @Test
    void borrowingShowsAGrowlMessage(ShelfPage page) {
        PrimeSelenium.guardAjax(page.books.getRow(1).getWebElement().findElement(By.tagName("button"))).click();

        assertEquals("Borrowed book 2", page.growlMessage.getText().strip());
    }

    @Test
    void theDialogStaysOpenWhileTheIsbnIsInvalid(ShelfPage page) {
        page.openReview.clickUnguarded();                // type="button": opens the dialog on the client only
        PrimeSelenium.waitGui().until(d -> page.dialog.isVisible());

        page.isbn.setValue("12345");
        page.save.click();

        assertTrue(page.dialog.isVisible());
        assertTrue(page.growlMessage.getText().contains("ISBN must have 13 digits, but \"12345\" has 5."));

        page.isbn.setValue("9780306406157");
        page.save.click();

        PrimeSelenium.waitGui().until(d -> !page.dialog.isVisible());
        assertFalse(page.dialog.isVisible());
    }

    @Test
    void theMenuSelectionIsReadBack(ShelfPage page) {
        page.openReview.clickUnguarded();
        PrimeSelenium.waitGui().until(d -> page.dialog.isVisible());

        page.genre.select("Gothic");

        assertEquals("Gothic", page.genre.getSelectedLabel());
    }
}

package org.example.bookshelf.e2e;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import org.htmlunit.BrowserVersion;
import org.htmlunit.WebClient;
import org.htmlunit.html.HtmlPage;
import org.htmlunit.html.HtmlSubmitInput;
import org.htmlunit.html.HtmlTextInput;
import org.junit.jupiter.api.Test;

/** HtmlUnit is a browser written in Java: no browser binary, but a JavaScript engine that is not Chrome's. */
class ReviewHtmlUnitIT {

    @Test
    void aValidReviewIsSavedThroughAjax() throws Exception {
        try (WebClient client = new WebClient(BrowserVersion.CHROME)) {
            HtmlPage page = client.getPage(BookshelfServer.url() + "/review.xhtml");
            page.<HtmlTextInput>getHtmlElementById("review:isbn").type("9780306406157");
            page.<HtmlTextInput>getHtmlElementById("review:rating").type("5");

            page.<HtmlSubmitInput>getHtmlElementById("review:submit").click();
            client.waitForBackgroundJavaScript(5_000);             // lets the Ajax request finish

            assertEquals("Saved review 5/5 for 9780306406157",
                    page.getHtmlElementById("review:saved").getTextContent());
        }
    }

    @Test
    void aShortIsbnShowsTheMessage() throws Exception {
        try (WebClient client = new WebClient(BrowserVersion.CHROME)) {
            HtmlPage page = client.getPage(BookshelfServer.url() + "/review.xhtml");
            page.<HtmlTextInput>getHtmlElementById("review:isbn").type("12345");
            page.<HtmlTextInput>getHtmlElementById("review:rating").type("4");

            page.<HtmlSubmitInput>getHtmlElementById("review:submit").click();
            client.waitForBackgroundJavaScript(5_000);

            assertTrue(page.getHtmlElementById("review:messages").getTextContent()
                    .contains("ISBN must have 13 digits"));
        }
    }
}

package org.example.bookshelf.e2e;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.time.Duration;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;

/**
 * Hostile input must come back as text. The validator message repeats what the user typed, which is exactly
 * where a component that does not escape its messages would turn the input into markup.
 */
class HostileInputIT extends BrowserTest {

    private static final String HOSTILE = "<img src=x onerror=\"document.title='pwned'\">";
    private static final By INJECTED = By.cssSelector("img[src='x']");

    @BeforeEach
    void cleanPage() {
        driver.manage().deleteAllCookies();
    }

    @Test
    void standardMessagesEscapeTheInput() {
        open("/review.xhtml");
        driver.findElement(By.id("review:isbn")).sendKeys(HOSTILE);
        driver.findElement(By.id("review:rating")).sendKeys("4");
        driver.findElement(By.cssSelector("[data-testid='save-review']")).click();
        FacesAjax.waitIdle(driver);

        assertTrue(driver.findElement(By.id("review:messages")).getText().contains("<img src=x onerror="));
        assertEquals(0, driver.findElements(INJECTED).size());       // no element was created from the text
        assertEquals("Bookshelf", driver.getTitle());                // and no handler ran
    }

    @Test
    void growlEscapesTheInput() {
        driver.get(base + "/shelf.xhtml");
        driver.findElement(By.id("shelf:open")).click();
        new WebDriverWait(driver, Duration.ofSeconds(5)).until(ExpectedConditions.elementToBeClickable(By.id("shelf:isbn")));
        driver.findElement(By.id("shelf:isbn")).sendKeys(HOSTILE);
        driver.findElement(By.id("shelf:save")).click();
        new WebDriverWait(driver, Duration.ofSeconds(5)).until(d -> !d.findElements(By.cssSelector(".ui-growl-message")).isEmpty()
                && !d.findElement(By.cssSelector(".ui-growl-message")).getText().isBlank());

        assertTrue(driver.findElement(By.cssSelector(".ui-growl-message")).getText().contains("<img src=x onerror="));
        assertEquals(0, driver.findElements(INJECTED).size());
        assertEquals("Bookshelf", driver.getTitle());
    }
}

package org.example.bookshelf.e2e;

import static org.example.bookshelf.e2e.FacesHttp.get;
import static org.example.bookshelf.e2e.FacesHttp.save;
import static org.example.bookshelf.e2e.FacesHttp.text;
import static org.example.bookshelf.e2e.FacesHttp.viewStateOf;
import static org.example.bookshelf.e2e.FacesHttp.xml;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.net.CookieManager;
import java.net.http.HttpClient;
import java.net.http.HttpResponse;
import java.util.Map;
import org.junit.jupiter.api.Test;

/** The same form with client-side state saving: the view state travels with the page, not in the session. */
class ClientStateIT {

    @Test
    void aViewSurvivesTheLossOfTheSessionWhenTheStateIsOnTheClient() throws Exception {
        try (var server = BookshelfServer.start(Integer.getInteger("stage.port", 8757),
                Map.of("jakarta.faces.STATE_SAVING_METHOD", "client"))) {
            String page = server.url() + "/review.xhtml";
            HttpClient first = HttpClient.newBuilder().cookieHandler(new CookieManager()).build();
            String viewState = viewStateOf(get(first, page));
            assertTrue(viewState.length() > 100, "client state is the serialised view, not a short id");

            HttpClient second = HttpClient.newBuilder().cookieHandler(new CookieManager()).build();   // no session
            HttpResponse<String> response = save(second, page, viewState, "9780306406157", "5");

            assertEquals(200, response.statusCode());
            assertEquals("", text(xml(response.body()), "/partial-response/error/error-name"));
            assertTrue(text(xml(response.body()), "/partial-response/changes/update[@id='review']")
                    .contains("Saved review 5/5"));
        }
    }
}