@kollorg/illum-corrupti-sapiente NPM

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. The tests are a series of sub-folders in the "test/fixtures" directory that contain an "input" Sass file and an "output" CSS file. Its unit tests then reference a particular folder, compile 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 @kollorg/illum-corrupti-sapiente

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
  └── test_mymodule.scss

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

import path from 'node:path';
import { expect } from 'chai';
import SassyTest from '@kollorg/illum-corrupti-sapiente';

const sassyTest = new SassyTest({
  // Path to the Sass module we are testing and its dependencies.
  loadPaths: [
    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.
  // fixtures: path.join(__dirname, 'fixtures'),
});

describe('@import "mymodule";', function() {
  describe('@function my-modules-function()', function() {
    it('should test an aspect of this function', async function() {
      // Sassy Test's compileFixture() will run a comparison test between the
      // compiled 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
      return sassyTest.compileFixture('my-modules-function')
        .catch(error => {
          // If we expect the comparison test to succeed, we just need to test
          // that no error occurred.
          expect(error).to.not.exist;
        })
        .then(result => {
          // No additional assertions are needed, but we can run other tests
          // here if we desire.
        });
    });

    it('should throw an error in this situation', async function() {
      // Sassy Test's compileFixture() can also test if your module produces an
      // intentional error with Sass' @error directive.
      return sassyTest.compileFixture('my-modules-error')
        .catch(error => {
          // 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.');
        });
    });

    it('should warn in another situation', async function() {
      // Sassy Test's compileFixture() can also test if your module produces an
      // intentional warning message with Sass' @warn directive.
      return sassyTest.compileFixture('my-modules-warn')
        .catch(error => {
          // 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;
        })
        .then(result => {
          // Sassy Test adds two new arrays to sass' result object:
          // result.warn and result.debug are arrays of strings.
          expect(result.warn[0]).to.equal('Some helpful warning from your module.');
        });
    });
  });
});

For more information about configuring a SassyTest object, see the configurePaths() method documentation.

JavaScript Promises

SassyTest's compile(), compileString() and compileFixture() methods return a Promise.

describe('@import "mymodule";', function() {
  describe('@function my-modules-function()', function() {
    it('should test an aspect of this function', function() {
      // Mocha accepts sassyTest's returned Promise.
      return sassyTest.compileFixture('my-modules-function');
    });

    it('should throw an error in this situation', function() {
      return sassyTest.compileFixture('my-modules-error').then(function(result) {
        // If the expected Sass error does not occur, we need to fail the test.
        expect(result).to.not.exist('An error should have occurred');
      }).catch(function(error) {
        expect(error).to.exist;
        expect(error.message).to.include('Some helpful error message from your module.');
      });
    });

    it('should warn in another situation', function() {
      return sassyTest.compileFixture('my-modules-warn').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.