Skip to content

Commit 70d5223

Browse files
vasu31devvasu31dev
committed
chore: bump version to 1.25.0; update dependencies and improve assertion skills documentation
1 parent 4a7c53b commit 70d5223

3 files changed

Lines changed: 194 additions & 251 deletions

File tree

‎.claude/skills/vasu-playwright-utils/references/assertions.md‎

Lines changed: 98 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -2,143 +2,138 @@
22

33
Source: `src/vasu-playwright-lib/utils/assert-utils.ts`
44

5-
## Overview
5+
## Using Assertions in Spec Files
66

7-
Assert utils wrap Playwright's auto-retrying `expect` assertions with a simplified API. All assertion functions:
7+
**Do not use assertions in spec files.** Assertions are for building and verifying behaviour inside page objects (e.g. `verify*` methods). Spec files should only orchestrate steps and call those methods so the test reads like a clear, readable scenario.
88

9-
- Accept `string | Locator` as the `input` parameter (converted to Locator internally)
10-
- Support `soft` option for soft assertions that don't stop the test
11-
- Support `timeout` option to override the default expect timeout
12-
- Auto-retry until the condition is met or timeout is reached
9+
### Good Example — Readable Spec (No Assertions in Spec)
1310

14-
## Soft Assertions
11+
The spec reads like a test plan; all assertions live in page files.
1512

16-
Pass `{ soft: true }` to any assertion to make it a soft assertion. Soft assertions record failures but don't stop the test. Call `assertAllSoftAssertions(testInfo)` at the end to verify all passed.
13+
**Spec file** — plain English, no assertion utils:
1714

1815
```typescript
19-
await expectElementToBeVisible('#header', { soft: true });
20-
await expectElementToHaveText('#title', 'Welcome', { soft: true });
21-
assertAllSoftAssertions(testInfo); // Fails if any soft assertion failed
16+
test('Complete checkout flow', async () => {
17+
await LoginPage.loginWithValidCredentials();
18+
await ProductsPage.verifyProductsPageIsDisplayed();
19+
await ProductsPage.addToCartByProductNumber(1);
20+
await MiniCart.verifyMiniCartCount('1');
21+
await CheckoutPage.goToCart();
22+
await CheckoutPage.clickCheckout();
23+
await CheckoutPage.fillCheckoutInfo();
24+
await CheckoutPage.clickContinue();
25+
await CheckoutPage.clickFinish();
26+
await CheckoutPage.verifyOrderComplete();
27+
});
2228
```
2329

24-
## Element Visibility & State
30+
**Page file** — assertions live here with descriptive messages:
2531

26-
### `expectElementToBeVisible(input, options?: ExpectOptions)`
27-
28-
Asserts element is present in DOM and visible.
29-
30-
### `expectElementToBeHidden(input, options?: ExpectOptions)`
31-
32-
Asserts element is not present in DOM or is hidden.
33-
34-
### `expectElementToBeAttached(input, options?: ExpectOptions)`
35-
36-
Asserts element is present in DOM (may not be visible).
32+
```typescript
33+
// sauce-demo-products-page.ts
34+
import { expectElementToBeVisible, expectElementToBeHidden } from '@utils/assert-utils';
35+
import { getLocator } from '@utils/locator-utils';
3736

38-
### `expectElementToBeInViewport(input, options?: ExpectOptions)`
37+
const productsContainer = () => getLocator('#inventory_container').nth(0);
3938

40-
Asserts element is visible within the page viewport.
39+
export async function verifyProductsPageIsDisplayed() {
40+
await expectElementToBeVisible(productsContainer(), { timeout: 1000, message: 'Logged in user should see Products' });
41+
}
4142

42-
### `expectElementNotToBeInViewport(input, options?: ExpectOptions)`
43+
export async function verifyProductsPageIsNotDisplayed() {
44+
await expectElementToBeHidden(productsContainer(), 'Products should not be displayed');
45+
}
46+
```
4347

44-
Asserts element is not in the viewport.
48+
```typescript
49+
// sauce-demo-checkout-page.ts
50+
import { expectElementToContainText } from '@utils/assert-utils';
51+
52+
export async function verifyOrderComplete() {
53+
await expectElementToContainText(orderCompleteMessage(), /thank you for your order/i, {
54+
message: 'Checkout complete message should be displayed',
55+
});
56+
}
57+
```
4558

46-
## Checkbox State
59+
## Overview
4760

48-
### `expectElementToBeChecked(input, options?: ExpectOptions)`
61+
All assertion functions:
4962

50-
### `expectElementNotToBeChecked(input, options?: ExpectOptions)`
63+
- Accept `string | Locator` as the `input` parameter
64+
- Support `soft` option for soft assertions that don't stop the test
65+
- Support `timeout` option to override the default expect timeout
66+
- Support `message` option (or a string shorthand) for descriptive failure messages
67+
- Auto-retry until the condition is met or timeout is reached
5168

52-
## Enabled/Disabled/Editable
69+
## Soft Assertions
5370

54-
### `expectElementToBeDisabled(input, options?: ExpectOptions)`
71+
Pass `{ soft: true }` to any assertion. Call `assertAllSoftAssertions(testInfo)` at the end to fail the test if any soft assertion failed.
5572

56-
### `expectElementToBeEnabled(input, options?: ExpectOptions)`
73+
```typescript
74+
await expectElementToBeVisible('#header', { soft: true });
75+
await expectElementToHaveText('#title', 'Welcome', { soft: true });
76+
assertAllSoftAssertions(testInfo);
77+
```
5778

58-
### `expectElementToBeEditable(input, options?: ExpectOptions)`
79+
## Element Assertions
80+
81+
| Function | Description |
82+
| ------------------------------------------------- | -------------------------------------- |
83+
| `expectElementToBeVisible(input, options?)` | Element is in DOM and visible |
84+
| `expectElementToBeHidden(input, options?)` | Element is not in DOM or hidden |
85+
| `expectElementToBeAttached(input, options?)` | Element is in DOM (may not be visible) |
86+
| `expectElementToBeInViewport(input, options?)` | Element is visible in viewport |
87+
| `expectElementNotToBeInViewport(input, options?)` | Element is not in viewport |
88+
| `expectElementToBeChecked(input, options?)` | Checkbox/radio is checked |
89+
| `expectElementNotToBeChecked(input, options?)` | Checkbox/radio is not checked |
90+
| `expectElementToBeDisabled(input, options?)` | Element is disabled |
91+
| `expectElementToBeEnabled(input, options?)` | Element is enabled |
92+
| `expectElementToBeEditable(input, options?)` | Element is editable |
5993

6094
## Text Assertions
6195

62-
### `expectElementToHaveText(input, text, options?)`
63-
64-
Asserts element's text content equals the provided value.
65-
66-
- `text`: `string | RegExp | Array<string | RegExp>`
67-
- Options extend `ExpectOptions` with `ignoreCase?: boolean` and `useInnerText?: boolean`
68-
69-
### `expectElementNotToHaveText(input, text, options?)`
96+
| Function | Description |
97+
| ------------------------------------------------------ | ------------------------------- |
98+
| `expectElementToHaveText(input, text, options?)` | Text equals value (exact match) |
99+
| `expectElementNotToHaveText(input, text, options?)` | Text does NOT equal value |
100+
| `expectElementToContainText(input, text, options?)` | Text contains value (substring) |
101+
| `expectElementNotToContainText(input, text, options?)` | Text does NOT contain value |
70102

71-
Asserts element's text does NOT equal the provided value.
72-
73-
### `expectElementToContainText(input, text, options?)`
74-
75-
Asserts element's text contains the provided value (substring match).
76-
77-
### `expectElementNotToContainText(input, text, options?)`
78-
79-
Asserts element's text does NOT contain the provided value.
103+
`text` accepts `string | RegExp | Array<string | RegExp>`. Options extend with `ignoreCase?: boolean` and `useInnerText?: boolean`.
80104

81105
## Value Assertions
82106

83-
### `expectElementToHaveValue(input, text: string | RegExp, options?)`
84-
85-
Asserts an input element has the specified value.
86-
87-
### `expectElementToHaveValues(input, texts: Array<string | RegExp>, options?)`
88-
89-
Asserts a multi-select has the specified values selected.
90-
91-
### `expectElementValueToBeEmpty(input, options?)`
92-
93-
Asserts an input/editable element is empty.
94-
95-
### `expectElementValueNotToBeEmpty(input, options?)`
96-
97-
Asserts an input/editable element is not empty.
98-
99-
## Attribute Assertions
100-
101-
### `expectElementToHaveAttribute(input, attribute: string, value: string | RegExp, options?)`
102-
103-
Asserts element has an attribute with the exact value.
107+
| Function | Description |
108+
| --------------------------------------------------- | ----------------------------------- |
109+
| `expectElementToHaveValue(input, text, options?)` | Input has the specified value |
110+
| `expectElementToHaveValues(input, texts, options?)` | Multi-select has specified values |
111+
| `expectElementValueToBeEmpty(input, options?)` | Input/editable element is empty |
112+
| `expectElementValueNotToBeEmpty(input, options?)` | Input/editable element is not empty |
104113

105-
### `expectElementToContainAttribute(input, attribute: string, value: string | RegExp, options?)`
114+
## Attribute & Count Assertions
106115

107-
Asserts element has an attribute whose value contains the given pattern.
108-
109-
## Count Assertion
110-
111-
### `expectElementToHaveCount(input, count: number, options?)`
112-
113-
Asserts the number of elements matching the selector equals `count`.
116+
| Function | Description |
117+
| --------------------------------------------------------------- | ---------------------------------------- |
118+
| `expectElementToHaveAttribute(input, attr, value, options?)` | Attribute equals value |
119+
| `expectElementToContainAttribute(input, attr, value, options?)` | Attribute contains value |
120+
| `expectElementToHaveCount(input, count, options?)` | Number of matching elements equals count |
114121

115122
## Page Assertions
116123

117-
### `expectPageToHaveURL(urlOrRegExp: string | RegExp, options?)`
118-
119-
Asserts the current page URL matches exactly.
120-
121-
### `expectPageToContainURL(url: string, options?)`
122-
123-
Asserts the current page URL contains the given string.
124-
125-
### `expectPageToHaveTitle(titleOrRegExp: string | RegExp, options?)`
126-
127-
Asserts the page title matches.
128-
129-
### `expectPageSizeToBeEqualTo(numberOfPages: number, options?)`
130-
131-
Asserts the number of open pages in the browser context.
124+
| Function | Description |
125+
| ------------------------------------------------ | --------------------------------- |
126+
| `expectPageToHaveURL(urlOrRegExp, options?)` | Page URL matches exactly |
127+
| `expectPageToContainURL(url, options?)` | Page URL contains string |
128+
| `expectPageToHaveTitle(titleOrRegExp, options?)` | Page title matches |
129+
| `expectPageSizeToBeEqualTo(count, options?)` | Number of open pages equals count |
132130

133131
## Alert Assertions
134132

135-
### `expectAlertToHaveText(input, text: string, options?)`
136-
137-
Clicks element, triggers dialog, asserts dialog message equals `text`.
138-
139-
### `expectAlertToMatchText(input, text: string | RegExp, options?)`
140-
141-
Clicks element, triggers dialog, asserts dialog message matches `text`.
133+
| Function | Description |
134+
| ----------------------------------------------- | -------------------------------------------------- |
135+
| `expectAlertToHaveText(input, text, options?)` | Clicks element, asserts alert text equals value |
136+
| `expectAlertToMatchText(input, text, options?)` | Clicks element, asserts alert text matches pattern |
142137

143138
## Option Types
144139

@@ -148,8 +143,5 @@ type ExpectOptions = TimeoutOption & SoftOption & MessageOrOptions;
148143
// SoftOption = { soft?: boolean }
149144
// MessageOrOptions = string | { message?: string }
150145

151-
type ExpectTextOptions = {
152-
ignoreCase?: boolean;
153-
useInnerText?: boolean;
154-
};
146+
type ExpectTextOptions = { ignoreCase?: boolean; useInnerText?: boolean };
155147
```

0 commit comments

Comments
 (0)