A Unit Testing Library for SASS
Sassaby is a unit testing library for SASS mixins and functions. It is written in Node to provide a consistent interface with other front-end tests in your system and for easy integration into a build system. Its interface can be used with any Node testing library (Mocha, Jasmine, etc.).
- Installation
- Setup
- Dependencies
- Features
- Rules
- Contributing
- License
Install via npm:
npm install --save-dev sassabySetting up Sassaby is simple with easy integration into your existing Javascript testing library. After installation, simply require it at the top of the file and instantiate a new object with the .sass or .scss file that you want to include. Here is a sample file using Mocha.
var path = require('path');
var Sassaby = require('sassaby');
describe('sample.scss', function() {
var file = path.resolve(__dirname, 'sample.scss');
var sassaby = new Sassaby(file);
describe('appearance', function() {
it('should have a webkit prefixed declaration', function() {
sassaby.includedMixin('appearance').calledWith('button').declares('-webkit-appearance', 'button');
});
});
});Note that the Sassaby constructor takes the absolute path to the SASS file. We recommend using Node's path and __dirname (which gives you the directory of the test file) plus the remaining path here. Also, note that this file must ONLY include SASS function and mixin declarations. Any code that compiles to CSS in this file will cause Sassaby's parsers to give inconsistent results.
We recommend testing SASS files in isolation. However, depending on the setup of your SASS import tree some functions and mixins may rely on externally declared variables, mixins, or functions. In this case, you can pass an options object to the Sassaby constructor with variables and/or dependencies defined. Here is the sample file with these options:
var path = require('path');
var Sassaby = require('sassaby');
describe('sample.scss', function() {
var file = path.resolve(__dirname, 'sample.scss');
var sassaby = new Sassaby(file, {
variables: {
'grid-columns': 12
},
dependencies: [
path.resolve(__dirname, 'need-this-to-compile.scss')
]
});
describe('#appearance', function() {
it('should have a webkit prefixed declaration', function() {
sassaby.includedMixin('appearance').calledWith('button').declares('-webkit-appearance', 'button');
});
});
});variables should be an object with string keys. It will declare each key-value pair as a SASS variable before compiling the given function/mixin.
dependencies should be an array of file paths to be imported into the compiled SASS. We recommend using the same approach (with path and __dirname) that is used with setting the file path.
Sassaby breaks down testable features into four categories:
- Functions
- Standalone Mixins
- Included Mixins
Functions are your typical SASS functions, defined like this:
@function rems($pxsize, $rembase) {
@return ($pxsize/$rembase)+rem;
}Standalone Mixins are mixins that define new rules, like this:
@mixin align-right($label) {
.align-right-#{$label} {
justify-content: flex-end;
}
}Included Mixins are mixins that do not define new rules, just declarations that should be placed into existing rules. For example:
@mixin appearance($value) {
-webkit-appearance: $value;
-moz-appearance: $value;
appearance: $value;
}Each of these categories can be defined by a respective function defined on an instance of Sassaby. For example, you can set up each of them with this syntax:
var sassaby = new Sassaby(filePath);
var testFunction = sassaby.func('rems');
var testStandaloneMixin = sassaby.standaloneMixin('align-right');
var testIncludedMixin = sassaby.includedMixin('appearance');These functions will read the given file (with variables and dependencies if given) and return an object that will takes one of the "called" functions documented below. SASS compilation will occur at this step.
Calls the mixin or function with the given arguments.
sassaby.func('rems').calledWithArgs('32px', '16px');
sassaby.standaloneMixin('align-right').calledWithArgs('md');
sassaby.includedMixin('appearance').calledWithArgs('button')Calls the mixin or function with no arguments.
sassaby.func('rems').called();
sassaby.standaloneMixin('align-right').called();
sassaby.includedMixin('appearance').called();Calls the mixin with a block. This is only available on mixins and the block is to be given as a string without wrapping brackets.
sassaby.standaloneMixin('align-right').calledWithBlock('.test { color: red; }');
sassaby.includedMixin('appearance').calledWithBlock('.test { color: red; }')Calls the mixin with a block and arguments. This is only available on mixins and the block is to be given as a string without wrapping brackets. The block is always the first argument of this function and the mixin arguments will follow.
sassaby.standaloneMixin('align-right').calledWithBlock('.test { color: red; }', true, 1);
sassaby.includedMixin('appearance').calledWithBlock('.test { color: red; }', true, 1)Each of these types has their own set of functions, or rules, that assert certain conditions on the result of the function or mixin. The arguments of these rules are normalized to match the output from the SASS compilation, so it can be formatted however you wish as long as it is compilable SASS.
Asserts that the function output equals a certain value.
sassaby.func('rems').calledWithArgs('32px', '16px').equals('2rem');Assert that the function output does not equal a certain value.
sassaby.func('rems').calledWithArgs('32px', '16px').doesNotEqual('3rem');Assert that the function output equals true.
sassaby.func('returns-true').calledWithArgs(true).isTrue();Assert that the function output equals false.
sassaby.func('returns-false').calledWithArgs(false).isFalse();Assert that the function output is a truthy value in SASS. Keep in mind that this is SASS truthy, not Javascript truthy.
sassaby.func('returns-truthy').calledWithArgs('string').isTruthy();Assert that the function output is a falsy value in SASS. Keep in mind that this is SASS truthy, not Javascript truthy.
sassaby.func('returns-falsy').calledWithArgs(null).isFalsy();Assert that the mixin creates the given selector.
sassaby.standaloneMixin('align-right').calledWithArgs('md').createsSelector('.align-right-md');Assert that the mixin does not create the given selector.
sassaby.standaloneMixin('align-right').calledWithArgs('md').doesNotCreateSelector('.align-right-lg');Assert that the mixin creates a media query with the given string.
sassaby.standaloneMixin('make-button').calledWithArgs('200px').createsMediaQuery('screen and (max-width: 200px)');Assert that the mixin does not create a media query with the given string.
sassaby.standaloneMixin('make-button').calledWithArgs('200px').doesNotCreateMediaQuery('screen and (max-width: 400px)');Assert that the mixin creates a font-face rule.
sassaby.standaloneMixin('make-font-face').calledWithArgs('helvetica').createsFontFace();Assert that the mixin does not create a font-face rule.
sassaby.standaloneMixin('align-right').calledWithArgs('md').doesNotCreateFontFace();Assert that the mixin creates the given number of declarations.
sassaby.standaloneMixin('align-right').calledWithArgs('md').hasNumDeclarations(1);Assert that the mixin makes a declaration of the given rule-property pair.
sassaby.standaloneMixin('align-right').calledWithArgs('md').declares('justify-content', 'flex-end');Assert that the mixin does not make a declaration of the given rule-property pair.
sassaby.standaloneMixin('align-right').calledWithArgs('md').doesNotDeclare('text-align', 'right');Assert that the mixin output equals the given string.
sassaby.standaloneMixin('align-right').calledWithArgs('md').equals('.align-right-md { justify-content: flex-end; }');Assert that the mixin output does not equal the given string.
sassaby.standaloneMixin('align-right').calledWithArgs('md').doesNotEqual('.align-right-lg { justify-content: flex-end; }');Assert that the mixin calls another mixin.
sassaby.standaloneMixin('build-alignments').calledWithArgs('md').calls('align-right(md)');Assert that the mixin does not call another mixin.
sassaby.standaloneMixin('build-alignments').calledWithArgs('md').doesNotCall('align-right(lg)');Assert that the mixin creates the given number of declarations.
sassaby.includedMixin('appearance').calledWithArgs('button').hasNumDeclarations(3);Can be either called with a string as property value or with an Array object.
Called with a String it asserts that the mixin makes a declaration of the given rule-property pair.
sassaby.includedMixin('appearance').calledWithArgs('button').declares('-webkit-appearance', 'button');Called with an Object it asserts that the mixin makes a declaration of the given property with the provided fallback values. E.g. for the mixin:
@mixin font-size($font-size: 1.6) {
font-size: $font-size * 16 + px;
font-size: $font-size + rem;
}
sassaby.includedMixin('font-size').calledWithArgs('2').declares('max-height', ['32px', '2rem']);Assert that the mixin makes a declaration of the given rule-property pair inside the provided selector. E.g. for the mixin:
@mixin clearfix() {
&:before,
&:after {
content: " "; // 1
display: table; // 2
}
&:after {
clear: both;
}
}
sassaby.includedMixin('clearfix').called().declaresInSelector(':before', 'content', " ");
sassaby.includedMixin('clearfix').called().declaresInSelector(':before', 'display', 'table');
sassaby.includedMixin('clearfix').called().declaresInSelector(':after', 'content', " ");
sassaby.includedMixin('clearfix').called().declaresInSelector(':after', 'display', 'table');
sassaby.includedMixin('clearfix').called().declaresInSelector(':after', 'clear', 'both');Assert that the mixin does not make a declaration of the given rule-property pair.
sassaby.includedMixin('appearance').calledWithArgs('button').doesNotDeclare('-o-appearance', 'button');Assert that the mixin output equals the given string.
sassaby.includedMixin('appearance').calledWithArgs('button').equals('-webkit-appearance: button; -moz-appearance: button; appearance: button;');Assert that the mixin output does not equal the given string.
sassaby.includedMixin('appearance').calledWithArgs('button').doesNotEqual('appearance: button;');Assert that the mixin calls another mixin.
sassaby.includedMixin('appearance').calledWithArgs('button').calls('prefixer(button)');Assert that the mixin does not call another mixin.
sassaby.includedMixin('appearance').calledWithArgs('button').doesNotCall('prefixer(-webkit-button)');Often your SASS project will have a single entry point from where all other files are imported. Sassaby exposes two assertion methods on the sassaby object itself to test this. These two methods take the same path that would be included in the @import statement in your SASS file.
Assert that the file imports the given path.
sassaby.imports('variables');Assert that the file does not import the given path.
sassaby.doesNotImport('nope');Pull requests are welcome. If you add functionality, then please add unit tests to cover it. Continuous Integration is handled by Travis.
MIT © Ryan Bahniuk