0
# Value Assertions
1

2
Testing Sass function outputs, variable values, and return types with comprehensive equality and truthiness checking. These assertions test Sass values during compilation.
3

4
## Capabilities
5

6
### Equality Testing
7

8
Tests whether two Sass values are equal using Sass's built-in equality comparison.
9

10
```scss { .api }
11
/**
12
 * Assert that two values are equal
13
 * @param $assert - The actual value to test
14
 * @param $expected - The expected value to match against
15
 * @param $description - Optional description of the assertion (generates default if null)
16
 * @param $inspect - Whether to compare inspected (string) values instead of Sass values
17
 */
18
@mixin assert-equal($assert, $expected, $description: null, $inspect: false);
19

20
/**
21
 * Alias for assert-equal
22
 * @param $assert - The actual value to test
23
 * @param $expected - The expected value to match against  
24
 * @param $description - Optional description of the assertion
25
 * @param $inspect - Whether to compare inspected values
26
 */
27
@mixin is-equal($assert, $expected, $description: null, $inspect: false);
28
```
29

30
**Usage Examples:**
31

32
```scss
33
@use 'pkg:sass-true' as *;
34
@use 'sass:math';
35

36
@include test('Math operations work correctly') {
37
  // Test numbers
38
  @include assert-equal(math.div(10, 2), 5);
39
  
40
  // Test strings  
41
  @include assert-equal('hello' + ' world', 'hello world');
42
  
43
  // Test lists
44
  @include assert-equal((1, 2, 3), (1, 2, 3));
45
  
46
  // Test maps
47
  @include assert-equal((a: 1, b: 2), (a: 1, b: 2));
48
  
49
  // Test colors
50
  @include assert-equal(red, #ff0000);
51
  
52
  // Test with custom description
53
  @include assert-equal(
54
    my-function(10px), 
55
    0.625rem,
56
    'Converts pixels to rem correctly'
57
  );
58
  
59
  // Test inspected values (compare as strings)
60
  @include assert-equal(
61
    10px + 5px,
62
    20px,
63
    'CSS calc is not evaluated in Sass',
64
    $inspect: true
65
  );
66
}
67
```
68

69
### Inequality Testing
70

71
Tests whether two Sass values are not equal.
72

73
```scss { .api }
74
/**
75
 * Assert that two values are not equal
76
 * @param $assert - The actual value to test
77
 * @param $expected - The value that should not match
78
 * @param $description - Optional description of the assertion
79
 * @param $inspect - Whether to compare inspected values
80
 */
81
@mixin assert-unequal($assert, $expected, $description: null, $inspect: false);
82

83
/**
84
 * Alias for assert-unequal
85
 * @param $assert - The actual value to test
86
 * @param $expected - The value that should not match
87
 * @param $description - Optional description of the assertion
88
 * @param $inspect - Whether to compare inspected values
89
 */
90
@mixin not-equal($assert, $expected, $description: null, $inspect: false);
91
```
92

93
**Usage Examples:**
94

95
```scss
96
@use 'pkg:sass-true' as *;
97

98
@include test('Values are different') {
99
  // Test different types
100
  @include assert-unequal(1, '1', 'Number and string are different');
101
  
102
  // Test different values
103
  @include assert-unequal(red, blue);
104
  
105
  // Test similar but different lists
106
  @include assert-unequal((1, 2, 3), (1, 2, 4));
107
  
108
  // Test with inspected values
109
  @include assert-unequal(
110
    10px,
111
    '10px',
112
    'Number and string representations differ',
113
    $inspect: true
114
  );
115
}
116
```
117

118
### Truthiness Testing
119

120
Tests whether a value is truthy according to Sass semantics, with enhanced truthiness that considers empty lists and strings as falsy.
121

122
```scss { .api }
123
/**
124
 * Assert that a value is truthy (enhanced truthiness: empty lists/strings are falsy)
125
 * @param $assert - The value to test for truthiness
126
 * @param $description - Optional description of the assertion
127
 */
128
@mixin assert-true($assert, $description: null);
129

130
/**
131
 * Alias for assert-true
132
 * @param $assert - The value to test for truthiness
133
 * @param $description - Optional description of the assertion
134
 */
135
@mixin is-truthy($assert, $description: null);
136
```
137

138
**Usage Examples:**
139

140
```scss
141
@use 'pkg:sass-true' as *;
142

143
@include test('Truthy values') {
144
  // Numbers (except 0)
145
  @include assert-true(1);
146
  @include assert-true(0.1);
147
  @include assert-true(-1);
148
  
149
  // Non-empty strings
150
  @include assert-true('hello');
151
  @include assert-true('0'); // String '0' is truthy
152
  
153
  // Non-empty lists
154
  @include assert-true((1, 2, 3));
155
  @include assert-true((a,)); // Single-item list
156
  
157
  // Maps
158
  @include assert-true((a: 1));
159
  
160
  // Colors
161
  @include assert-true(red);
162
  @include assert-true(transparent); // Even transparent is truthy
163
  
164
  // Boolean true
165
  @include assert-true(true);
166
  
167
  // Custom description
168
  @include assert-true(
169
    get-config('enabled'),
170
    'Configuration should be enabled'
171
  );
172
}
173
```
174

175
### Falsiness Testing
176

177
Tests whether a value is falsy, including enhanced falsiness for empty lists and strings.
178

179
```scss { .api }
180
/**
181
 * Assert that a value is falsy (enhanced falsiness: empty lists/strings are falsy)
182
 * @param $assert - The value to test for falsiness
183
 * @param $description - Optional description of the assertion
184
 */
185
@mixin assert-false($assert, $description: null);
186

187
/**
188
 * Alias for assert-false
189
 * @param $assert - The value to test for falsiness
190
 * @param $description - Optional description of the assertion
191
 */
192
@mixin is-falsy($assert, $description: null);
193
```
194

195
**Usage Examples:**
196

197
```scss
198
@use 'pkg:sass-true' as *;
199

200
@include test('Falsy values') {
201
  // Boolean false
202
  @include assert-false(false);
203
  
204
  // Null
205
  @include assert-false(null);
206
  
207
  // Empty string (enhanced falsiness)
208
  @include assert-false('');
209
  
210
  // Empty list (enhanced falsiness)  
211
  @include assert-false(());
212
  
213
  // Zero (standard Sass truthiness - zero is truthy in Sass)
214
  // Note: 0 is actually truthy in Sass, so this would fail:
215
  // @include assert-false(0); // This assertion would fail!
216
  
217
  // Custom description
218
  @include assert-false(
219
    get-optional-config('theme'),
220
    'Optional theme should not be set'
221
  );
222
}
223
```
224

225
## Advanced Usage
226

227
### Testing Complex Data Structures
228

229
```scss
230
@use 'pkg:sass-true' as *;
231

232
@include test('Complex data structure testing') {
233
  $config: (
234
    theme: (
235
      primary: #007bff,
236
      secondary: #6c757d,
237
      sizes: (small: 0.875rem, large: 1.25rem)
238
    ),
239
    breakpoints: (mobile: 768px, desktop: 1024px)
240
  );
241
  
242
  // Test nested map access
243
  @include assert-equal(
244
    map-get(map-get($config, 'theme'), 'primary'),
245
    #007bff
246
  );
247
  
248
  // Test entire sub-maps
249
  @include assert-equal(
250
    map-get($config, 'breakpoints'),
251
    (mobile: 768px, desktop: 1024px)
252
  );
253
}
254
```
255

256
### Testing Function Error States
257

258
```scss
259
@use 'pkg:sass-true' as *;
260

261
@include test('Function error handling') {
262
  // Test that a function returns an error
263
  @include assert-equal(
264
    divide-by-zero(10, 0),
265
    'ERROR [divide()]: Cannot divide by zero',
266
    'Should return error message for division by zero'
267
  );
268
  
269
  // Test error message format
270
  @include assert-true(
271
    str-index(invalid-color('not-a-color'), 'ERROR') == 1,
272
    'Error messages should start with ERROR'
273
  );
274
}
275
```
276

277
### Inspect Mode for CSS Output Testing
278

279
The `$inspect` parameter converts values to their string representations, useful for testing CSS output:
280

281
```scss
282
@use 'pkg:sass-true' as *;
283

284
@include test('CSS value inspection') {
285
  // Without inspect - compares Sass values
286
  @include assert-equal(10px + 5px, 15px); // Passes
287
  
288
  // With inspect - compares string representations
289
  @include assert-equal(
290
    10px + 5px,
291
    '15px',
292
    'Should match string representation',
293
    $inspect: true
294
  ); // Passes
295
  
296
  // Inspect mode for complex values
297
  @include assert-equal(
298
    (margin: 1rem, padding: 0.5rem),
299
    '(margin: 1rem, padding: 0.5rem)',
300
    'Should match map string representation',
301
    $inspect: true
302
  );
303
}
304
```
305

306
## Type Support
307

308
Sass True supports testing all Sass data types:
309

310
- **Numbers**: `1`, `10px`, `1.5rem`, `50%`
311
- **Strings**: `'hello'`, `"world"`, unquoted identifiers
312
- **Colors**: `red`, `#ff0000`, `rgb(255, 0, 0)`, `hsl(0, 100%, 50%)`
313
- **Booleans**: `true`, `false`
314
- **Null**: `null`  
315
- **Lists**: `(1, 2, 3)`, `1 2 3`, nested lists
316
- **Maps**: `(a: 1, b: 2)`, nested maps
317
- **Functions**: Function references (though these can't be easily tested for equality)