sassy-test

Sassy Test

Sassy Test is a simple helper utility for creating unit tests of Sass modules.

Sassy Test models its testing after the unit tests in LibSass. LibSass has a series of sub-folders in its "test/fixtures" directory that contain an "input" Sass file and an "output" CSS file. Its unit tests then reference a particular folder, render the input.scss and compare the results to the output.css file.

To get started, just install Sassy Test as a development dependency of your Sass module with: npm install --save-dev sassy-test

Sassy Test will work with any Node.js test runner, like mocha or jasmine.

A quick demo of Mocha + Sassy Test

Example project's root directory:

|   # You can put your module's Sass files anywhere.
|   # We use "sass" as an example.
├─┬ sass/
│ └── _mymodule.scss
│   # Mocha prefers your tests to live in a "test" folder.
│   # Sassy Test will automatically find your fixtures if
│   # they are in /test/fixtures, but you can change the
│   # path with configurePaths().
└─┬ test/
  ├─┬ fixtures/
  │ │   # Test fixtures can be deeply nested.
  │ ├─┬ my-modules-function/
  │ │ ├── input.scss
  │ │ └── output.css
  │ ├─┬ my-modules-error/
  │ │ ├── input.scss
  │ │ └── output.css
  │ └─┬ my-modules-warn/
  │   ├── input.scss
  │   └── output.css
  ├── helper.js
  └── test_mymodule.scss

With mocha, we can place a call to before() in the root of any test file and it will be run once before all the other tests in every test_*.js file. We can also require() files and assign them to the global object to make them available to all test_*.js files. A file called helper.js can be used to set up our mocha global requires and before():

'use strict';

// Globals for all test_*.js files.
global.path = require('path');
global.expect = require('chai').expect;
global.SassyTest = require('sassy-test');
global.sassyTest = new SassyTest();

// This before() is run before any test_*.js file.
before(function(done) {
  sassyTest.configurePaths({
    // Path to the Sass module we are testing and its dependencies.
    includePaths: [
      path.join(__dirname, '../sass'),
      path.join(__dirname, '../node_modules/breakpoint-sass/stylesheets')
    ]
    // Since our fixtures are in test/fixtures, we don't need to override
    // the default value by setting the "fixtures" path here.
  });
  done();
});

For more information, see the configurePaths() documentation.

Then in our test file, test_mymodule.js, we can use sassyTest to simplify our tests:

describe('@import "mymodule";', function() {
  describe('@function my-modules-function()', function() {
    it('should test an aspect of this function', function(done) {
      // Sassy Test's renderFixture() will run a comparison test between the
      // rendered input.scss and the output.css found in the fixtures
      // sub-directory specified in its first parameter, in this case:
      // test/fixtures/my-modules-function
      sassyTest.renderFixture('my-modules-function', {}, function(error, result) {
        // If we expect the comparison test to succeed, we just need to test
        // that no error occurred and then done(), but we can run other tests
        // here if we desire.
        expect(error).to.not.exist;
        expect(result.css).to.expect('.some-valid-css {border: 0}');
        done();
      });
    });

    it('should throw an error in this situation', function(done) {
      // Sassy Test's renderFixture() can also test if your module produces an
      // intentional error with Sass' @error directive.
      sassyTest.renderFixture('my-modules-error', {}, function(error, result) {
        // If the Sass in test/fixtures/my-modules-error/input.scss triggers an
        // @error in your module, you should expect the error object to exist
        // and to contain the error message from your module.
        expect(error).to.exist;
        expect(error.message).to.equal('Some helpful error message from your module.');
        done();
      });
    });

    it('should warn in another situation', function(done) {
      // Sassy Test's renderFixture() can also test if your module produces an
      // intentional warning message with Sass' @warn directive.
      sassyTest.renderFixture('my-modules-warn', {}, function(error, result) {
        // If the Sass in test/fixtures/my-modules-warn/input.scss triggers a
        // @warn in your module, you should expect the result object to exist
        // and to contain the warn message from your module.
        expect(error).to.not.exist;
        // Sassy Test adds two new arrays to node-sass' result object:
        // result.warn and result.debug are arrays of strings.
        expect(result.warn[0]).to.equal('Some helpful warning from your module.');
        done();
      });
    });
  });
});

SassyTest's render() and renderFixture() methods will return a Promise if you don't provide a callback:

describe('@import "mymodule";', function() {
  describe('@function my-modules-function()', function() {
    it('should test an aspect of this function', function() {
      return sassyTest.renderFixture('my-modules-function', {}).catch(function(error) {
        expect(error).to.not.exist;
      }).then(function(result) {
        expect(result.css).to.expect('.some-valid-css {border: 0}');
      });
    });

    it('should throw an error in this situation', function() {
      return sassyTest.renderFixture('my-modules-error', {}).then(function(result) {
        expect(result).to.not.exist;
      }).catch(function(error) {
        expect(error).to.exist;
        expect(error.message).to.equal('Some helpful error message from your module.');
      });
    });

    it('should warn in another situation', function() {
      return sassyTest.renderFixture('my-modules-warn', {}).catch(function(error) {
        expect(error).to.not.exist;
      }).then(function(result) {
        expect(result.warn[0]).to.equal('Some helpful warning from your module.');
      });
    });
  });
});

Full documentation of Sassy Test’s JavaScript API is available online.

Development

Forking, hacking, and tearing apart of this software is welcome! It's still very simple and could use additional features and conveniences.

After you've cloned this repository, run npm install and then you'll be able to run the module's mocha and eslint tests with npm test.

Contributors

None but me yet. All are welcome! https://github.com/JohnAlbin/sassy-test/graphs/contributors