Css-specs

Test CSS programmatically

What ?

It's a tool that reports the differences from a very big stylesheet based on previous versions. It's based on selector and rule specifications that are being saved automatically from any given local html.

Why ?

This tool has emerged from the frustration of manually testing the result of a very large css codebase. Most likely emerging from a compiled language such as SASS, LESS or custom css builder.

It can be usefull to

• make sure the css rules realy apply or make sense
• detect unwanted changes from an other rule
• deeply report the difference between two states

Features

• Create a snapshot from existing compiled style
• Compare compiled styles to last valid snapshot for that css build
• Report differences displaying actual and expected css values
• JSON format output (can be converted to XML for jenkins report and such)
• can be pointed to any html template (remote or local)
• can load any stylesheet file that is local to your computer
• load remote stylesheets if present in the template or the remote server

Pictures

How to use

add in you project

npm install --save css-specs

create a config file named css-specs.conf.js

module.exports = {
  prettySnapshots: false,
  snapshotPath: 'snapshots',
  port: 5000
};

When you require it, you have a few methods exposed to handle different use cases.

var cs = require('..'); // that's our css-specs lib
var fs = require('fs');
 
var cssBuildPath = 'example.css'; // can be any local path
var url = './example.html'; // can be external urls as well
 
// get css as a string
var css = fs.readFileSync(cssBuildPath, 'utf-8');

.renderer(url, css, callback) is used to render the current page with the specified style and return computed values.

cs.renderer(url, css, function(result) {
  /* do something with the results... */
});

.snapshot.save(cssBuildPath, result.styles) is used to save a result after being rendered.

cs.renderer(url, css, function(result) {
  cs.snapshot.save(cssBuildPath, result.styles);
});

.comparator.compare(cssBuildPath, result.styles) is used to compare two different results.

cs.renderer(url, cssToCheck, function(result) {
  var snapshot = require(cs.utils.snapshotPath(cssBuildPath));
  var diff = cs.comparator.compare(snapshot, result.styles);
});

Lastlyl, .reporter(diffTree) is used to output differences in the console in a nice way

cs.renderer(url, cssToCheck, function(result) {
  var snapshot = require(cs.utils.snapshotPath(cssBuildPath));
  var diff = cs.comparator.compare(snapshot, result.styles);
  cs.reporter(diff); // <------
});

Refer to the example that you might run with node index.js for "real-life" usage.

API

We encourage reading the source code from the entry point and the config defaults