@projectwallace/css-code-coverage 0.1.3 → 0.2.0
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.
- package/README.md +44 -11
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
# CSS Code Coverage
|
|
2
2
|
|
|
3
|
+
> [!WARNING]
|
|
4
|
+
> This is a very experimental approach to calculating CSS Code Coverage and currently very much a work in progress.
|
|
5
|
+
|
|
3
6
|
Takes your generated coverage files and turns them into something actually usable. Accepts coverage reports generated by browsers (Edge/Chrome/chromium), Puppeteer, Playwright.
|
|
4
7
|
|
|
5
8
|
Features include:
|
|
@@ -17,14 +20,32 @@ npm install @projectwallace/css-code-coverage
|
|
|
17
20
|
|
|
18
21
|
## Usage
|
|
19
22
|
|
|
20
|
-
|
|
23
|
+
```ts
|
|
24
|
+
import { calculate_coverage } from '@projectwallace/css-code-coverage'
|
|
25
|
+
|
|
26
|
+
function parse_html(html) {
|
|
27
|
+
return new DOMParser().parseFromString(html, 'text/html')
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
let report = calculcate_coverage(coverage_data, parse_html)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
See [src/index.ts](https://github.com/projectwallace/css-code-coverage/blob/main/src/index.ts) for the data that's returned.
|
|
34
|
+
|
|
35
|
+
## Collecting CSS Coverage
|
|
36
|
+
|
|
37
|
+
There are two principal ways of collecting CSS Coverage data:
|
|
38
|
+
|
|
39
|
+
### Browser devtools
|
|
21
40
|
|
|
22
|
-
|
|
41
|
+
In Edge, Chrome or chromium you can manually collect coverage in the browser's DevTools. In all cases you'll generate coverage data manually and the browser will let you export the data to a JSON file. Note that this JSON contains both JS coverage as well as the CSS coverage. Learn how it works:
|
|
23
42
|
|
|
24
|
-
|
|
25
|
-
|
|
43
|
+
- Collect coverage in Microsoft Edge: https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/coverage/
|
|
44
|
+
- Collect coevrage in Google Chrome: https://developer.chrome.com/docs/devtools/coverage/
|
|
26
45
|
|
|
27
|
-
|
|
46
|
+
Additionally, DevTools Tips writes about it in their [explainer](https://devtoolstips.org/tips/en/detect-unused-code/).
|
|
47
|
+
|
|
48
|
+
You end up with one or more JSON files that contain coverage data. We provide a helper `parse_coverage()` that both parses the JSON and validates it so you can pass it directly into `calculate_coverage()`.
|
|
28
49
|
|
|
29
50
|
```ts
|
|
30
51
|
// Read a single JSON or a folder full of JSON files with coverage data
|
|
@@ -47,19 +68,31 @@ for (let file of files) {
|
|
|
47
68
|
}
|
|
48
69
|
```
|
|
49
70
|
|
|
50
|
-
###
|
|
71
|
+
### Coverage API
|
|
72
|
+
|
|
73
|
+
Both Puppeteer and Playwright provide an API to programmatically get the coverage data, allowing you to put that directly into this library. Here is the gist:
|
|
51
74
|
|
|
52
75
|
```ts
|
|
76
|
+
// Start collecting coverage
|
|
77
|
+
await page.coverage.startCSSCoverage()
|
|
78
|
+
// Load the page, do all sorts of interactions to increase coverage, etc.
|
|
79
|
+
await page.goto('http://example.com')
|
|
80
|
+
// Stop the coverage and store the result in a variable to pass along
|
|
81
|
+
let coverage = await page.coverage.stopCSSCoverage()
|
|
82
|
+
|
|
83
|
+
// Now we can process it
|
|
53
84
|
import { calculate_coverage } from '@projectwallace/css-code-coverage'
|
|
54
85
|
|
|
55
|
-
|
|
56
|
-
|
|
86
|
+
function parse_html(html) {
|
|
87
|
+
return new DOMParser().parseFromString(html, 'text/html')
|
|
88
|
+
}
|
|
57
89
|
|
|
58
|
-
|
|
90
|
+
let report = calculcate_coverage(coverage, parse_html)
|
|
91
|
+
```
|
|
59
92
|
|
|
60
93
|
### Optional: coverage from `<style>` blocks
|
|
61
94
|
|
|
62
|
-
|
|
95
|
+
Coverage generators also create coverage ranges for `<style>` blocks in HTML. If this applies to your code you should provide a HTML parser that we use to 'scrape' the HTML in case the browser gives us not just plain CSS contents. Depending on where you run this analysis you can use:
|
|
63
96
|
|
|
64
97
|
1. Browser:
|
|
65
98
|
```ts
|
|
@@ -67,7 +100,7 @@ Covergae generators also create coverage ranges for `<style>` blocks in HTML. If
|
|
|
67
100
|
return new DOMParser().parseFromString(html, 'text/html')
|
|
68
101
|
}
|
|
69
102
|
```
|
|
70
|
-
1. Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example):
|
|
103
|
+
1. Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example, but other parsers could work, too):
|
|
71
104
|
|
|
72
105
|
```ts
|
|
73
106
|
// $ npm install linkedom
|