readme

Author: bartveneman

README.md

@@ -1,3 +1,72 @@
 # CSS Code Coverage
 
 Takes your generated coverage files and turns them into something actually usable. Accepts coverage reports generated by browsers (Edge/Chrome/chromium), Puppeteer, Playwright.
+
+Features include:
+
+- 🤩 Prettifies CSS for easy inspection and updates coverage ranges after prettification
+- 🪄 Marks each line of each CSS file as covered or uncovered
+- 📑 A single stylesheet that's reported over multiple URL's is combined into a single one, coverage ranges merged
+- 🗂️ Creates a report of total line coverage, byte coverage and coverage details per individual stylesheet discovered
+
+## Installation
+
+```sh
+npm install @projectwallace/css-code-coverage
+```
+
+## Usage
+
+### Prerequisites
+
+1. You have collected browser coverage data of your CSS. There are several ways to do this:
+
+   1. in the browser devtools in [Edge](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/coverage/)/[Chrome](https://developer.chrome.com/docs/devtools/coverage/)/chromium
+   1. Via the `coverage.startCSSCoverage()` API that headless browsers like [Playwright](https://playwright.dev/docs/api/class-coverage#coverage-start-css-coverage) or [Puppeteer](https://pptr.dev/api/puppeteer.coverage.startcsscoverage/) provide.
+
+   Either way you end up with one or more JSON files that contain coverage data.
+
+   ```ts
+   // Read a single JSON or a folder full of JSON files with coverage data
+   // Coverage data looks like this:
+   // {
+   //   url: 'https://www.projectwallace.com/style.css',
+   //   text: 'a { color: blue; text-decoration: underline; }', etc.
+   //   ranges: [
+   //     { start: 0, end: 46 }
+   //   ]
+   // }
+   let files = await fs.glob('./css-coverage/**/*.json')
+   let coverage_data = []
+   for (let file of files) {
+   	let json_content = await fs.readFile(file, 'urf-8')
+   	coverage_data.push(JSON.parse(json_content))
+   }
+   ```
+
+1. You 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:
+
+   1. Browser:
+      ```ts
+      function parse_html(html) {
+      	return new DOMParser().parseFromString(html, 'text/html')
+      }
+      ```
+   1. Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example):
+
+      ```ts
+      // $ npm install linkedom
+      import { DOMParser } from 'linkedom'
+
+      function parse_html(html: string) {
+      	return new DOMParser().parseFromString(html, 'text/html')
+      }
+      ```
+
+### Bringing it together
+
+```ts
+import { calculate_coverage } from '@projectwallace/css-code-coverage'
+
+let report = calculcate_coverage(coverage_data, parse_html)
+```

src/index.ts

@@ -24,8 +24,8 @@ export type StylesheetCoverage = CoverageData & {
 
 export type CoverageResult = CoverageData & {
 	total_files_found: number
-	coverage_per_stylesheet: StylesheetCoverage[]
 	total_stylesheets: number
+	coverage_per_stylesheet: StylesheetCoverage[]
 }
 
 /**