or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

css-output-testing.mderror-handling.mdindex.mdjavascript-integration.mdtest-structure.mdvalue-assertions.md
tile.json

tessl/npm-sass-true

Unit testing framework for Sass code with JavaScript test runner integration

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/sass-true@9.0.x

To install, run

npx @tessl/cli install tessl/npm-sass-true@9.0.0

index.mddocs/

Sass True

Sass True is a comprehensive unit testing framework specifically designed for Sass code. It enables developers to write and run tests in plain Sass that can be compiled using Dart Sass, supports both traditional test-module/test syntax and modern describe/it patterns, and provides seamless integration with JavaScript test runners like Mocha and Jest for enhanced reporting and CI/CD workflows.

Package Information

  • Package Name: sass-true
  • Package Type: npm
  • Language: Sass/SCSS with JavaScript/TypeScript integration
  • Installation: npm install --save-dev sass-true

Core Imports

Sass Imports

Modern @use syntax:

@use 'pkg:sass-true' as *;

If not using the Sass Node.js package importer:

@use '../node_modules/sass-true' as *;

For JavaScript test runner integration:

@use 'true' as *;

Legacy @import syntax (preserves true-* prefixes):

@import '../node_modules/sass-true/sass/true';

JavaScript Imports

const sassTrue = require('sass-true');
// or
import * as sassTrue from 'sass-true';

Basic Usage

Sass Testing

@use 'pkg:sass-true' as *;

// Using test-module/test syntax
@include test-module('Math Functions') {
  @include test('Addition works correctly') {
    @include assert-equal(2 + 2, 4);
  }
  
  @include test('CSS output is correct') {
    @include assert {
      @include output {
        width: calc(100% - 20px);
      }
      @include expect {
        width: calc(100% - 20px);
      }
    }
  }
}

// Using describe/it syntax (equivalent)
@include describe('Math Functions') {
  @include it('Addition works correctly') {
    @include assert-equal(2 + 2, 4);
  }
}

// Generate final report
@include report;

JavaScript Test Runner Integration

const path = require('node:path');
const sassTrue = require('sass-true');

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

Architecture

Sass True is built around several key components:

  • Testing Structure: Hierarchical test organization with modules/describe and tests/it for BDD-style testing
  • Dual Assertion System: Separate APIs for testing Sass values and CSS output
  • Error Handling: Sophisticated error catching and reporting system with optional compilation continuation
  • Reporting Engine: Comprehensive test result reporting to both CSS and terminal
  • JavaScript Bridge: CSS parsing and test runner integration for automated testing workflows
  • Configuration System: Flexible settings for terminal output and error behavior

Capabilities

Test Organization

Hierarchical test structure using either traditional or BDD naming conventions. Supports nested modules for complex test organization.

@mixin test-module($name);
@mixin describe($name);  // alias for test-module
@mixin test($name);
@mixin it($name);       // alias for test

Test Structure

Value Assertions

Testing Sass function outputs, variable values, and return types with comprehensive equality and truthiness checking.

@mixin assert-equal($assert, $expected, $description: null, $inspect: false);
@mixin is-equal($assert, $expected, $description: null, $inspect: false);     // alias
@mixin assert-true($assert, $description: null);
@mixin is-truthy($assert, $description: null);                              // alias
@mixin assert-false($assert, $description: null);
@mixin is-falsy($assert, $description: null);                               // alias
@mixin assert-unequal($assert, $expected, $description: null, $inspect: false);
@mixin not-equal($assert, $expected, $description: null, $inspect: false);  // alias

Value Assertions

CSS Output Testing

Testing compiled CSS output from mixins and complex Sass expressions, with exact matching and subset matching capabilities.

@mixin assert($description: null);
@mixin output($selector: true);
@mixin expect($selector: true);
@mixin contains($selector: true);
@mixin contains-string($string-to-find);

CSS Output Testing

Error Handling

Sophisticated error catching system allowing tests to validate error conditions without stopping compilation.

@function error($message, $source: null, $catch: $catch-errors);
@mixin error($message, $source: null, $catch: $catch-errors);

Error Handling

Test Reporting

Comprehensive test result reporting to both CSS comments and terminal output, with optional compilation failure on test failures.

@mixin report($terminal: $terminal-output, $fail-on-error: false, $results: $results, $stats: $stats);

JavaScript Integration

Complete integration with JavaScript/TypeScript test runners, providing automated CSS parsing and test result reporting.

function runSass(
  trueOptions: TrueOptions,
  src: string,
  sassOptions?: any
): void;

function parse(rawCss: string, contextLines?: number): Module[];

function formatFailureMessage(assertion: Assertion): string;

interface TrueOptions {
  describe: (description: string, fn: () => void) => void;
  it: (description: string, fn: () => void) => void;
  sass?: any;
  sourceType?: 'path' | 'string';
  contextLines?: number;
}

JavaScript Integration

Configuration

Global Settings

$terminal-output: true !default;  // Show terminal output when compiling manually
$catch-errors: false !default;    // Catch errors without stopping compilation ('warn' also shows warnings)

Legacy Settings (for @import syntax):

$true-terminal-output: true !default;  // Legacy prefixed version for @import syntax

Types

// Sass doesn't have explicit types, but these are the expected value types:
// $name: string - Test/module names and descriptions
// $assert, $expected: any - Values to test (numbers, strings, lists, maps, etc.)  
// $description: string | null - Optional assertion descriptions
// $inspect: bool - Whether to compare inspected (string) values
// $selector: bool - Whether to wrap CSS output in test selectors
// $catch: bool | 'warn' - Error catching behavior
// JavaScript integration types
interface Assertion {
  description: string;
  assertionType?: string;
  output?: string;
  expected?: string;
  details?: string;
  passed?: boolean;
}

interface Test {
  test: string;
  assertions: Assertion[];
}

interface Module {
  module: string;
  tests?: Test[];
  modules?: Module[];
}