tessl/npm-sass-true

Unit testing framework for Sass code with JavaScript test runner integration

—

Pending

Overview

Eval results

Files

Test Structure

Name: tessl/npm-sass-true
Author: tessl

Hierarchical test organization system supporting both traditional and BDD naming conventions with nested module support for complex test suites.

Capabilities

Module Organization

Groups related tests together with optional nesting for complex test organization.

/**
 * Creates a test module for grouping related tests and sub-modules
 * @param $name - Name of the test module
 * @content Include tests and sub-modules within this module
 */
@mixin test-module($name);

/**
 * BDD-style alias for test-module
 * @param $name - Name of the module/feature being described  
 * @content Include tests and sub-modules within this describe block
 */
@mixin describe($name);

Usage Examples:

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

// Traditional syntax
@include test-module('Math Utilities') {
  @include test-module('Addition Functions') {
    @include test('adds positive numbers') {
      @include assert-equal(add(2, 3), 5);
    }
    
    @include test('adds negative numbers') {
      @include assert-equal(add(-2, -3), -5);
    }
  }
  
  @include test-module('Subtraction Functions') {
    @include test('subtracts correctly') {
      @include assert-equal(subtract(5, 3), 2);
    }
  }
}

// BDD syntax (equivalent)
@include describe('Math Utilities') {
  @include describe('Addition Functions') {
    @include it('adds positive numbers') {
      @include assert-equal(add(2, 3), 5);
    }
  }
}

Test Definition

Defines individual test cases containing one or more assertions.

/**
 * Creates a test case containing related assertions
 * @param $name - Description of what is being tested
 * @content Include assertions that validate the behavior being tested
 */
@mixin test($name);

/**
 * BDD-style alias for test
 * @param $name - Description of the behavior being tested
 * @content Include assertions that validate the expected behavior
 */
@mixin it($name);

Usage Examples:

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

@include test-module('String Functions') {
  @include test('capitalizes first letter correctly') {
    @include assert-equal(capitalize('hello'), 'Hello');
    @include assert-equal(capitalize('WORLD'), 'WORLD');
    @include assert-equal(capitalize(''), '');
  }
  
  @include test('handles edge cases') {
    @include assert-equal(capitalize(null), null);
    @include assert-equal(capitalize(123), 123);
  }
}

// BDD equivalent
@include describe('String Functions') {
  @include it('capitalizes first letter correctly') {
    @include assert-equal(capitalize('hello'), 'Hello');
  }
  
  @include it('handles edge cases') {
    @include assert-equal(capitalize(null), null);
  }
}

Nested Organization

Modules can be nested to any depth for organizing complex test suites.

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

@include describe('Component Library') {
  @include describe('Layout Components') {
    @include describe('Grid System') {
      @include describe('Grid Container') {
        @include it('sets correct container width') {
          @include assert-equal(grid-container-width(), 1200px);
        }
      }
      
      @include describe('Grid Columns') {
        @include it('calculates column width correctly') {
          @include assert-equal(grid-column-width(12, 1200px), 100px);
        }
      }
    }
  }
  
  @include describe('Typography Components') {
    @include it('generates font sizes correctly') {
      @include assert-equal(font-size('large'), 1.25rem);
    }
  }
}

Best Practices

Naming Conventions

Module names: Use descriptive names that group related functionality (e.g., "Math Functions", "Color Utilities")
Test names: Use action-oriented descriptions (e.g., "adds two numbers", "returns correct color value")
BDD style: Use natural language descriptions (e.g., "should add two numbers correctly")

Organization Patterns

// Group by function/feature
@include describe('Button Mixin') {
  @include it('generates base button styles') { /* ... */ }
  @include it('handles size variants') { /* ... */ }
  @include it('handles color themes') { /* ... */ }
}

// Group by use case
@include describe('Responsive Typography') {
  @include describe('Mobile Breakpoint') {
    @include it('uses smaller font sizes') { /* ... */ }
  }
  @include describe('Desktop Breakpoint') {
    @include it('uses larger font sizes') { /* ... */ }
  }
}

Mixed Testing Approaches

You can mix value assertions and CSS output testing within the same test structure:

@include describe('Button Mixin') {
  @include it('calculates padding correctly') {
    // Test function return value
    @include assert-equal(button-padding('small'), 0.5rem 1rem);
  }
  
  @include it('generates correct CSS output') {
    // Test CSS output
    @include assert {
      @include output {
        @include button('primary', 'large');
      }
      @include expect {
        padding: 1rem 2rem;
        background-color: #007bff;
        border: none;
        border-radius: 0.25rem;
      }
    }
  }
}

Install with Tessl CLI