• Stars
    star
    683
  • Rank 66,158 (Top 2 %)
  • Language SCSS
  • License
    BSD 3-Clause "New...
  • Created over 11 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Sass unit tests

True

License

  1. To make true; shape, adjust, place, etc., exactly or accurately:

    True the wheels of a bicycle after striking a pothole.

  2. To make even, symmetrical, level, etc. (often followed by up):

    True up the sides of a door.

  3. To test your Sass code; debug, perfect, etc. (often using True):

    True your sweet plugin before you deploy.

True is a unit-testing tool for Sass code. All of the tests are written in plain Sass, and can be compiled using Dart Sass – but we also provide integration with JavaScript test runners (e.g. Mocha or Jest), for extra features and improved reporting.

Install

In command line:

npm install --save-dev sass-true

Import in your test directory, like any other Sass file:

@use 'true' as *;

Depending on your setup, you may need to include the full path name:

// This is only an example, your path may be different
@use '../node_modules/sass-true' as *;

One Setting

$terminal-output (boolean), defaults to true

  • true will show detailed information in the terminal for debugging failed assertions or reporting final results. This is the default, and best for compiling without a JavaScript test runner.
  • false will turn off all terminal output from Sass, though Mocha/Jest will continue to use the terminal for reporting.

If you are still using @import rather than @use, there is an import path available - which retains the legacy prefixed $true-terminal-output variable name:

// Your path may be different
@import '../node_modules/sass-true/sass/true';

Usage

True is based on common JS-testing patterns, allowing both a test-module/test syntax, and the newer describe/it for defining the structure:

@include test-module('Zip [function]') {
  @include test('Zips multiple lists into a single multi-dimensional list') {
    // Assert the expected results
    @include assert-equal(zip(a b c, 1 2 3), (a 1, b 2, c 3));
  }
}

This is the same as…

@include describe('Zip [function]') {
  @include it('Zips multiple lists into a single multi-dimensional list') {
    // Assert the expected results
    @include assert-equal(zip(a b c, 1 2 3), (a 1, b 2, c 3));
  }
}

Sass is able to compare values internally, meaning function-output and variable values can easily be compared and reported during Sass compilation.

CSS output tests, on the other hand, have to be compared after compilation is complete. You can do that by hand if you want (git diff is helpful for noticing changes), or you can use a test runner such as Mocha or Jest.

Output tests fit the same structure, but assertions take a slightly different form, with an outer assert mixin, and a matching pair of output and expect to contain the output-values.

// Test CSS output from mixins
@include it('Outputs a font size and line height based on keyword') {
  @include assert {
    @include output {
      @include font-size('large');
    }

    @include expect {
      font-size: 2rem;
      line-height: 3rem;
    }
  }
}

You can optionally show a summary report in CSS and/or the command line, after the tests have completed:

@include report;

See the full documentation online for more details. See CHANGELOG.md when upgrading from an older version of True.

Using Mocha, Jest, or other JS test runners

  1. Install true via npm:

    npm install --save-dev sass-true
  2. [Optional] Install sass (Dart Sass), if not already installed.

    npm install --save-dev sass
  3. Write some Sass tests in test/test.scss (see above).

  4. Write a shim JS test file in test/sass.test.js:

    const path = require('path');
    const sassTrue = require('sass-true');
    
    const sassFile = path.join(__dirname, 'test.scss');
    sassTrue.runSass({ describe, it }, sassFile);
  5. Run Mocha/Jest, and see your Sass tests reported in the command line.

Note: Because of differences between Jest globals and Node globals, Dart Sass often errors when trying to compile in a Jest environment (e.g. J.getInterceptor$ax(...).map$1$1 is not a function). This can usually be fixed by installing jest-environment-node-single-context and setting testEnvironment: 'jest-environment-node-single-context' in jest.config.js. See possible related issues.

Note: Jest does not watch for changes in Sass files by default. To use jest --watch with True, add "scss" to your moduleFileExtensions setting.

You can call runSass more than once, if you have multiple Sass test files you want to run separately.

The first argument is an object with required describe and it options, and optional contextLines and sourceType options.

Any JS test runner with equivalents to Mocha's or Jest's describe and it should be usable in the same way: just pass your test runner's describe and it equivalents in the first argument to runSass.

If True can't parse the CSS output, 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 contextLines option: the maximum number of context lines to provide.

The second argument is a string representing either the path to a source Sass file (passed through to Sass' compile function), or a string of source Sass (passed through to Sass' compileString function). By default it is expected to be a path, and sass.compile is used -- to pass in a source string (and use sass.compileString), add sourceType: 'string' to your options passed in as the first argument to runSass.

The third (optional) argument to runSass accepts the same options that Sass' compile or compileString expect, and these are passed directly through to Sass. The only modification runSass makes is to add True's sass path to the loadPaths option, so @use 'true'; works in your Sass test file.

Note: True requires the default Sass 'expanded' output style, and will not work if { style: 'compressed' } is used in the third argument to runSass.

Custom Importers

If you use Webpack's tilde notation, like @use '~accoutrement/sass/tools', you'll need to tell runSass how to handle that. That will require writing a custom importer and passing it into the configuration for runSass:

const path = require('path');
const { pathToFileURL } = require('url');

const sassTrue = require('sass-true');

const importers = [
  {
    findFileUrl(url) {
      if (!url.startsWith('~')) {
        return null;
      }
      return new URL(
        pathToFileURL(path.resolve('node_modules', url.substring(1))),
      );
    },
  },
];

const sassFile = path.join(__dirname, 'test.scss');
sassTrue.runSass({ describe, it }, sassFile, { importers });

More Repositories

1

susy

Pre-grid responsive layout toolkit for Sass, now deprecated
SCSS
3,868
star
2

popover-polyfill

Polyfills the HTML popover attribute and showPopover/hidePopover/togglePopover methods onto HTMLElement, as well as the popovertarget and popovertargetaction attributes on <button> elements.
TypeScript
255
star
3

css-anchor-positioning

Polyfill for CSS Anchor Positioning
TypeScript
248
star
4

sassdoc-theme-herman

An Odd SassDoc theme.
JavaScript
117
star
5

cascading-color-system

CSS Custom Property color-theming
SCSS
71
star
6

susysite

Source for the new susy.oddbird.net
CSS
59
star
7

css-toggles

CSS Toggles demo and polyfill
JavaScript
58
star
8

css-sandbox

A place to draft & experiment with CSS proposals
Nunjucks
53
star
9

accoutrement

Combined Sass Accoutrement tools, with option for individual module imports
SCSS
36
star
10

accoutrement-color

Color helpers
CSS
32
star
11

oddcontrast

Svelte
28
star
12

blend

More color options for sass…
SCSS
26
star
13

show-when

An element that shows or hides based on provided conditions
JavaScript
22
star
14

slide-deck

Web presentations, as a self-contained web component
JavaScript
20
star
15

odd-browser

A place to explore ideas towards a site-building & networking browser
17
star
16

oddsite

⛔️ DEPRECATED: Old (unused) OddBird site
HTML
17
star
17

sliiides

An 11ty attempt at web presentations
Nunjucks
17
star
18

sass-json-export

JSON exporter for Sass. Based on SassyJSON, by Kitty Giraudel.
SCSS
12
star
19

vuefinder

mia-style slideshows with nuxt
Vue
11
star
20

portfoliyo

A communication tool for teachers and parents
Python
11
star
21

accoutrement-scale

Size and scale helpers for typography and layout
CSS
9
star
22

accoutrement-init

browser normalization and baseline defaults
CSS
6
star
23

greenmud

into the green green mud
JavaScript
6
star
24

accoutrement-maps

Sass map helpers
CSS
5
star
25

oddleventy

Official OddBird Site
Nunjucks
5
star
26

source-element

An exploratory Web Component to conditionally load one of several scripts based on user and browser settings.
JavaScript
4
star
27

PyFly

Python
3
star
28

mlt

Python
3
star
29

polyfill-template

TypeScript
3
star
30

cascade-layers-polyfill-demo

HTML
3
star
31

portfoliyo-landing

A landing page for the Portfoliyo project
JavaScript
2
star
32

accoutrement-type

Font helpers
CSS
2
star
33

susy.oddbird.net

New home for the Susy website
CSS
2
star
34

mozdemos

Demos for Mozilla Developer Channel – https://youtube.com/MozillaDeveloper
HTML
2
star
35

knet

Collecting stories of inspiration for teachers
Python
2
star
36

start-testing-preso

A talk on testing for PyCon US 2013
JavaScript
2
star
37

buntpress

PHP
1
star
38

set-your-code-free-preso

A presentation by Carl Meyer for PyCon 2014
CSS
1
star
39

rectangles

Vue
1
star
40

mahjongg

Concise scoring summary for Classical European style mahjongg
Ruby
1
star
41

project-templates

JavaScript
1
star
42

accoutrement-layout

Layout helpers in Sass
CSS
1
star
43

herman-test-project

a test project for sassdoc-theme-herman
CSS
1
star
44

bugdash

A "release readiness" and work prioritization dashboard for Bugzilla users.
JavaScript
1
star
45

accoutrement-queries

Media-query helpers
CSS
1
star
46

oddtools

project management tools for oddbird
JavaScript
1
star
47

advanced-python-preso

A presentation by Carl Meyer for ConFoo 2014, on advanced Python techniques.
CSS
1
star
48

sass-colors-sample

Sample code for implementing support of CSS color spaces in Sass
SCSS
1
star
49

accoutrement-reset

Reset helpers
CSS
1
star
50

odddocker

A base Docker image for OddBird web projects
Dockerfile
1
star