Narcoleptic Pasta Manufacturer

    sassaby

    2.1.1 • Public • Published

    Sassaby

    A Unit Testing Library for SASS

    Sassaby Logo

    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

    Install via npm:

    npm install --save-dev sassaby

    Setup

    Setting 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.

    Dependencies

    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.

    Features

    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.

    calledWithArgs

    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')

    called

    Calls the mixin or function with no arguments.

    sassaby.func('rems').called();
    sassaby.standaloneMixin('align-right').called();
    sassaby.includedMixin('appearance').called();

    calledWithBlock

    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; }')

    calledWithBlockAndArgs

    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)

    Rules

    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.

    Function Rules

    equals

    Asserts that the function output equals a certain value.

    sassaby.func('rems').calledWithArgs('32px', '16px').equals('2rem');

    doesNotEqual

    Assert that the function output does not equal a certain value.

    sassaby.func('rems').calledWithArgs('32px', '16px').doesNotEqual('3rem');

    isTrue

    Assert that the function output equals true.

    sassaby.func('returns-true').calledWithArgs(true).isTrue();

    isFalse

    Assert that the function output equals false.

    sassaby.func('returns-false').calledWithArgs(false).isFalse();

    isTruthy

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

    isFalsy

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

    Standalone Mixin Rules

    createsSelector

    Assert that the mixin creates the given selector.

    sassaby.standaloneMixin('align-right').calledWithArgs('md').createsSelector('.align-right-md');

    doesNotCreateSelector

    Assert that the mixin does not create the given selector.

    sassaby.standaloneMixin('align-right').calledWithArgs('md').doesNotCreateSelector('.align-right-lg');

    createsMediaQuery

    Assert that the mixin creates a media query with the given string.

    sassaby.standaloneMixin('make-button').calledWithArgs('200px').createsMediaQuery('screen and (max-width: 200px)');

    doesNotCreateMediaQuery

    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)');

    createsFontFace

    Assert that the mixin creates a font-face rule.

    sassaby.standaloneMixin('make-font-face').calledWithArgs('helvetica').createsFontFace();

    doesNotCreateFontFace

    Assert that the mixin does not create a font-face rule.

    sassaby.standaloneMixin('align-right').calledWithArgs('md').doesNotCreateFontFace();

    hasNumDeclarations

    Assert that the mixin creates the given number of declarations.

    sassaby.standaloneMixin('align-right').calledWithArgs('md').hasNumDeclarations(1);

    declares

    Assert that the mixin makes a declaration of the given rule-property pair.

    sassaby.standaloneMixin('align-right').calledWithArgs('md').declares('justify-content', 'flex-end');

    doesNotDeclare

    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');

    equals

    Assert that the mixin output equals the given string.

    sassaby.standaloneMixin('align-right').calledWithArgs('md').equals('.align-right-md { justify-content: flex-end; }');

    doesNotEqual

    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; }');

    calls

    Assert that the mixin calls another mixin.

    sassaby.standaloneMixin('build-alignments').calledWithArgs('md').calls('align-right(md)');

    doesNotCall

    Assert that the mixin does not call another mixin.

    sassaby.standaloneMixin('build-alignments').calledWithArgs('md').doesNotCall('align-right(lg)');

    Included Mixin Rules

    hasNumDeclarations

    Assert that the mixin creates the given number of declarations.

    sassaby.includedMixin('appearance').calledWithArgs('button').hasNumDeclarations(3);

    declares

    Assert that the mixin makes a declaration of the given rule-property pair.

    sassaby.includedMixin('appearance').calledWithArgs('button').declares('-webkit-appearance', 'button');

    doesNotDeclare

    Assert that the mixin does not make a declaration of the given rule-property pair.

    sassaby.includedMixin('appearance').calledWithArgs('button').doesNotDeclare('-o-appearance', 'button');

    equals

    Assert that the mixin output equals the given string.

    sassaby.includedMixin('appearance').calledWithArgs('button').equals('-webkit-appearance: button; -moz-appearance: button; appearance: button;');

    doesNotEqual

    Assert that the mixin output does not equal the given string.

    sassaby.includedMixin('appearance').calledWithArgs('button').doesNotEqual('appearance: button;');

    calls

    Assert that the mixin calls another mixin.

    sassaby.includedMixin('appearance').calledWithArgs('button').calls('prefixer(button)');

    doesNotCall

    Assert that the mixin does not call another mixin.

    sassaby.includedMixin('appearance').calledWithArgs('button').doesNotCall('prefixer(-webkit-button)');

    Testing Imports

    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.

    imports

    Assert that the file imports the given path.

    sassaby.imports('variables');

    doesNotImport

    Assert that the file does not import the given path.

    sassaby.imports('nope');

    Contributing

    Pull requests are welcome. If you add functionality, then please add unit tests to cover it. Continuous Integration is handled by Travis.

    License

    MIT © Ryan Bahniuk

    Install

    npm i sassaby

    DownloadsWeekly Downloads

    15

    Version

    2.1.1

    License

    MIT

    Last publish

    Collaborators

    • ryanbahniuk