true 2.1.3 → 2.2.0

data/sass/_true.scss

@@ -2,6 +2,7 @@
 // =============
 
 @import 'true/settings';
+@import 'true/context';
 @import 'true/utilities';
 @import 'true/messages';
 @import 'true/results';

data/sass/true/_assert.scss

@@ -2,78 +2,84 @@
 // ======
 
 
+
+// Assert True
+// -----------
 /// Assert that a parameter is `true`
 /// @access public
 /// @group testing
 /// @param {*} $assert - Assert
 /// @param {String} $description [''] - Assert description
-/// @require {mixin} _true-fail-details
-/// @require {mixin} _true-assert-start
-/// @require {mixin} _true-assert-stop
 @mixin assert-true(
   $assert,
-  $description: ''
+  $description: null
 ) {
   $default: '"#{inspect($assert)}" should be truthy';
-
   @include _true-context('assert', $description or $default);
   @include _true-assert-results('assert-true', not not $assert, true);
 }
 
+
+
+// Assert False
+// ------------
 /// Assert that a parameter is `false`
 /// @access public
 /// @group testing
-/// @param {*} $assert - Assert
-/// @param {String} $description [''] - Assert description
-/// @require {mixin} _true-fail-details
-/// @require {mixin} _true-assert-start
-/// @require {mixin} _true-assert-stop
+/// @param {*} $assert -
+///   Assert
+/// @param {String} $description [''] -
+///   Assert description
 @mixin assert-false(
   $assert,
-  $description: ''
+  $description: null
 ) {
   $default: '"#{inspect($assert)}" should be falsey';
-
   @include _true-context('assert', $description or $default);
-  @include _true-assert-results('assert-false', $assert, false);
+  @include _true-assert-results('assert-false', not $assert, true);
 }
 
-/// /// Assert that two parameters are `equal`
+
+
+// Assert Equal
+// ------------
+/// Assert that two parameters are `equal`
 /// @access public
 /// @group testing
-/// @param {*} $assert - Assert
-/// @param {*} $expected - Expected result
-/// @param {String} $description [''] - Assert description
-/// @require {mixin} _true-fail-details
-/// @require {mixin} _true-assert-start
-/// @require {mixin} _true-assert-stop
+/// @param {*} $assert -
+///   Assert
+/// @param {*} $expected -
+///   Expected result
+/// @param {String} $description [''] -
+///   Assert description
 @mixin assert-equal(
   $assert,
   $expected,
-  $description: ''
+  $description: null
 ) {
   $default: '"#{inspect($assert)}" and "#{inspect($expected)}" should be equal';
-
   @include _true-context('assert', $description or $default);
   @include _true-assert-results('assert-equal', $assert, $expected);
 }
 
+
+// Assert UnEqual
+// --------------
 /// Assert that two parameters are `unequal`
 /// @access public
 /// @group testing
-/// @param {*} $assert - Assert
-/// @param {*} $expected - Expected result
-/// @param {String} $description [''] - Assert description
-/// @require {mixin} _true-fail-details
-/// @require {mixin} _true-assert-start
-/// @require {mixin} _true-assert-stop
+/// @param {*} $assert -
+///   Assert
+/// @param {*} $expected -
+///   Expected result
+/// @param {String} $description [''] -
+///   Assert description
 @mixin assert-unequal(
   $assert,
   $expected,
-  $description: ''
+  $description: null
 ) {
   $default: '"#{inspect($assert)}" and "#{inspect($expected)}" should not be equal';
-
   @include _true-context('assert', $description or $default);
   @include _true-assert-results('assert-unequal', $assert, $expected, 'unequal');
 }
@@ -85,29 +91,31 @@
 /// Define a CSS-output assertion
 /// @access public
 /// @group testing
-/// @param {String} $description - Assert description
-/// @content Use `output()` and `expect()` mixins to define blocks for comparison
-/// @require {mixin} _true-assert-start
-/// @require {mixin} _true-assert-stop
-/// @require {function} _true-selector
+/// @param {String} $description -
+///   Assert description
+/// @content Use `output()` and `expect()` mixins
+///   to define blocks for comparison
 @mixin assert(
-  $description: ''
+  $description: null
 ) {
   $default: _true-context('test') or 'CSS output should match expected output';
-
-  @include _true-context('assert', $description);
+  @include _true-context('assert', $description or $default);
   @include _true-message('  ASSERT: #{$description}  ', 'comments');
 
   @content;
 
-  @include _true-update('output-to-css');
+  @include _true-update-test('output-to-css');
   @include _true-context-pop();
   @include _true-message('  END_ASSERT  ', 'comments');
 }
 
 
+
+// Output
+// ------
 /// Describe the test content to be evaluated
-/// The output will be compared against the results of the `expect()` mixin.
+/// The output will be compared against the results
+/// of the `expect()` mixin.
 /// @access public
 /// @group testing
 @mixin output(
@@ -139,8 +147,12 @@
 }
 
 
+
+// Expect
+// ------
 /// Describe the output content to be expected.
-/// The output will be compared against the results of the `output()` mixin.
+/// The output will be compared against the results
+///  of the `output()` mixin.
 /// @access public
 /// @group testing
 @mixin expect(
@@ -160,9 +172,10 @@
 }
 
 
+
 // Assert Results
 // --------------
-
+/// @access private
 @mixin _true-assert-results(
   $type,
   $assert,
@@ -197,6 +210,6 @@
     }
   }
 
-  @include _true-update($result);
+  @include _true-update-test($result);
   @include _true-context-pop();
 }

data/sass/true/_context.scss

@@ -0,0 +1,86 @@
+// Context Management
+// ==================
+
+
+
+// Context [variable]
+// ------------------
+/// True current context
+/// @access private
+/// @type list
+$_true-context: ();
+
+
+
+// Context [mixin]
+// ---------------
+/// Update the current context for a given scope
+/// @access private
+/// @param {String} $scope - Either `module`, `test` or `assert`
+/// @param {String} $name - Name of current scope
+@mixin _true-context(
+  $scope,
+  $name
+) {
+  $_true-context: append($_true-context, ($scope, $name)) !global;
+}
+
+
+
+// Context Pop [mixin]
+// -------------------
+/// Remove the deepest context layer
+/// @access private
+@mixin _true-context-pop() {
+  $new: ();
+
+  @for $i from 1 to length($_true-context) {
+    $new: append($new, nth($_true-context, $i));
+  }
+
+  $_true-context: $new !global;
+}
+
+
+
+// Context [function]
+// ------------------
+/// Get information on current context for a given scope
+/// @access private
+/// @param {String} $scope
+/// @return {String}
+@function _true-context(
+  $scope
+) {
+  $value: null;
+
+  @each $entry-scope, $entry-value in $_true-context {
+    @if $entry-scope == $scope {
+      $value: $entry-value;
+    }
+  }
+
+  @return $value;
+}
+
+
+
+// Context All [function]
+// ----------------------
+/// Get list of context names for a given scope
+/// @access private
+/// @param {String} $scope
+/// @return {List}
+@function _true-context-all(
+  $scope
+) {
+  $list: ();
+
+  @each $entry-scope, $entry-value in $_true-context {
+    @if $entry-scope == $scope {
+      $list: append($list, $entry-value);
+    }
+  }
+
+  @return $list;
+}

data/sass/true/_messages.scss

@@ -1,24 +1,30 @@
 // Messages
 // ========
 
+
+// TNL
+// ---
 /// New line helper
 /// @access private
-/// @group x_private
 /// @type String
-$-tnl: '\a ';
+$_tnl: '\a ';
+
 
 
-/// Output a message to CSS comments, or command line terminal (via debug/warn)
+// True Message
+// ------------
+/// Output a message to CSS comments,
+/// or command line terminal (via debug/warn)
 /// @access private
-/// @group x_private
-/// @param {String} $message - Message to output
-/// @param {String} $output [comments] - Type of output, either `comments`, `terminal`, `debug` or `warn`
-/// @require {function} _true-str-split
+/// @param {String} $message -
+///   Message to output
+/// @param {String} $output [comments] -
+///   Type of output, either `comments`, `terminal`, `debug` or `warn`
 @mixin _true-message(
   $message,
   $output: 'comments'
 ) {
-  $lines: _true-str-split($message, $-tnl);
+  $lines: _true-str-split($message, $_tnl);
   @if index($output, 'comments') {
     @each $line in $lines {
       /* #{$line} */

data/sass/true/_modules.scss

@@ -1,12 +1,14 @@
 // Test Module
 // ===========
 
+
+
+// Test Module
+// -----------
 /// Define a Test Module
 /// @access public
 /// @group testing
 /// @param {String} $name - Module name
-/// @require {mixin} _true-module-start
-/// @require {mixin} _true-module-stop
 /// @content Include all the tests that are part of this module
 @mixin test-module(
   $name
@@ -17,25 +19,23 @@
 }
 
 
-// Module Start (private)
-// ----------------------
 
+// Module Start
+// ------------
 /// Module start helper
 /// @access private
-/// @group x_private
 /// @param {String} $name - Module name
-/// @require {mixin} _true-context
-/// @require {mixin} _true-message
 @mixin _true-module-start(
   $name
 ) {
   @include _true-context(module, $name);
   $modules: _true-context-all('module');
-  @include _true-message('# Module: #{_true-str-join($modules, ' :: ')}', 'comments');
+  $modules: _true-str-join($modules, ' :: ');
+  @include _true-message('# Module: #{$modules}', 'comments');
 
   $underline: '----------';
 
-  @for $i from 1 through str-length($name) {
+  @for $i from 1 through str-length(inspect($modules)) {
     $underline: '#{$underline}-';
   }
 
@@ -43,14 +43,11 @@
 }
 
 
-// Module Stop (private)
-// ---------------------
 
+// Module Stop
+// -----------
 /// Module stop helper
 /// @access private
-/// @group x_private
-/// @require {mixin} _true-context
-/// @require {mixin} _true-message
 @mixin _true-module-stop {
   @include _true-context-pop();
   @include _true-message('', 'comments');

data/sass/true/_results.scss

@@ -1,45 +1,102 @@
 // Results
 // =======
 
-/// Results map
+
+
+// Report
+// ------
+/// Report results summary to CSS and/or command line
+/// @access public
+/// @group reporting
+/// @param {Bool} $terminal [$true-terminal-output] -
+///   Optionally output results to the terminal
+/// @param {Bool} $fail-on-error [false] -
+///   Optionally error out of the compiler if tests have failed
+@mixin report(
+  $terminal: $true-terminal-output,
+  $fail-on-error: false
+) {
+  $message: _true-report-message('global', 'multiple');
+
+  $fail: map-get($_true-results, 'fail');
+  @if $fail-on-error and ($fail > 0) {
+    @error "#{$fail} tests failed."
+  }
+
+  @include _true-message('# SUMMARY ----------', 'comments');
+  @include _true-message($message, 'comments');
+  @include _true-message('--------------------', 'comments');
+
+  @if $terminal {
+    $message: _true-report-message('global', 'single');
+    @include _true-message($message, 'debug');
+  }
+}
+
+
+
+// Results
+// -------
+/// Global test-results map
 /// @access private
-/// @group x_private
 /// @type Map
 $_true-results: (
-  run: 0,
-  pass: 0,
-  fail: 0,
-  output-to-css: 0,
+  'run': 0,
+  'pass': 0,
+  'fail': 0,
+  'output-to-css': 0,
 );
 
 
+
+// Test Fail
+// ---------
+// Local flags for tracking assertion results in a test
+/// @access private
+/// @type String
+$_true-test-result: null;
+
+
+
+// Update Test
+// -----------
+@mixin _true-update-test(
+  $result
+) {
+  @if ($result == 'fail') or ($_true-test-result == 'fail') {
+    $_true-test-result: 'fail' !global;
+  } @else if ($_true-test-result != 'output-to-css') {
+    $_true-test-result: $result !global;
+  }
+}
+
+
+
 // Update
 // ------
-
 /// Update results
 /// @access private
-/// @group x_private
-/// @param {String} $result - Result (pass/fail/output-to-css)
-/// @require {function} _true-map-increment
-/// @require $_true-results
-@mixin _true-update($result) {
+/// @param {String} $result -
+///   Result (pass/fail/output-to-css)
+@mixin _true-update(
+  $result
+) {
   $_true-results: _true-map-increment($_true-results, (
-    run: 1,
+    'run': 1,
     $result: 1,
   )) !global;
+  $_true-test-result: null !global;
 }
 
 
+
 // Report Message
 // --------------
-
 /// Report message
 /// @access private
-/// @group x_private
 /// @param {String} $scope [test] - Scope
 /// @param {String} $lines [single] - Lines
 /// @return {String} - Reported message
-/// @require {function} _true-get-results
 @function _true-report-message(
   $scope: 'test',
   $lines: 'single'
@@ -62,33 +119,9 @@ $_true-results: (
     $message: '#{$run} #{$items}, #{$pass} Passed, #{$fail} Failed';
     $message: if($output-to-css > 0, $message + ', #{$output-to-css} Output to CSS', $message);
   } @else {
-    $message: '#{$run $items}:#{$-tnl} - #{$pass} Passed#{$-tnl} - #{$fail} Failed';
-    $message: if($output-to-css > 0, $message + '#{$-tnl} - #{$output-to-css} Output to CSS', $message);
+    $message: '#{$run $items}:#{$_tnl} - #{$pass} Passed#{$_tnl} - #{$fail} Failed';
+    $message: if($output-to-css > 0, $message + '#{$_tnl} - #{$output-to-css} Output to CSS', $message);
   }
 
   @return $message;
 }
-
-
-// Report
-// ------
-
-/// Report results summary to CSS and/or command line
-/// @access public
-/// @group reporting
-/// @param {Bool} $terminal [$true-terminal-output] - Whether or not to use terminal output
-/// @require {function} _true-report-message
-/// @require {function} _true-message
-@mixin report(
-  $terminal: $true-terminal-output
-) {
-  $message: _true-report-message('global', 'multiple');
-  @include _true-message('# SUMMARY ----------', 'comments');
-  @include _true-message($message, 'comments');
-  @include _true-message('--------------------', 'comments');
-
-  @if $terminal {
-    $message: _true-report-message('global', 'single');
-    @include _true-message($message, 'debug');
-  }
-}