True: Unit Testing for Sass

You can run Sass tests within JS frameworks like Mocha, Jest, or Vitest by using the sass-true package to bridge the two.

1. Create a JS test shim

Create a file (e.g., test/sass.test.js) to invoke the Sass compilation:

import path from 'node:path';
import { fileURLToPath } from 'node:url';
import sassTrue from 'sass-true';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const sassFile = path.join(__dirname, 'test.scss');

// Pass your runner's describe/it functions to runSass
sassTrue.runSass({ describe, it }, sassFile);

2. Configure Watch Mode

Standard JS runners may not detect .scss changes automatically.

• Vitest: Add Sass files to forceRerunTriggers in vitest.config.js:

  test: { forceRerunTriggers: ['**/*.scss'] }

• Jest: Add scss to moduleFileExtensions in jest.config.js:

  moduleFileExtensions: ['js', 'json', 'scss']

The runSass() function is the primary entry point for integrating True with JavaScript environments.

Signature: sassTrue.runSass(testRunnerConfig, sassPathOrSource, sassOptions);

Arguments

1. testRunnerConfig (Object, Required)

2. sassPathOrSource ('string' or 'path', Required)

• File path to the Sass test file, or
• Inline Sass source code (if sourceType: 'string')

3. sassOptions (Object, Optional)

Standard Sass compile options (e.g., importers, loadPaths, style).

Important Notes:

• Style Requirement: You must use style: 'expanded'. style: 'compressed' is not supported.
• Automatic Load Paths: True automatically adds its own Sass directory to loadPaths.
• Automatic Importers: If using Dart Sass $\ge$ v1.71 and importers is not defined, the Node.js package importer is added automatically.

The project uses a flat configuration file (eslint.config.js) based on eslint/config. It integrates several plugins and presets to enforce code quality, TypeScript support, import ordering, and testing environment globals.

Key Configurations

• Global Ignores: The following directories and files are excluded from linting:

  • .git/*, .nyc_output/*, .vscode/*, .yarn/*, .yarnrc.yml, coverage/*, dist/*, docs/*, node_modules/*

• General JavaScript/TypeScript Files: Applies to **/*.{js,mjs,cjs,ts,cts,mts}.

  • Uses typescript-eslint parser.
  • Globals: node and es2022.
  • parserOptions.sourceType is set to script.
  • Enforces import-x rules for import management.

• Source Files: Applies to src/**/*.{js,mjs,cjs,ts,cts,mts}.

  • Uses typescript-eslint parser.
  • Globals: browser and es2022.
  • parserOptions.sourceType is set to module.
  • Uses simple-import-sort for strict import/export sorting.
  • Disables import-x/order to avoid conflicts with simple-import-sort.

• Test Files: Applies to test/**/*.{js,ts}.

  • Uses typescript-eslint parser.
  • Globals: vitest environments, mocha, and es2022.
  • Includes vitest plugin and recommended Vitest rules.
  • Uses simple-import-sort for sorting.

The runSass function is the primary entry point for executing Sass tests. It takes a source string (or path), compiles it using a Sass implementation (like sass or sass-embedded), and then parses the resulting CSS to execute assertions defined within the Sass file via special comment tokens.

Key Requirements:

• Sass Implementation: True will attempt to automatically load sass-embedded or sass. You can also provide a specific compiler via TrueOptions.sass.
• Output Style: You must not use style: "compressed" in your Sass options. True requires the default expanded output style to correctly parse and match CSS rules.
• Test Runner Integration: You must provide describe and it functions in TrueOptions (e.g., from Jest, Mocha, or Vitest) to report test results.

import { runSass } from 'true';

runSass(
  {
    describe: describe, // e.g., from Jest
    it: it,             // e.g., from Jest
    sass: 'sass-embedded' // optional: specify compiler
  },
  'path/to/your/test.scss',
  { /* Sass options */ }
);