0
# Sass True
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: sass-true
7
- **Package Type**: npm
8
- **Language**: Sass/SCSS with JavaScript/TypeScript integration
9
- **Installation**: `npm install --save-dev sass-true`
10
11
## Core Imports
12
13
### Sass Imports
14
15
Modern @use syntax:
16
17
```scss
18
@use 'pkg:sass-true' as *;
19
```
20
21
If not using the Sass Node.js package importer:
22
23
```scss
24
@use '../node_modules/sass-true' as *;
25
```
26
27
For JavaScript test runner integration:
28
29
```scss
30
@use 'true' as *;
31
```
32
33
Legacy @import syntax (preserves `true-*` prefixes):
34
35
```scss
36
@import '../node_modules/sass-true/sass/true';
37
```
38
39
### JavaScript Imports
40
41
```typescript
42
const sassTrue = require('sass-true');
43
// or
44
import * as sassTrue from 'sass-true';
45
```
46
47
## Basic Usage
48
49
### Sass Testing
50
51
```scss
52
@use 'pkg:sass-true' as *;
53
54
// Using test-module/test syntax
55
@include test-module('Math Functions') {
56
@include test('Addition works correctly') {
57
@include assert-equal(2 + 2, 4);
58
}
59
60
@include test('CSS output is correct') {
61
@include assert {
62
@include output {
63
width: calc(100% - 20px);
64
}
65
@include expect {
66
width: calc(100% - 20px);
67
}
68
}
69
}
70
}
71
72
// Using describe/it syntax (equivalent)
73
@include describe('Math Functions') {
74
@include it('Addition works correctly') {
75
@include assert-equal(2 + 2, 4);
76
}
77
}
78
79
// Generate final report
80
@include report;
81
```
82
83
### JavaScript Test Runner Integration
84
85
```javascript
86
const path = require('node:path');
87
const sassTrue = require('sass-true');
88
89
const sassFile = path.join(__dirname, 'test.scss');
90
sassTrue.runSass({ describe, it }, sassFile);
91
```
92
93
## Architecture
94
95
Sass True is built around several key components:
96
97
- **Testing Structure**: Hierarchical test organization with modules/describe and tests/it for BDD-style testing
98
- **Dual Assertion System**: Separate APIs for testing Sass values and CSS output
99
- **Error Handling**: Sophisticated error catching and reporting system with optional compilation continuation
100
- **Reporting Engine**: Comprehensive test result reporting to both CSS and terminal
101
- **JavaScript Bridge**: CSS parsing and test runner integration for automated testing workflows
102
- **Configuration System**: Flexible settings for terminal output and error behavior
103
104
## Capabilities
105
106
### Test Organization
107
108
Hierarchical test structure using either traditional or BDD naming conventions. Supports nested modules for complex test organization.
109
110
```scss { .api }
111
@mixin test-module($name);
112
@mixin describe($name); // alias for test-module
113
@mixin test($name);
114
@mixin it($name); // alias for test
115
```
116
117
[Test Structure](./test-structure.md)
118
119
### Value Assertions
120
121
Testing Sass function outputs, variable values, and return types with comprehensive equality and truthiness checking.
122
123
```scss { .api }
124
@mixin assert-equal($assert, $expected, $description: null, $inspect: false);
125
@mixin is-equal($assert, $expected, $description: null, $inspect: false); // alias
126
@mixin assert-true($assert, $description: null);
127
@mixin is-truthy($assert, $description: null); // alias
128
@mixin assert-false($assert, $description: null);
129
@mixin is-falsy($assert, $description: null); // alias
130
@mixin assert-unequal($assert, $expected, $description: null, $inspect: false);
131
@mixin not-equal($assert, $expected, $description: null, $inspect: false); // alias
132
```
133
134
[Value Assertions](./value-assertions.md)
135
136
### CSS Output Testing
137
138
Testing compiled CSS output from mixins and complex Sass expressions, with exact matching and subset matching capabilities.
139
140
```scss { .api }
141
@mixin assert($description: null);
142
@mixin output($selector: true);
143
@mixin expect($selector: true);
144
@mixin contains($selector: true);
145
@mixin contains-string($string-to-find);
146
```
147
148
[CSS Output Testing](./css-output-testing.md)
149
150
### Error Handling
151
152
Sophisticated error catching system allowing tests to validate error conditions without stopping compilation.
153
154
```scss { .api }
155
@function error($message, $source: null, $catch: $catch-errors);
156
@mixin error($message, $source: null, $catch: $catch-errors);
157
```
158
159
[Error Handling](./error-handling.md)
160
161
### Test Reporting
162
163
Comprehensive test result reporting to both CSS comments and terminal output, with optional compilation failure on test failures.
164
165
```scss { .api }
166
@mixin report($terminal: $terminal-output, $fail-on-error: false, $results: $results, $stats: $stats);
167
```
168
169
### JavaScript Integration
170
171
Complete integration with JavaScript/TypeScript test runners, providing automated CSS parsing and test result reporting.
172
173
```typescript { .api }
174
function runSass(
175
trueOptions: TrueOptions,
176
src: string,
177
sassOptions?: any
178
): void;
179
180
function parse(rawCss: string, contextLines?: number): Module[];
181
182
function formatFailureMessage(assertion: Assertion): string;
183
184
interface TrueOptions {
185
describe: (description: string, fn: () => void) => void;
186
it: (description: string, fn: () => void) => void;
187
sass?: any;
188
sourceType?: 'path' | 'string';
189
contextLines?: number;
190
}
191
```
192
193
[JavaScript Integration](./javascript-integration.md)
194
195
## Configuration
196
197
### Global Settings
198
199
```scss { .api }
200
$terminal-output: true !default; // Show terminal output when compiling manually
201
$catch-errors: false !default; // Catch errors without stopping compilation ('warn' also shows warnings)
202
```
203
204
**Legacy Settings (for @import syntax):**
205
206
```scss { .api }
207
$true-terminal-output: true !default; // Legacy prefixed version for @import syntax
208
```
209
210
## Types
211
212
```scss { .api }
213
// Sass doesn't have explicit types, but these are the expected value types:
214
// $name: string - Test/module names and descriptions
215
// $assert, $expected: any - Values to test (numbers, strings, lists, maps, etc.)
216
// $description: string | null - Optional assertion descriptions
217
// $inspect: bool - Whether to compare inspected (string) values
218
// $selector: bool - Whether to wrap CSS output in test selectors
219
// $catch: bool | 'warn' - Error catching behavior
220
```
221
222
```typescript { .api }
223
// JavaScript integration types
224
interface Assertion {
225
description: string;
226
assertionType?: string;
227
output?: string;
228
expected?: string;
229
details?: string;
230
passed?: boolean;
231
}
232
233
interface Test {
234
test: string;
235
assertions: Assertion[];
236
}
237
238
interface Module {
239
module: string;
240
tests?: Test[];
241
modules?: Module[];
242
}
243
```