Skip to content
Skills Library
Programming · Testing

spring-testing-browser

/spring-testing-browser

Browser-level tests of Spring Boot web UIs - HtmlUnit on the mock MVC stack, or Selenium driving a real browser against a RANDOM_PORT server. Use when testing rendered HTML structure, forms, clicks, keyboard input, JavaScript behaviour or login pages, rather than raw HTTP responses.

Licence
Apache-2.0
Last repository change
29.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Browser-level tests of Spring Boot web UIs - HtmlUnit on the mock MVC stack, or Selenium driving a real browser against a RANDOM_PORT server. Use when testing rendered HTML structure, forms, clicks, keyboard input, JavaScript behaviour or login pages, rather than raw HTTP responses.

Original author description

Browser-level tests of Spring Boot web UIs - HtmlUnit on the mock MVC stack, or Selenium driving a real browser against a RANDOM_PORT server. Use when testing rendered HTML structure, forms, clicks, keyboard input, JavaScript behaviour or login pages, rather than raw HTTP responses.

How it works

  1. Steps
  2. HtmlUnit
Original SKILL.md headings · 71 lines, 534 words
SKILL.md preview
---
name: spring-testing-browser
description: Browser-level tests of Spring Boot web UIs - HtmlUnit on the mock MVC stack, or Selenium driving a real browser against a RANDOM_PORT server. Use when testing rendered HTML structure, forms, clicks, keyboard input, JavaScript behaviour or login pages, rather than raw HTTP responses.
---

# Browser-level testing

`MockMvcTester` handles HTTP and JSON well, but HTML only as one big string. To check page structure or simulate a user, drive a browser:

| Choose | When | Cost |
|---|---|---|
| **HtmlUnit** | Server-rendered pages, forms, light JavaScript (ES6-era) | JVM-only, runs on mock MVC, no server |
| **Selenium** | Modern JavaScript (`async`/`await`, classes, recent browser APIs such as `PublicKeyCredential` for passkeys), JS-heavy pages | Real browser + driver, full server, slower |

Start with HtmlUnit; move to Selenium when HtmlUnit can't run the page's JavaScript. For a rich SPA built with a JS framework (React, Angular, Vue), the frontend team's tools (Playwright, Cypress) usually fit better than either.

For Selenium, read [selenium.md](selenium.md).

## Steps

1. **Pick the driver** from the table, per page: HtmlUnit unless its JavaScript engine can't run the page.
2. **Arrange server-side state** as for HTTP tests: stub external services, reset data, insert what the page should show.
3. **For each user interaction**, load the page, act (type, click, press a key), wait for the JavaScript to settle, then assert the resulting DOM through stable selectors (ids, `data-role`, semantic classes).
4. **Cover navigation outcomes**: where a form submit, a login or a logout lands, and what an unauthorized user sees.

Done when every interaction under test asserts the DOM state it produces, after waiting for the JavaScript it triggers (`waitForBackgroundJavaScript` in HtmlUnit, an explicit wait on that state in Selenium), and every navigating action asserts the landing URL.

## HtmlUnit

Dependency: `org.htmlunit:htmlunit` (test scope). With `@AutoConfigureMockMvc` (or `@WebMvcTest`), Spring Boot auto-configures an HtmlUnit `WebClient` bound to mock MVC. Request paths need no host or port.

**Import `org.htmlunit.WebClient`**: it is not Spring's reactive `WebClient`.

```java
import org.htmlunit.WebClient;
import org.htmlunit.html.HtmlPage;

@SpringBootTest
@AutoConfigureMockMvc
class HtmlUnitTests {

    @Autowired WebClient webClient;

    @BeforeEach
    void setUp() {
        webClient.getOptions().setFetchPolyfillEnabled(true); // page JS uses fetch()
    }

    @Test
    void addCityWithMouse() throws IOException {
        HtmlPage page = webClient.getPage("/");

        page.<HtmlInput>querySelector("input#citySearch").type("bogot");
        webClient.waitForBackgroundJavaScript(1000); // autocomplete XHR

        page.<HtmlElement>querySelector(".autocomplete-item").click();
        webClient.waitForBackgroundJavaScript(1000); // selection XHR + re-render

        assertThat(page.querySelectorAll(".cities-grid .card"))
            .singleElement()
            .extracting(DomNode::getTextContent).asString()
            .contains("Bogotá (Colombia)");
    }
}
```

- **Find elements** with `querySelectorAll(css)` (returns `DomNode`s) and `querySelector(css)`. Type the result for the action you need: `HtmlInput.type(...)`, `HtmlElement.click()`, `HtmlButton.click()`. Also `getElementById(id)`.
- **Assert on text** with `DomNode::getTextContent`. Select with stable hooks such as ids, `data-role` attributes and semantic classes, and assert on several cards or rows with `.map(...)`.
- **Keys**: `input.type(KeyboardEvent.DOM_VK_RETURN)`, `DOM_VK_DOWN`.
- **After every action that triggers JavaScript, call `webClient.waitForBackgroundJavaScript(timeoutMs)`** before asserting. JS runs asynchronously, so an assertion made too early sees the old DOM.
- **Navigation**: after a click that navigates (form submit, logout), read the new page with `page.getEnclosingWindow().getEnclosedPage()`; assert the URL with `assertThat(page.getUrl()).hasPath("/login")`.
- **JavaScript limits**: HtmlUnit runs JS in a Java engine (a fork of Mozilla Rhino), which lacks modern syntax. A failure looks like a cryptic parse error, for example `missing ; before statement (…/modern.js#11)` on an `async` line. Pin it down with a test that expects the `ScriptException`, or switch to Selenium.
- Server-side setup is the same as for HTTP tests (load `spring-testing-web`): stub external services with `@MockitoBean`, reset data in `@BeforeEach`, arrange data through services or repositories, then load the page.
- Secured pages: the `@WithMockUser` / `@WithUserDetails` annotations apply to HtmlUnit requests too; load `spring-testing-security`.
Files in this package (2)
  • SKILL.md 5 KB
  • selenium.md 5 KB

Versions

The database has no other skills named spring-testing-browser.

Database snapshot: 13.11.2026 · package version 8437ba2d9952 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90spring-boot
    Use when modifying a Java application that actually uses Spring Boot, Spring MVC, Spring Security, Spring Data, or Spring-managed configuration.
  • 100spring-boot-testing
    Write unit, integration, and slice tests for Spring Boot 3 applications. Use when writing unit tests, integration tests, or slice tests for Spring Boot 3 applications.
  • 100spring-boot-integration
    Spring Boot integration testing with Testcontainers, sliced tests, and full context. Covers real database testing, API integration, and end-to-end flows. USE WHEN: user mentions "spring integration test", "testcontainers spring", "full context test", asks about "@SpringBootTest…
  • 100spring-testing-strategy
    Choose the kind of test for Spring Boot code - plain unit test, @SpringBootTest, test slice, Spring Modulith module test, SpringApplicationBuilder, or browser test. Use when about to write tests in a Spring Boot app, or when deciding where a new test belongs.
  • 100spring-boot
    Spring Boot 4.x development - REST APIs, JPA, Security, Testing, and Cloud-native patterns. Use for building enterprise Java applications with Spring Boot.
  • 90selenium-mcp
    Use the selenium-mcp browser tools from Claude Code to inspect websites, run UI checks, capture evidence, and create or replay browser flows. Trigger when asked to test a web UI, automate browser interactions, investigate a browser-visible bug, or run selenium-mcp flows.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.