CSS Code Coverage

> [!WARNING]
> This is a very experimental approach to calculating CSS Code Coverage and currently very much a work in progress.

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

`ts
import { calculate_coverage } from '@projectwallace/css-code-coverage'

let report = await calculcate_coverage(coverage_data)

// => report.line_coverage_ratio: 0.80
// => report.byte_coverage_ratio: 0.85
// => report.total_lines: 1000
// => report.covered_lines: 800
// etc.
`

See src/index.ts for the data that's returned.

Collecting CSS Coverage

There are two principal ways of collecting CSS Coverage data:

$3

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:

`ts
// Start collecting coverage
await page.coverage.startCSSCoverage()
// Load the page, do all sorts of interactions to increase coverage, etc.
await page.goto('http://example.com')
// Stop the coverage and store the result in a variable to pass along
let coverage = await page.coverage.stopCSSCoverage()

// Now we can process it
import { calculate_coverage } from '@projectwallace/css-code-coverage'

let report = calculcate_coverage(coverage)
`

$3

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:

- Collect coverage in Microsoft Edge: https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/coverage/
- Collect coverage in Google Chrome: https://developer.chrome.com/docs/devtools/coverage/

Additionally, DevTools Tips writes about it in their explainer.

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().

`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 }
// ]
// }
import { parse_coverage } from '@projectwallace/css-code-coverage'

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(...parse_coverage(json_content))
}
`

CLI

Use the CLI tool (css-coverage) to check if coverage meets minimum requirements, globally and/or per file.

`sh
css-coverage --coverage-dir=