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.
- Author
- Kehrlann ↗
- Repository
- spring-boot-testing-skills ↗
- Licence
- Apache-2.0
- Last repository change
- 29.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.
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
- Steps
- HtmlUnit
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.