Skip to content

Commit 1e259e7

Browse files
rbrirbri
committed
Improve WebAssert javadoc
1 parent ae53ff3 commit 1e259e7

File tree

2 files changed

+73
-5
lines changed

2 files changed

+73
-5
lines changed

‎src/changes/changes.xml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@
88

99
<body>
1010
<release version="4.15.0" date="August 17, 2025" description="Chrome/Edge 139, Firefox 141, core-js, Bugfixes">
11+
<action type="update" dev="rbri">
12+
Improve WebAssert javadoc.
13+
</action>
1114
<action type="update" dev="rbri">
1215
Improve WebClientOptions javadoc.
1316
</action>

‎src/main/java/org/htmlunit/WebAssert.java‎

Lines changed: 70 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,22 @@
2727
/**
2828
* Utility class which contains standard assertions for HTML pages.
2929
*
30+
* <p>This class provides a collection of static assertion methods for testing
31+
* HTML page content, structure, and behavior. All assertion methods throw
32+
* {@link AssertionError} when the expected condition is not met.</p>
33+
*
34+
* <p>Common use cases include:</p>
35+
* <ul>
36+
* <li>Verifying page titles and content</li>
37+
* <li>Checking for presence/absence of elements</li>
38+
* <li>Validating form inputs and links</li>
39+
* <li>Ensuring accessibility attributes are properly set</li>
40+
* </ul>
41+
*
3042
* @author Daniel Gredler
3143
* @author Mike Bowler
3244
* @author Ahmed Ashour
45+
* @author Ronald Broöö
3346
*/
3447
public final class WebAssert {
3548

@@ -45,6 +58,8 @@ private WebAssert() {
4558
*
4659
* @param page the page to check
4760
* @param title the expected title
61+
* @throws AssertionError if the page title does not match the expected title
62+
* @throws NullPointerException if page or title is null
4863
*/
4964
public static void assertTitleEquals(final HtmlPage page, final String title) {
5065
final String s = page.getTitleText();
@@ -59,6 +74,8 @@ public static void assertTitleEquals(final HtmlPage page, final String title) {
5974
*
6075
* @param page the page to check
6176
* @param titlePortion the substring which the page title is expected to contain
77+
* @throws AssertionError if the page title does not contain the substring
78+
* @throws NullPointerException if page or titlePortion is null
6279
*/
6380
public static void assertTitleContains(final HtmlPage page, final String titlePortion) {
6481
final String s = page.getTitleText();
@@ -73,6 +90,8 @@ public static void assertTitleContains(final HtmlPage page, final String titlePo
7390
*
7491
* @param page the page to check
7592
* @param regex the regular expression that the page title is expected to match
93+
* @throws AssertionError if the page title does not match the regular expression
94+
* @throws NullPointerException if page or regex is null
7695
*/
7796
public static void assertTitleMatches(final HtmlPage page, final String regex) {
7897
final String s = page.getTitleText();
@@ -86,7 +105,9 @@ public static void assertTitleMatches(final HtmlPage page, final String regex) {
86105
* Verifies that the specified page contains an element with the specified ID.
87106
*
88107
* @param page the page to check
89-
* @param id the expected ID of an element in the page
108+
* @param id the ID of an element expected in the page
109+
* @throws AssertionError if no element with the specified ID is found
110+
* @throws NullPointerException if page or id is null
90111
*/
91112
public static void assertElementPresent(final HtmlPage page, final String id) {
92113
try {
@@ -101,8 +122,16 @@ public static void assertElementPresent(final HtmlPage page, final String id) {
101122
/**
102123
* Verifies that the specified page contains an element matching the specified XPath expression.
103124
*
125+
* <p><b>Example usage:</b></p>
126+
* <pre>{@code
127+
* WebAssert.assertElementPresentByXPath(page, "//div[@class='error']");
128+
* WebAssert.assertElementPresentByXPath(page, "//input[@type='submit' and @value='Login']");
129+
* }</pre>
130+
*
104131
* @param page the page to check
105132
* @param xpath the XPath expression which is expected to match an element in the page
133+
* @throws AssertionError if no elements match the XPath expression
134+
* @throws NullPointerException if page or xpath is null
106135
*/
107136
public static void assertElementPresentByXPath(final HtmlPage page, final String xpath) {
108137
final List<?> elements = page.getByXPath(xpath);
@@ -118,6 +147,8 @@ public static void assertElementPresentByXPath(final HtmlPage page, final String
118147
*
119148
* @param page the page to check
120149
* @param id the ID of an element which expected to not exist on the page
150+
* @throws AssertionError if an element with the specified ID is found
151+
* @throws NullPointerException if page or id is null
121152
*/
122153
public static void assertElementNotPresent(final HtmlPage page, final String id) {
123154
try {
@@ -136,12 +167,13 @@ public static void assertElementNotPresent(final HtmlPage page, final String id)
136167
*
137168
* @param page the page to check
138169
* @param xpath the XPath expression which is expected to not match an element in the page
170+
* @throws AssertionError if any elements match the XPath expression
139171
*/
140172
public static void assertElementNotPresentByXPath(final HtmlPage page, final String xpath) {
141173
final List<?> elements = page.getByXPath(xpath);
142174
if (!elements.isEmpty()) {
143-
final String msg = "The page does not contain any elements matching the XPath expression '" + xpath
144-
+ "'.";
175+
final String msg = "The page contains " + elements.size()
176+
+ " element(s) matching the XPath expression '" + xpath + "'.";
145177
throw new AssertionError(msg);
146178
}
147179
}
@@ -151,6 +183,8 @@ public static void assertElementNotPresentByXPath(final HtmlPage page, final Str
151183
*
152184
* @param page the page to check
153185
* @param text the text to check for
186+
* @throws AssertionError if the page does not contain the specified text
187+
* @throws NullPointerException if page or text is null
154188
*/
155189
public static void assertTextPresent(final HtmlPage page, final String text) {
156190
if (!page.asNormalizedText().contains(text)) {
@@ -166,6 +200,9 @@ public static void assertTextPresent(final HtmlPage page, final String text) {
166200
* @param page the page to check
167201
* @param text the text to check for
168202
* @param id the ID of the element which is expected to contain the specified text
203+
* @throws AssertionError if the element does not contain the specified text
204+
* @throws ElementNotFoundException if no element with the specified ID exists
205+
* @throws NullPointerException if any parameter is null
169206
*/
170207
public static void assertTextPresentInElement(final HtmlPage page, final String text, final String id) {
171208
try {
@@ -187,6 +224,8 @@ public static void assertTextPresentInElement(final HtmlPage page, final String
187224
*
188225
* @param page the page to check
189226
* @param text the text to check for
227+
* @throws AssertionError if the page contains the specified text
228+
* @throws NullPointerException if page or text is null
190229
*/
191230
public static void assertTextNotPresent(final HtmlPage page, final String text) {
192231
if (page.asNormalizedText().contains(text)) {
@@ -223,6 +262,9 @@ public static void assertTextNotPresentInElement(final HtmlPage page, final Stri
223262
*
224263
* @param page the page to check
225264
* @param id the ID of the link which the page is expected to contain
265+
* @throws AssertionError if no link with the specified ID is found
266+
* @see #assertLinkNotPresent(HtmlPage, String)
267+
* @see #assertLinkPresentWithText(HtmlPage, String)
226268
*/
227269
public static void assertLinkPresent(final HtmlPage page, final String id) {
228270
try {
@@ -239,6 +281,9 @@ public static void assertLinkPresent(final HtmlPage page, final String id) {
239281
*
240282
* @param page the page to check
241283
* @param id the ID of the link which the page is expected to not contain
284+
* @throws AssertionError if a link with the specified ID is found
285+
* @see #assertLinkPresent(HtmlPage, String)
286+
* @see #assertLinkNotPresentWithText(HtmlPage, String)
242287
*/
243288
public static void assertLinkNotPresent(final HtmlPage page, final String id) {
244289
try {
@@ -298,6 +343,8 @@ public static void assertLinkNotPresentWithText(final HtmlPage page, final Strin
298343
*
299344
* @param page the page to check
300345
* @param name the expected name of a form on the page
346+
* @throws AssertionError if no form with the specified name is found
347+
* @see #assertFormNotPresent(HtmlPage, String)
301348
*/
302349
public static void assertFormPresent(final HtmlPage page, final String name) {
303350
try {
@@ -314,6 +361,8 @@ public static void assertFormPresent(final HtmlPage page, final String name) {
314361
*
315362
* @param page the page to check
316363
* @param name the name of a form which should not exist on the page
364+
* @throws AssertionError if a form with the specified name is found
365+
* @see #assertFormPresent(HtmlPage, String)
317366
*/
318367
public static void assertFormNotPresent(final HtmlPage page, final String name) {
319368
try {
@@ -331,6 +380,9 @@ public static void assertFormNotPresent(final HtmlPage page, final String name)
331380
*
332381
* @param page the page to check
333382
* @param name the name of the input element to look for
383+
* @throws AssertionError if no input element with the specified name is found
384+
* @see #assertInputNotPresent(HtmlPage, String)
385+
* @see #assertInputContainsValue(HtmlPage, String, String)
334386
*/
335387
public static void assertInputPresent(final HtmlPage page, final String name) {
336388
final String xpath = "//input[@name='" + name + "']";
@@ -345,12 +397,14 @@ public static void assertInputPresent(final HtmlPage page, final String name) {
345397
*
346398
* @param page the page to check
347399
* @param name the name of the input element to look for
400+
* @throws AssertionError if an input element with the specified name is found
401+
* @throws NullPointerException if page or name is null
348402
*/
349403
public static void assertInputNotPresent(final HtmlPage page, final String name) {
350404
final String xpath = "//input[@name='" + name + "']";
351405
final List<?> list = page.getByXPath(xpath);
352406
if (!list.isEmpty()) {
353-
throw new AssertionError("Unable to find an input element named '" + name + "'.");
407+
throw new AssertionError("Found an input element named '" + name + "' when none was expected.");
354408
}
355409
}
356410

@@ -405,9 +459,13 @@ public static void assertInputDoesNotContainValue(final HtmlPage page, final Str
405459
* all tabbable elements should have the <code>tabindex</code> attribute set.</p>
406460
*
407461
* <p>This method verifies that all tabbable elements have a valid value set for
408-
* the <code>tabindex</code> attribute.</p>
462+
* the <code>tabindex</code> attribute. Valid values are positive integers,
463+
* 0 (for default tab order), or -1 (to exclude from tab order).</p>
464+
*
465+
* <p>The following elements are checked: a, area, button, input, object, select, textarea</p>
409466
*
410467
* @param page the page to check
468+
* @throws AssertionError if any tabbable element has an invalid or missing tabindex attribute
411469
*/
412470
public static void assertAllTabIndexAttributesSet(final HtmlPage page) {
413471
final List<String> tags =
@@ -429,7 +487,10 @@ public static void assertAllTabIndexAttributesSet(final HtmlPage page) {
429487
* keyboard navigation. This method verifies that all the <code>accesskey</code> attributes on the
430488
* specified page are unique.
431489
*
490+
* <p>Duplicate access keys can confuse users and make keyboard navigation unpredictable.</p>
491+
*
432492
* @param page the page to check
493+
* @throws AssertionError if any access key is used more than once on the page
433494
*/
434495
public static void assertAllAccessKeyAttributesUnique(final HtmlPage page) {
435496
final List<String> list = new ArrayList<>();
@@ -448,6 +509,8 @@ public static void assertAllAccessKeyAttributesUnique(final HtmlPage page) {
448509
* Verifies that all element IDs in the specified page are unique.
449510
*
450511
* @param page the page to check
512+
* @throws AssertionError if any element ID is used more than once on the page
513+
* @throws NullPointerException if page is null
451514
*/
452515
public static void assertAllIdAttributesUnique(final HtmlPage page) {
453516
final List<String> list = new ArrayList<>();
@@ -465,8 +528,10 @@ public static void assertAllIdAttributesUnique(final HtmlPage page) {
465528
/**
466529
* Assert that the specified parameter is not null. Throw a NullPointerException
467530
* if a null is found.
531+
*
468532
* @param description the description to pass into the NullPointerException
469533
* @param object the object to check for null
534+
* @throws NullPointerException if the object is null
470535
*/
471536
public static void notNull(final String description, final Object object) {
472537
if (object == null) {

0 commit comments

Comments
 (0)