True 8.1.0

Catching & Testing Errors

Sass doesn’t (yet) provide a way to catch errors, but we provide a workaround that works for many use-cases (especially unit-testing error states).

Since v6.0:

@function error()

Use in place of @error statements inside functions. When the $catch parameter (or global $catch-errors setting) is set, the function will return errors without stopping compilation. This can be used to test errors as return values with True, or to “catch” errors and handle them in different ways.

Since v6.0:

Parameters & Return

$message: (string)

The error message to report

$source: null (string)

The source of the error, for additional context

$catch: $catch-errors (bool | 'warn')

Optionally catch errors, and return them as values without stopping compilation

@return (string)

A message detailing the source and error, when $catch is true

@error

A message detailing the source and error, when $catch is false

Example

scss 
@use 'throw';
@use 'sass:meta';

@function add($a, $b) {
  @if (meta.type-of($a) != 'number') or (meta.type-of($b) != 'number') {
    @return throw.error(
      $message: '$a and $b must both be numbers',
      $source: 'add()',
      $catch: true
    );
  }
  @return $a + $b;
}

.demo { width: add(3em, 'hello'); }
css compiled 
.demo {
  width: "ERROR [add()]: $a and $b must both be numbers";
}

Used By

@mixin report()

@function validate-output-context() [private]

@function join-multiple() [private]

@mixin error()

Use in place of @error statements inside mixins or other control structures with CSS output (not functions). When the $catch parameter (or global $catch-errors setting) is set, the function will output errors as comments without stopping compilation. This can be used to test errors as return values with True, or to “catch” errors and handle them in different ways.

Since True results rely on completing compilation, we do not have a way to “error out” of the code being tested. If there is code that needs to be skipped after an error, we recommend using explicit Sass conditional (if/else) statements to avoid compounding the problem:

 @mixin width ($length) {
   @if (meta.type-of($length) != number) {
     @include true.error("$length must be a number", "width", true);
   @else {
     // The @else block hides any remaining output
     width: $length;
   }
 }

Since v6.0:

Parameters & Output & Return

$message: (string | list)

The error message to report

$source: null (string)

The source of the error, for additional context

$catch: $catch-errors (bool | 'warn')

Optionally catch errors, and output them as CSS comments without stopping compilation

{CSS output} (code block)

A message detailing the source and error, when $catch is true

@error

A message detailing the source and error, when $catch is false

Example

scss 
@use 'throw';
$run: 5; $total: 6;

@if ($run != $total) {
  @include throw.error(
    $message: 'The results don’t add up.',
    $source: 'report',
    $catch: true
  );
}
css compiled 
@charset "UTF-8";
/* ERROR [report]: */
/*   The results don’t add up. */