Merge pull request #311 from DT3264/ContainsString

Add support for substring matching within output assertion

Author: jgerigmeyer

sass/assert/_output.scss

@@ -166,3 +166,39 @@
 @mixin contains($selector: true) {
   @include utils.content('contains', $selector) { @content; }
 }
+
+
+// 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.
+///
+/// @group api-assert-output
+///
+/// @param {string} $string-to-find -
+///   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');
+///     }
+///   }
+@mixin contains-string($string-to-find) {
+  @include utils.content-string('contains-string', $string-to-find);
+}

sass/assert/_utils.scss

@@ -41,6 +41,38 @@
   @include config.message('  END_#{$block}  ', 'comments');
 }
 
+// Content String
+// --------------
+/// Prepares and formats the output for string-based assertions,
+/// wrapping the target string with appropriate CSS comments.
+/// This mixin is used internally by assertion mixins like `contains-string`.
+///
+/// @access private
+/// @group assert-utils
+///
+/// @param {string} $type -
+///   The type of content being output (e.g., `contains-string`).
+/// @param {string} $string-to-find -
+///   The string that will be searched for in the compiled CSS output.
+/// @param {string} $description [null] -
+///   An optional description for the assertion being tested.
+///
+/// @output - The `$string-to-find` wrapped in relevant CSS comments.
+@mixin content-string($type, $string-to-find, $description: null) {
+  @include data.output-context($type);
+
+  $block: map.get(config.$output, $type);
+  $start: if(
+    $description or ($block == 'ASSERT'),
+    '#{$block}: #{$description}',
+    $block
+  );
+
+  @include config.message('  #{$start}  ', 'comments');
+  @include config.message('#{$string-to-find}', 'comments');
+  @include config.message('  END_#{$block}  ', 'comments');
+}
+
 // Setup
 // -----
 /// Setup the proper context for value assertions before testing

sass/config/_terms.scss

@@ -8,4 +8,5 @@ $output: (
   'output': 'OUTPUT',
   'expect': 'EXPECTED',
   'contains': 'CONTAINED',
+  'contains-string': 'CONTAINS_STRING'
 );

src/constants.ts

@@ -18,6 +18,8 @@ export const OUTPUT_START_TOKEN = 'OUTPUT';
 export const OUTPUT_END_TOKEN = 'END_OUTPUT';
 export const EXPECTED_START_TOKEN = 'EXPECTED';
 export const EXPECTED_END_TOKEN = 'END_EXPECTED';
+export const CONTAINS_STRING_START_TOKEN = 'CONTAINS_STRING';
+export const CONTAINS_STRING_END_TOKEN = 'END_CONTAINS_STRING';
 export const CONTAINED_START_TOKEN = 'CONTAINED';
 export const CONTAINED_END_TOKEN = 'END_CONTAINED';
 export const ASSERT_END_TOKEN = 'END_ASSERT';

src/index.ts

@@ -550,6 +550,10 @@ export const parse = function (
         ctx.currentExpectedRules = [];
         return parseAssertionContained;
       }
+      if(text === constants.CONTAINS_STRING_START_TOKEN){
+        ctx.currentExpectedRules = [];
+        return parseAssertionContainsString;
+      }
       throw parseError(
         `Unexpected comment "${text}"`,
         'EXPECTED',
@@ -629,5 +633,28 @@ export const parse = function (
     return parseAssertionContained;
   };
 
+  const parseAssertionContainsString: Parser = function (rule, ctx) {
+    if (isCommentNode(rule)) {
+      if (rule.comment?.trim() === constants.CONTAINS_STRING_END_TOKEN) {
+        /* istanbul ignore else */
+        if (ctx.currentAssertion) {
+          // The string to find is wrapped in a Sass comment because it might not always be a complete, valid CSS block on its own.
+          // These replace calls are necessary to strip the leading `/*` and trailing `*/` characters that enclose the string,
+          // so we're left with just the raw string to find for accurate comparison.
+          ctx.currentAssertion.expected = cssStringify({
+            type: CssTypes.stylesheet,
+            stylesheet: { rules: ctx.currentExpectedRules || [] },
+          }).replace(new RegExp('^/\\*'), '').replace(new RegExp('\\*/$'), '').trim();
+          ctx.currentAssertion.passed = ctx.currentAssertion.output?.includes(ctx.currentAssertion.expected);
+          ctx.currentAssertion.assertionType = 'contains-string';
+        }
+        delete ctx.currentExpectedRules;
+        return parseEndAssertion;
+      }
+    }
+    ctx.currentExpectedRules?.push(rule);
+    return parseAssertionContainsString;
+  };
+
   return parseCss();
 };

test/main.test.js

@@ -1174,4 +1174,87 @@ describe('#parse', () => {
       expect(sassTrue.parse(css)).to.deep.equal(expected);
     });
   });
+  describe('#contains-string', () => {
+    it('parses a passing output test', () => {
+      const css = [
+        '/* # Module: Contains-string */',
+        '/* Test: CSS output contains-string */',
+        '/*   ASSERT: Output selector pattern contains-string input pattern   */',
+        '/* */',
+        '/*   OUTPUT   */',
+        '.test-output {',
+        '  height: 10px;',
+        '  width: 20px; }',
+        '/*   END_OUTPUT   */',
+        '/* */',
+        '/*   CONTAINS_STRING   */',
+        '/* height */',
+        '/*   END_CONTAINS_STRING   */',
+        '/* */',
+        '/*   END_ASSERT   */',
+      ].join('\n');
+      const expected = [
+        {
+          module: 'Contains-string',
+          tests: [
+            {
+              test: 'CSS output contains-string',
+              assertions: [
+                {
+                  description:
+                    'Output selector pattern contains-string input pattern',
+                  assertionType: 'contains-string',
+                  passed: true,
+                  output: '.test-output {\n  height: 10px;\n  width: 20px;\n}',
+                  expected: 'height',
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      expect(sassTrue.parse(css)).to.deep.equal(expected);
+    });
+
+    it('parses a failing output test', () => {
+      const css = [
+        '/* # Module: Contains-string */',
+        '/* Test: CSS output contains-string */',
+        '/*   ASSERT: Output selector pattern contains-string input pattern   */',
+        '/* */',
+        '/*   OUTPUT   */',
+        '.test-output {',
+        '  height: 10px;',
+        '  width: 20px; }',
+        '/*   END_OUTPUT   */',
+        '/* */',
+        '/*   CONTAINS_STRING   */',
+        '/* background-color */',
+        '/*   END_CONTAINS_STRING   */',
+        '/* */',
+        '/*   END_ASSERT   */',
+      ].join('\n');
+      const expected = [
+        {
+          module: 'Contains-string',
+          tests: [
+            {
+              test: 'CSS output contains-string',
+              assertions: [
+                {
+                  description:
+                    'Output selector pattern contains-string input pattern',
+                  assertionType: 'contains-string',
+                  passed: false,
+                  output: '.test-output {\n  height: 10px;\n  width: 20px;\n}',
+                  expected: 'background-color',
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      expect(sassTrue.parse(css)).to.deep.equal(expected);
+    });
+  });
 });

test/scss/assert/_output.scss

@@ -49,6 +49,37 @@
   }
 }
 
+@include describe('Output Contains-string') {
+  @include it('Contains sub-strings') {
+    @include assert {
+      @include output {
+        height: 10px;
+        width: 20px;
+      }
+
+      @include contains-string('height');
+    }
+  }
+  @include it('Contains properties') {
+    @include assert {
+      @include output {
+        --my-custom-property: 3rem;
+      }
+
+      @include contains-string('--my-custom-property');
+    }
+  }
+  @include it('Contains values') {
+    @include assert {
+      @include output {
+        font-family: Helvetica;
+      }
+
+      @include contains-string('Helvetica');
+    }
+  }
+}
+
 @include describe('Output Contains') {
   @include it('Contains sub-string') {
     @include assert {