Testing CSS Output

Unlike value assertions (which are evaluated during Sass compilation), CSS output assertions generate compiled CSS that must be compared to verify correctness. The assert(), output(), and expect() mixins work together to create this testable output.

Important: CSS output tests require comparison after Sass compilation. You have two options for verifying output:

Manual comparison – Use git diff or similar tools to review changes in the compiled CSS output. True generates structured CSS comments containing the test results, which you can inspect manually.
JavaScript test runner – Integrate with Mocha, Jest, Vitest, or similar test runners to automate the comparison. The JS integration parses the CSS output and reports differences automatically. See: https://www.oddbird.net/true/docs/#javascript-test-runner-integration

@mixin assert()

Define a CSS-output assertion. Assertions are used inside the test() mixin to define the expected results of the test.

The assert() mixin is a wrapper, and should contain one output() block and one expect() block as nested contents.
These three mixins together describe a single assert-equal comparison on output CSS. The compiled CSS-results of the output() mixin will be compared against the results of the expect() mixin.
When using Mocha/Jest integration, the output comparison is automated – otherwise you will have to compare the output manually. Using git diff is a great way to watch for changes in output.

Parameters

$description: null (string)

Description of the assertion being tested. A null of false value generates a default description.

@content (code block)

Use `output()` and `expect()` mixins to define blocks for comparison

Example

scss

@include true.test('Sass math compiles before output') {
  @include true.assert('You can also describe the assertion...') {
    @include true.output {
      width: 14em + 2;
    }
    @include true.expect {
      width: 16em;
    }
  }
}

css compiled

/* Test: Sass math compiles before output */
/*   ASSERT: You can also describe the assertion...   */
/*   OUTPUT   */
.test-output {
  width: 16em;
}

/*   END_OUTPUT   */
/*   EXPECTED   */
.test-output {
  width: 16em;
}

/*   END_EXPECTED   */
/*   END_ASSERT   */
/*  */

Requires

$output (bool) [private]

@mixin output()

Describe the test content to be evaluated against the paired expect() block. Assertions are used inside the test() mixin to define the expected results of the test.

The output() mixin requires a content block, and should be nested inside the assert() mixin along with a single expect() block.
These three mixins together describe a single assert-equal comparison on output CSS. The compiled CSS-results of the output() mixin will be compared against the results of the expect() mixin.
When using Mocha/Jest integration, the output comparison is automated – otherwise you will have to compare the output manually. Using git diff is a great way to watch for changes in output.

Parameters

$selector: true (bool)

Optionally wrap the contents in a .test-output selector block, so you can test property-value output directly.

@content (code block)

Define the test content to be checked

Example

scss

@include true.test('Sass math compiles before output') {
  @include true.assert {
    @include true.output {
      width: 14em + 2;
    }
    @include true.expect {
      width: 16em;
    }
  }
}

css compiled

/* Test: Sass math compiles before output */
/*   ASSERT:    */
/*   OUTPUT   */
.test-output {
  width: 16em;
}

/*   END_OUTPUT   */
/*   EXPECTED   */
.test-output {
  width: 16em;
}

/*   END_EXPECTED   */
/*   END_ASSERT   */
/*  */

@mixin expect()

Describe the expected results of the paired output() block. The expect() mixin requires a content block, and should be nested inside the assert() mixin, along with a single output() block. Assertions are used inside the test() mixin to define the expected results of the test.

These three mixins together describe a single assert-equal comparison on output CSS. The compiled CSS-results of the output() mixin will be compared against the results of the expect() mixin.
When using Mocha/Jest integration, the output comparison is automated – otherwise you will have to compare the output manually. Using git diff is a great way to watch for changes in output.

Parameters

$selector: true (bool)

Optionally wrap the contents in a .test-output selector block, so you can test property-value output directly.

@content (code block)

Define the expected results of a sibling `output()` mixin

Example

scss

@include true.test('Sass math compiles before output') {
  @include true.assert {
    @include true.output {
      width: 14em + 2;
    }
    @include true.expect {
      width: 16em;
    }
  }
}

css compiled

/* Test: Sass math compiles before output */
/*   ASSERT:    */
/*   OUTPUT   */
.test-output {
  width: 16em;
}

/*   END_OUTPUT   */
/*   EXPECTED   */
.test-output {
  width: 16em;
}

/*   END_EXPECTED   */
/*   END_ASSERT   */
/*  */

@mixin contains()

Describe the expected results of the paired output() block. The contains() mixin requires a content block, and should be nested inside the assert() mixin, along with a single output() block. Assertions are used inside the test() mixin to define the expected results of the test.

These three mixins together describe a single comparison on output CSS. The compiled CSS-results of the contains() mixin will be compared against the results of the output() mixin to see if all of the contains CSS is within the output CSS.
When using Mocha/Jest integration, the output comparison is automated – otherwise you will have to compare the output manually. Using git diff is a great way to watch for changes in output.

Parameters

$selector: true (bool)

Optionally wrap the contents in a .test-output selector block, so you can test property-value output directly.

@content (code block)

Define the expected results of a sibling `output()` mixin

Example

scss

@include true.test('Sass math compiles before output') {
  @include true.assert {
    @include true.output {
      height: 100%;
      width: 14em + 2;
    }
    @include true.contains {
      width: 16em;
    }
  }
}

css compiled

/* Test: Sass math compiles before output */
/*   ASSERT:    */
/*   OUTPUT   */
.test-output {
  height: 100%;
  width: 16em;
}

/*   END_OUTPUT   */
/*   CONTAINED   */
.test-output {
  width: 16em;
}

/*   END_CONTAINED   */
/*   END_ASSERT   */
/*  */

@mixin contains-string()

Describe a case-sensitive substring expected to be found within the paired output() block. The contains-string() mixin requires a string argument, and should be nested inside the assert() mixin along with a single output() block. Assertions are used inside the test() mixin to define the expected results of the test.

These mixins together describe a comparison on output CSS, checking if the compiled CSS-results of the output() mixin contain the specified $string-to-find.
When using Mocha/Jest integration, the output comparison is automated – otherwise you will have to compare the output manually. Using git diff is a great way to watch for changes in output.

Parameters

$string-to-find: (string)

The substring to search for within the compiled CSS output.

Example

scss

@include true.test('Can find partial strings') {
  @include true.assert {
    @include true.output {
      font-size: 1em;
      line-height: 1.5;
    }
    @include true.contains-string('font-size');
    @include true.contains-string('line');
  }
}

css compiled

/* Test: Can find partial strings */
/*   ASSERT:    */
/*   OUTPUT   */
.test-output {
  font-size: 1em;
  line-height: 1.5;
}

/*   END_OUTPUT   */
/*   CONTAINS_STRING   */
/* font-size */
/*   END_CONTAINS_STRING   */
/*   CONTAINS_STRING   */
/* line */
/*   END_CONTAINS_STRING   */
/*   END_ASSERT   */
/*  */