version 0.04


    css-coverage style.css index.html second.html
        Unmatched selectors (3):
            div.form-actions button:first-child
            ul.attn li form textarea

    my $coverage = CSS::Coverage->new(
        css       => $css_file,
        documents => \@html_files,

    my $report = $coverage->check;

    print for $report->unmatched_selectors;


Every CSS rule in your stylesheets have a cost. Browser must parse them and apply them to your document. Your maintainers have to understand what each rule is doing. If a CSS rule doesn't appear to match any part of the document, maintainers wonder "is that intentional, or just a typo?"

So it is useful excise unused CSS rules. Unfortunately it is very tedious to manually confirm whether a particular CSS selector matches any of your documents. There are browser-based tools, like one that ships in Chrome, that do this for you. However, they do not presently check multiple pages. Browser tools are also not great for running in a continuous integration environment.

This module and its associated css-coverage script provide a good first stab at paring down the list of rules to manually check.


Modern HTML pages are living, breathing, dynamic documents. CSS::Coverage can only statically check whether a CSS selector matches an HTML document. So if you manipulate the DOM in JavaScript, CSS::Coverage may report false positives. There's certainly a point where CSS::Coverage provides diminishing returns if your page is very JavaScript-heavy. But for static, or mostly-static, pages, CSS::Coverage should be useful.

If you know that a particular rule only matches when JavaScript runs, you can add a comment like this either inside or before that CSS rule:

    a.clicked {
        /* coverage: dynamic */
        text-decoration: line-through;

    /* coverage: dynamic */
    a.clicked {
        text-decoration: line-through;

Either directive will cause CSS::Coverage to skip that rule entirely.


CSS::Coverage - Confirm that your CSS matches your DOM


version 0.04


css (Str|ScalarRef)

If given a string, css is treated as a filename. If given as a scalar reference, css is treated as CSS code.

documents (ArrayRef[Str|ScalarRef])

A list of HTML documents. For each document, strings are treated as filenames; scalar reference as raw HTML code.



Runs a coverage check of the given CSS against the given documents. Returns a CSS::Coverage::Report object.


Shawn M Moore <>


This software is copyright (c) 2013 by Infinity Interactive, Inc..

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.