@cerios/playwright-table 1.0.2 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +421 -38
  2. package/package.json +16 -7
package/README.md CHANGED
@@ -2,63 +2,446 @@
2
2
 
3
3
  ## Introduction
4
4
 
5
- It is always hard to test HTML Tables. You will need multiple selectors/locators to get the data you need. This package will make it easy for you and parse it to a json based on the given headers and objects for each row of the table. Now you can assert the objects to your liking.
5
+ Testing HTML tables can be challenging due to their structure. This package simplifies the process by parsing HTML tables into JSON objects based on headers and rows, making it easier to assert table data in your tests.
6
6
 
7
- Given the following HTML
7
+ ---
8
8
 
9
- | id | name | yearOfBirth |
10
- | :-: | :----: | :---------: |
11
- | 1 | Ronald | 1987 |
12
- | 2 | Cerios | 2022 |
9
+ ## Installation
10
+
11
+ First, install and familiarize yourself with the Playwright testing library:
12
+ [Playwright Documentation](https://github.com/microsoft/playwright/blob/main/README.md)
13
+
14
+ Then, install this package:
15
+
16
+ ```bash
17
+ npm i @cerios/playwright-table
18
+ ```
13
19
 
14
- The result JSON will become:
20
+ Or as Dev dependency
15
21
 
22
+ ```bash
23
+ npm i -D @cerios/playwright-table
16
24
  ```
25
+
26
+ ---
27
+
28
+ ## Usage
29
+
30
+ ### Basic Setup
31
+
32
+ To use the package, create a new `PlaywrightTable` instance by passing a locator for the table element:
33
+
34
+ ```ts
35
+ const table = new PlaywrightTable(page.locator("table"));
36
+ ```
37
+
38
+ By default, the following selectors are used:
39
+
40
+ - Header rows: `thead > tr`
41
+ - Header cells: `th`
42
+ - Body rows: `tbody > tr`
43
+ - Body cells: `td`
44
+
45
+ ---
46
+
47
+ ## Methods and Examples
48
+
49
+ ### 1. `getHeaderRows`
50
+
51
+ Retrieves all header rows of the table. Works with colspan and rowspan. Every extra colspan of the same cell gets a counting postfix \_\_C
52
+
53
+ #### Example:
54
+
55
+ HTML Table:
56
+
57
+ <table>
58
+ <thead>
59
+ <tr>
60
+ <th rowspan="2">Awesome</th>
61
+ <th>First Name</th>
62
+ <th>Last Name</th>
63
+ </tr>
64
+ <tr>
65
+ <th colspan="2" style="text-align: center;">Full Name</th>
66
+ </tr>
67
+ </thead>
68
+ </table>
69
+
70
+ Code:
71
+
72
+ ```ts
73
+ const headers = await table.getHeaderRows();
74
+ console.log(headers);
75
+ ```
76
+
77
+ Output:
78
+
79
+ ```json
17
80
  [
18
- {
19
- id: 1,
20
- name: "Ronald",
21
- yearOfBirth: 1987
22
- },
23
- {
24
- id: 2,
25
- name: "Cerios",
26
- yearOfBirth: 2022
27
- },
81
+ ["Awesome", "First Name", "Last Name"],
82
+ ["Awesome", "Full Name", "Full Name__C1"]
28
83
  ]
29
84
  ```
30
85
 
31
- ## Installation
86
+ ---
87
+
88
+ ### 2. `getMainHeaderRow`
32
89
 
33
- First you need to install and get firmiliar with the amazing playwright testing library:
34
- https://github.com/microsoft/playwright/blob/main/README.md
90
+ Retrieves the main header row (default is the last row).
35
91
 
92
+ #### Example:
93
+
94
+ HTML Table:
95
+
96
+ <table>
97
+ <thead>
98
+ <tr>
99
+ <th colspan="2">Full Name</th>
100
+ </tr>
101
+ <tr>
102
+ <th>First Name</th>
103
+ <th>Last Name</th>
104
+ </tr>
105
+ </thead>
106
+ </table>
107
+
108
+ Code:
109
+
110
+ ```ts
111
+ const mainHeader = await table.getMainHeaderRow();
112
+ console.log(mainHeader);
113
+ // Output: ["First Name", "Last Name"]
36
114
  ```
37
- npx i -D @cerios/playwright-table
115
+
116
+ ---
117
+
118
+ ### 3. `getBodyRows`
119
+
120
+ Retrieves all body rows of the table.
121
+
122
+ #### Example:
123
+
124
+ HTML Table:
125
+
126
+ <table>
127
+ <tbody>
128
+ <tr>
129
+ <td>Ronald</td>
130
+ <td>Veth</td>
131
+ </tr>
132
+ <tr>
133
+ <td>Logan</td>
134
+ <td>Deacon</td>
135
+ </tr>
136
+ </tbody>
137
+ </table>
138
+
139
+ Code:
140
+
141
+ ```ts
142
+ const rows = await table.getBodyRows();
143
+ console.log(rows);
144
+ // Output: [["Ronald", "Veth"], ["Logan", "Deacon"]]
38
145
  ```
39
146
 
40
- ## Usage
147
+ ---
148
+
149
+ ### 4. `getBodyCellLocator`
150
+
151
+ Retrieves a specific cell locator in the body of the table.
41
152
 
42
- There can be more tables on a webpage. So you first need to identify the unique locator that wraps you complete table element.
153
+ #### Example:
43
154
 
44
- Create a new PlaywrightTable
155
+ HTML Table:
45
156
 
157
+ <table>
158
+ <tbody>
159
+ <tr>
160
+ <td>Ronald</td>
161
+ <td>Veth</td>
162
+ </tr>
163
+ <tr>
164
+ <td>Principal</td>
165
+ <td>Cerios</td>
166
+ </tr>
167
+ </tbody>
168
+ </table>
169
+
170
+ Code:
171
+
172
+ ```ts
173
+ const cellLocator = table.getBodyCellLocator(1, 1);
174
+ await expect(cellLocator).toHaveText("Cerios");
46
175
  ```
47
- const table = new PlaywrightTable(page.locator("table"));
176
+
177
+ ---
178
+
179
+ ### 5. `getBodyCellLocatorByRowConditions`
180
+
181
+ Retrieves a cell locator in the body of the table based on row conditions and a target header.
182
+
183
+ #### Example:
184
+
185
+ HTML Table:
186
+
187
+ <table>
188
+ <thead>
189
+ <tr>
190
+ <th>First Name</th>
191
+ <th>Last Name</th>
192
+ </tr>
193
+ </thead>
194
+ <tbody>
195
+ <tr>
196
+ <td>Ronald</td>
197
+ <td>Veth</td>
198
+ </tr>
199
+ <tr>
200
+ <td>Principal</td>
201
+ <td>Cerios</td>
202
+ </tr>
203
+ </tbody>
204
+ </table>
205
+
206
+ Code:
207
+
208
+ ```ts
209
+ const cellLocator = await table.getBodyCellLocatorByRowConditions({ "First Name": "Principal" }, "Last Name");
210
+ await expect(cellLocator).toHaveText("Cerios");
211
+ ```
212
+
213
+ ---
214
+
215
+ ### 6. `getAllBodyCellLocatorsByHeaderName`
216
+
217
+ Retrieves all cell locators in the body of the table for a specific header name.
218
+
219
+ #### Example:
220
+
221
+ HTML Table:
222
+
223
+ <table>
224
+ <thead>
225
+ <tr>
226
+ <th>First Name</th>
227
+ <th>Last Name</th>
228
+ </tr>
229
+ </thead>
230
+ <tbody>
231
+ <tr>
232
+ <td>Ronald</td>
233
+ <td>Veth</td>
234
+ </tr>
235
+ <tr>
236
+ <td>Principal</td>
237
+ <td>Cerios</td>
238
+ </tr>
239
+ </tbody>
240
+ </table>
241
+
242
+ Code:
243
+
244
+ ```ts
245
+ const locators = await table.getAllBodyCellLocatorsByHeaderName("Last Name");
246
+ for (const locator of locators) {
247
+ console.log(await locator.textContent());
248
+ // Output: ["Veth", "Cerios"]
249
+ }
250
+ ```
251
+
252
+ ---
253
+
254
+ ### 7. `getAllBodyCellLocatorsByHeaderIndex`
255
+
256
+ Retrieves all cell locators in the body of the table for a specific header index.
257
+
258
+ #### Example:
259
+
260
+ HTML Table:
261
+
262
+ <table>
263
+ <thead>
264
+ <tr>
265
+ <th>First Name</th>
266
+ <th>Last Name</th>
267
+ </tr>
268
+ </thead>
269
+ <tbody>
270
+ <tr>
271
+ <td>Ronald</td>
272
+ <td>Veth</td>
273
+ </tr>
274
+ <tr>
275
+ <td>Principal</td>
276
+ <td>Cerios</td>
277
+ </tr>
278
+ </tbody>
279
+ </table>
280
+
281
+ Code:
282
+
283
+ ```ts
284
+ const locators = await table.getAllBodyCellLocatorsByHeaderIndex(1);
285
+ for (const locator of locators) {
286
+ console.log(await locator.textContent());
287
+ // Output: ["Veth", "Cerios"]
288
+ }
289
+ ```
290
+
291
+ ---
292
+
293
+ ### 8. `getJson`
294
+
295
+ Converts the table data into a JSON object.
296
+
297
+ #### Example:
298
+
299
+ HTML Table **SIMPLE**:
300
+
301
+ <table>
302
+ <thead>
303
+ <tr>
304
+ <th>id</th>
305
+ <th>name</th>
306
+ <th>yearOfBirth</th>
307
+ </tr>
308
+ </thead>
309
+ <tbody>
310
+ <tr>
311
+ <td>1</td>
312
+ <td>Ronald</td>
313
+ <td>1987</td>
314
+ </tr>
315
+ <tr>
316
+ <td>2</td>
317
+ <td>Cerios</td>
318
+ <td>2022</td>
319
+ </tr>
320
+ </tbody>
321
+ </table>
322
+
323
+ Code:
324
+
325
+ ```ts
326
+ const json = await table.getJson();
327
+ console.log(json);
328
+ ```
329
+
330
+ Output:
331
+
332
+ ```json
333
+ [
334
+ {
335
+ "id": 1,
336
+ "name": "Ronald",
337
+ "yearOfBirth": 1987
338
+ },
339
+ {
340
+ "id": 2,
341
+ "name": "Cerios",
342
+ "yearOfBirth": 2022
343
+ }
344
+ ]
345
+ ```
346
+
347
+ #### Example:
348
+
349
+ HTML Table **COMPLEX**:
350
+
351
+ <table>
352
+ <thead>
353
+ <tr>
354
+ <th rowspan="2">Awesome Rowspan</th>
355
+ <th>Very Duplicate</th>
356
+ <th colspan="3">Mega colspan</th>
357
+ <th></th>
358
+ <th></th>
359
+ <th>Very Duplicate</th>
360
+ </tr>
361
+ </thead>
362
+ <tbody>
363
+ <tr>
364
+ <td></td>
365
+ <td>Ronald</td>
366
+ <td>Veth</td>
367
+ <td>Test</td>
368
+ <td>Automator</td>
369
+ <td>At</td>
370
+ <td>Cerios</td>
371
+ <td>!</td>
372
+ </tr>
373
+ </tbody>
374
+ </table>
375
+
376
+ Code:
377
+
378
+ ```ts
379
+ const json = await table.getJson();
380
+ console.log(json);
381
+ ```
382
+
383
+ Output:
384
+
385
+ ```json
386
+ [
387
+ {
388
+ "Awesome Rowspan": "",
389
+ "Very Duplicate": "Ronald",
390
+ "Mega colspan": "Veth",
391
+ "Mega colspan__C1": "Test",
392
+ "Mega colspan__C2": "Automator",
393
+ "{{Empty}}": "At",
394
+ "{{Empty}}__D1": "Cerios",
395
+ "Very Duplicate__D1": "!"
396
+ }
397
+ ]
398
+ ```
399
+
400
+ ---
401
+
402
+ ### 9. `waitForHeaderRows`
403
+
404
+ Waits for the header rows to be loaded.
405
+
406
+ #### Example:
407
+
408
+ ```ts
409
+ await table.waitForHeaderRows({ timeout: 5000 });
410
+ ```
411
+
412
+ ---
413
+
414
+ ### 10. `waitForBodyRows`
415
+
416
+ Waits for the body rows to be loaded.
417
+
418
+ #### Example:
419
+
420
+ ```ts
421
+ await table.waitForBodyRows({ timeout: 5000 });
422
+ ```
423
+
424
+ ---
425
+
426
+ ## Advanced Options
427
+
428
+ You can customize the behavior of the table parsing by passing options to the `PlaywrightTable` constructor. For example:
429
+
430
+ ```ts
431
+ const table = new PlaywrightTable(page.locator("table"), {
432
+ header: {
433
+ rowSelector: ".custom-header-row",
434
+ columnSelector: ".custom-header-cell",
435
+ },
436
+ row: {
437
+ rowSelector: ".custom-body-row",
438
+ columnSelector: ".custom-body-cell",
439
+ },
440
+ });
48
441
  ```
49
442
 
50
- Without extra options the defaults for header rows(thead>tr), header cells(thead), body rows(tbody/tr) and body cells(td) will be used.
51
- Now you can call the following methods:
443
+ ---
52
444
 
53
- - getHeaderRows
54
- - getMainHeaderRow (default last)
55
- - getBodyRows
56
- - getBodyCellLocator
57
- - getBodyCellLocatorByRowConditions
58
- - getAllBodyCellLocatorsByHeaderName
59
- - getAllBodyCellLocatorsByHeaderIndex
60
- - getJson
61
- - waitForHeaderRows
62
- - waitForBodyRows
445
+ ## License
63
446
 
64
- More information will be provided soon. Check the unit tests for inspiration...
447
+ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
package/package.json CHANGED
@@ -1,9 +1,8 @@
1
1
  {
2
2
  "name": "@cerios/playwright-table",
3
- "version": "1.0.2",
3
+ "version": "1.0.4",
4
4
  "author": "Ronald Veth - Cerios",
5
5
  "description": "Easy Html Tables handler for Playwright",
6
- "homepage": "https://www.cerios.nl/",
7
6
  "license": "MIT",
8
7
  "keywords": [
9
8
  "playwright",
@@ -11,6 +10,14 @@
11
10
  "table",
12
11
  "testing"
13
12
  ],
13
+ "bugs": {
14
+ "url": "https://github.com/CeriosTesting/playwright-tables/issues"
15
+ },
16
+ "homepage": "https://github.com/CeriosTesting/playwright-tables#readme",
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/CeriosTesting/playwright-tables.git"
20
+ },
14
21
  "scripts": {
15
22
  "format": "prettier --write . --cache --ignore-path=.prettierignore",
16
23
  "test": "playwright test",
@@ -19,14 +26,16 @@
19
26
  "serve": "serve tests/demo-html -p 3000",
20
27
  "check-exports": "attw --pack .",
21
28
  "changeset": "npx changeset",
22
- "local-release": "changeset version && changeset publish"
29
+ "local-release": "changeset version && changeset publish",
30
+ "compile": "tsc --noEmit",
31
+ "update-all-packages": "npx npm-check-updates -u && npm i"
23
32
  },
24
33
  "devDependencies": {
25
- "@arethetypeswrong/cli": "^0.18.0",
26
- "@changesets/cli": "^2.29.3",
27
- "@playwright/test": "^1.51.1",
34
+ "@arethetypeswrong/cli": "^0.18.1",
35
+ "@changesets/cli": "^2.29.4",
36
+ "@playwright/test": "^1.52.0",
28
37
  "husky": "^9.1.7",
29
- "lint-staged": "^15.5.0",
38
+ "lint-staged": "^16.0.0",
30
39
  "prettier": "^3.5.3",
31
40
  "serve": "^14.2.4",
32
41
  "ts-node": "^10.9.2",