True
Verb
- To make true; shape, adjust, place, etc., exactly or accurately: True the wheels of a bicycle after striking a pothole.
- To make even, symmetrical, level, etc. (often followed by up): True up the sides of a door.
- To test your Sass code; debug, perfect, etc. (often using True): True your sweet plugin before you deploy.
Install
in command line:
# ruby gem
gem install true
# bower package
bower install true
# npm module
npm install sass-true
Usage
With any Sass compiler
@import "true";
@include test-module('Utilities') {
// Testing Functions
@include test('Map Add [function]') {
$base: (one: 1, two: 1, three: 1);
$add: (one: 1, two: 2, three: -1);
$test: map-add($base, $add);
$expect: (one: 2, two: 3, three: 0);
@include assert-equal($test, $expect,
'Returns the sum of two numeric maps');
}
// Testing Mixins
@include test('Font Size [mixin]') {
@include assert('Outputs a font size and line height based on keyword.') {
@include output {
@include font-size(large);
}
@include expect {
font-size: 2rem;
line-height: 3rem;
}
}
}
}
// Optionally show summary report in CSS and/or the command line:
// - If you use Mocha, reporting to the command line is automatic.
// - if you use true-cli, report(terminal) is required for output.
@include report;
Note: Function unit-tests work across the board, but testing mixins can be a bit more complex. At this point, only Mocha is able to compare/report the results of mixin tests. Without using Mocha, you can test any mixin, but you will have to compare the expected and actual results manually in the output code. Version control can make that much easier than it sounds.
With node-sass and Mocha (or other JS test runners)
Install
true
via npm (npm install sass-true
).Write some Sass tests in
test/test.scss
(see above).Write a shim JS test file in
test/test_sass.js
:
var path = require('path');
var sassTrue = require('sass-true');
var sassFile = path.join(__dirname, 'test.scss');
sassTrue.runSass({file: sassFile}, describe, it);
- Run Mocha, and see your Sass tests reported as individual test results.
You can call runSass
more than once, if you have multiple Sass test files you
want to run separately.
The first argument to runSass
accepts the same options that node-sass'
renderSync
function accepts. The only modification runSass
makes is to add
True's sass path to the includePaths
option, so @import 'true';
works in
your Sass test file.
Any other JS test runner with equivalents to Mocha's describe
and it
should
be usable in the same way; just pass your test runner's describe
and it
equivalents into runSass
.
If True's Mocha plugin can't parse the CSS output from True, it'll give you
some context lines of CSS as part of the error message. This context will
likely be helpful in understanding the parse failure. By default it provides up
to 10 lines of context; if you need more, you can provide a numeric fourth
argument to runSass
, the maximum number of context lines to provide.
With Grunt...
Run Mocha using the Grunt task supplied by grunt-mocha-cli
Install grunt-mocha-cli
:
npm install grunt-mocha-cli --save-dev
Configure task:
grunt.loadNpmTasks('grunt-mocha');
mochacli: {
all: ['test/test_sass.js']
},
Run tests:
grunt mochacli
With ruby-sass on the command line
true-cli [options] PATH
Options:
-s
silent-c
config file-d
debug config file settings
Config file (optional):
options:
color: true # enables colored output
# require ruby sass extension libraries
require:
- "compass"
- "serialy/sassy"
default location: test/true.yml
Settings
There is only one setting:
$true-terminal-output
toggles output to the terminal on or off.
true
will show detailed information on failing assertions. This is the default, and best for usingtrue-cli
.false
to turn off all terminal output.