true 2.2.1 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1765574280f707dd23e99e32259fd5638bfb15de
-  data.tar.gz: cadbeaf9375bc3588433f28d738b653b6f180fb7
+  metadata.gz: fd6cc4853271c5c85b0991afcdb45a63cf9af818
+  data.tar.gz: 463cddf82b9dbe01121277074f257377af2dd2da
 SHA512:
-  metadata.gz: 2808ca9ddf9585413ac6ef95bdc6210b3886dbb3e50580fc8602eaee3b31df5b5f77589d3d8122695ecd7e7a657acb949a3b27f16fe73305328a63d265b9b93f
-  data.tar.gz: 0a7ca6fbd4313a181807d2f340185e0cef115a7d69c2abff44d9c3b1deb7d94145083c70cb44db05e53d6b48f177cd05c361c60553f20bc23d261146f19be171
+  metadata.gz: de700ce77b7ddabe698e23def93433bce2096f9c0c44fbe740bdf883f11ab6c46cd040b199f2e8b914f56308278e02f6c3632f7ebf28a14234324aebd2e73ac4
+  data.tar.gz: ad30953383bc554625fce61bda64eaf9355486fb8afe018a42d26682ee3947250d2e121c2f1d0ce100b4c16d4321531e271d18bcd7619fd7f82c58c756332d69

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 True Changelog
 ==============
 
+2.2.2 (4/11/17)
+---------------
+- `assert-true` returns false on empty strings and lists
+- `assert-false` returns true on empty strings and lists
+- Module/Test/Assertion stats are included in reports
+
 
 2.2.1 (2/7/17)
 --------------

data/README.md

@@ -181,3 +181,146 @@ toggles output to the terminal on or off.
 - `true` will show detailed information on failing assertions.
   This is the default, and best for using `true-cli`.
 - `false` to turn off all terminal output.
+
+## API
+
+### Tests
+
+Tests help define what we are testing for. They can be used individually or
+grouped as a test module.
+
+#### `@include test-module()`
+
+Defines a test module. Allows the grouping of several common purposed tests.
+
+- `@param` {`String`} `$description` [''] - Module description
+
+```scss
+  @include test-module('Description of the module being tested') {
+    // Your tests here
+  }
+```
+
+#### `@include test()`
+
+Defines a test. Allows the definition of a single test for your module.
+
+- `@param` {`String`} `$description` [''] - Test description
+
+```scss
+  @include test-module('My test module description') {
+    @include test('Your test description') {
+      // Your asserts go here.
+    }
+  }
+```
+
+### Asserts
+
+Asserts help define what we are testing for. A test must contain at least one
+assert but can have as many as necessary based on your testing needs.
+
+#### `@include assert()`
+
+Defines a single assert for a CSS output. It's used together with the
+`output()` and `expect()` mixins to compare a mixin with it's expected output.
+
+
+```scss
+  @include test('Your test description') {
+    @include assert('Your assert description') {
+      @include output {
+        // Mixin to be evaluated
+        @include the-mixin-to-be-tested();
+      }
+
+      @include expect {
+        // The expected output of the-mixin-to-be-tested()
+        ...
+      }
+    }
+  }
+```
+
+
+#### `@include assert-false()`
+
+Asserts that the output of a test is falsy. This includes `false`, `null`,
+`''` (empty string) and `()` (empty list).
+
+- `@param` {`*`} `$assert` - Assert to be tested
+- `@param` {`String`} `$description` [''] - Assert description
+
+```scss
+  @include test('Your test description') {
+    $test: sample-function(5);
+
+    @include assert-false($test, 'Your assert description');
+  }
+```
+
+
+#### `@include assert-true()`
+
+Asserts that the output of a test is not falsy. The test will pass as long as
+the assert returns something.
+
+- `@param` {`*`} `$assert` - Assert to be tested
+- `@param` {`String`} `$description` [''] - Assert description
+
+```scss
+  @include test('Your test description') {
+    $test: sample-function(5);
+
+    @include assert-true($test, 'Your assert description');
+  }
+```
+
+
+#### `@include assert-equal()`
+
+Asserts that two parameters are equal.
+
+- `@param` {`*`} `$assert` - Assert to be tested
+- `@param` {`*`} `$expected` - Expected result
+- `@param` {`String`} `$description` [''] - Assert description
+
+```scss
+  @include test('Your test description') {
+    $test: sample-function(5);
+
+    @include assert-equals($test, 10, 'Your assert description');
+  }
+```
+
+
+#### `@include assert-unequal()`
+
+Asserts that two parameters are unequal.
+
+- `@param` {`*`} `$assert` - Assert to be tested
+- `@param` {`*`} `$expected` - Expected result
+- `@param` {`String`} `$description` [''] - Assert description
+
+```scss
+  @include test('Your test description') {
+    $test: sample-function(5);
+
+    @include assert-unequal($test, 10, 'Your assert description');
+  }
+```
+
+### Summary
+
+Reports show a summary of total, passed, failed, and output to CSS tests. The summary can be output into CSS and/or onto the terminal. If you use Mocha, reporting to the command line is automatic. If you use true-cli, `@include report(terminal)` is required at the end of your main test file for output.
+
+#### `@include report()`
+
+Reports summary and stats data into CSS and/or onto the terminal.
+
+- `@param` {`Bool`} `$terminal` [`true`] - Optionally output results to the terminal
+- `@param` {`Bool`} `$fail-on-error` [`false`] - Optionally error out the compiler if tests have failed
+
+```scss
+  @include report();
+```

data/bin/true-cli

@@ -59,8 +59,9 @@ output = with_captured_stdout do
   end
 end
 
+matches = output.match(%r{(?<tests>\d+) Tests?, (?<passed>\d+) Passed, (?<failed>\d+) Failed})
+stats_matches = output.match(%r{(?<modules>\d+) Modules?, (?<tests>\d+) Tests?, (?<assertions>\d+) Assertions?})
 
-matches = output.match(%r{(?<tests>\d+) Tests, (?<passed>\d+) Passed, (?<failed>\d+) Failed})
 if matches.nil? # return sass errors
   puts output
   exit(2)
@@ -68,10 +69,15 @@ end
 
 if matches[:failed] == '0'
   if options['color']
-    noun = matches[:tests].to_i == 1 ? 'Test' : 'Tests'
-    puts COLORS[:ok] + "#{matches[:tests]} #{noun}, #{matches[:passed]} Passed, #{matches[:failed]} Failed" + COLORS[:end] unless options['silent']
+    unless options['silent']
+      puts COLORS[:ok] + matches.to_s + COLORS[:end]
+      puts COLORS[:ok] + stats_matches.to_s + COLORS[:end]
+    end
   else
-    puts output unless options['silent']
+    unless options['silent']
+      puts matches
+      puts stats_matches
+    end
   end
   exit(0)
 else

data/sass/true/_assert.scss

@@ -5,7 +5,7 @@
 
 // Assert True
 // -----------
-/// Assert that a parameter is `true`
+/// Assert that a parameter is truey (anything not falsey)
 /// @access public
 /// @group testing
 /// @param {*} $assert - Assert
@@ -15,15 +15,21 @@
   $description: null
 ) {
   $default: '"#{inspect($assert)}" should be truthy';
+  $truey-assert: if(
+    not not $assert and
+    $assert != '' and
+    $assert != (),
+    true,
+    false);
   @include _true-context('assert', $description or $default);
-  @include _true-assert-results('assert-true', not not $assert, true);
+  @include _true-assert-results('assert-true', $truey-assert, true);
 }
 
 
 
 // Assert False
 // ------------
-/// Assert that a parameter is `false`
+/// Assert that a parameter is falsey (false, null, empty stirng or empty list)
 /// @access public
 /// @group testing
 /// @param {*} $assert -
@@ -35,8 +41,14 @@
   $description: null
 ) {
   $default: '"#{inspect($assert)}" should be falsey';
+  $falsey-assert: if(
+    not $assert or
+    $assert == '' or
+    $assert == (),
+    true,
+    false);
   @include _true-context('assert', $description or $default);
-  @include _true-assert-results('assert-false', not $assert, true);
+  @include _true-assert-results('assert-false', $falsey-assert, true);
 }
 
 
@@ -105,6 +117,7 @@
   @content;
 
   @include _true-update-test('output-to-css');
+  @include _true-update-stats-count('assertions');
   @include _true-context-pop();
   @include _true-message('  END_ASSERT  ', 'comments');
 }
@@ -211,5 +224,6 @@
   }
 
   @include _true-update-test($result);
+  @include _true-update-stats-count('assertions');
   @include _true-context-pop();
 }

data/sass/true/_modules.scss

@@ -49,6 +49,7 @@
 /// Module stop helper
 /// @access private
 @mixin _true-module-stop {
+  @include _true-update-stats-count('modules');
   @include _true-context-pop();
   @include _true-message('', 'comments');
 }

data/sass/true/_results.scss

@@ -11,12 +11,13 @@
 /// @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
+///   Optionally error out the compiler if tests have failed
 @mixin report(
   $terminal: $true-terminal-output,
   $fail-on-error: false
 ) {
   $message: _true-report-message('global', 'multiple');
+  $stats-message: _true-stats-message($_true-stats-count, 'multiple');
 
   $fail: map-get($_true-results, 'fail');
   @if $fail-on-error and ($fail > 0) {
@@ -25,12 +26,17 @@
 
   @include _true-message('# SUMMARY ----------', 'comments');
   @include _true-message($message, 'comments');
+  @include _true-message($stats-message, 'comments');
   @include _true-message('--------------------', 'comments');
 
   @if $terminal {
     $message: _true-report-message('global', 'single');
     @include _true-message($message, 'debug');
+
+    $stats-message: _true-stats-message($_true-stats-count, 'single');
+    @include _true-message($stats-message, 'debug');
   }
+
 }
 
 
@@ -95,7 +101,8 @@ $_true-test-result: null;
 /// Report message
 /// @access private
 /// @param {String} $scope [test] - Scope
-/// @param {String} $lines [single] - Lines
+/// @param {String} $lines [single] -
+///   Return message either as a single line or in multiple lines
 /// @return {String} - Reported message
 @function _true-report-message(
   $scope: 'test',
@@ -110,9 +117,9 @@ $_true-test-result: null;
   $message: null;
 
   @if $scope == 'global' or $scope == 'module' {
-    $items: 'Tests';
+    $items: if($run == 1, 'Test', 'Tests');
   } @else if $scope == 'test' {
-    $items: 'Assertions';
+    $items: if($run == 1, 'Assertion', 'Assertions');
   }
 
   @if $lines == 'single' {
@@ -125,3 +132,59 @@ $_true-test-result: null;
 
   @return $message;
 }
+
+// Stats Count
+// -----------
+/// Global stats count of how many modules, tests, and assertions are found
+/// @access private
+/// @type Map<String: Number>
+$_true-stats-count: (
+  'modules': 0,
+  'tests': 0,
+  'assertions': 0
+);
+
+
+
+// Update stats count
+// ------------------
+/// Add to a stats count type count by 1
+/// @param {String} $type - The stats type to add to
+/// @access private
+@mixin _true-update-stats-count($type) {
+  $_true-stats-count: _true-map-increment($_true-stats-count, ($type: 1)) !global;
+}
+
+
+
+// Stats Message
+// -------------
+/// Stats message
+/// @access private
+/// @param {Map<String: Number>} $stats [$_true-stats-count] -
+///   Map that contains the stats counts for modules, tests, and assertions found
+/// @param {String} $lines [single] -
+///   Return message either as a single line or in multiple lines
+/// @return {String} - Stats count message
+@function _true-stats-message(
+  $stats: $_true-stats-count,
+  $lines: 'single'
+) {
+  $message: null;
+
+  $modules: map-get($stats, 'modules');
+  $tests: map-get($stats, 'tests');
+  $assertions: map-get($stats, 'assertions');
+
+  $modules-label: if($modules == 1, 'Module', 'Modules');
+  $tests-label: if($tests == 1, 'Test', 'Tests');
+  $assertions-label: if($assertions == 1, 'Assertion', 'Assertions');
+
+  @if $lines == 'single' {
+    $message: '#{$modules} #{$modules-label}, #{$tests} #{$tests-label}, #{$assertions} #{$assertions-label}';
+  } @else {
+    $message: 'Stats: #{$_tnl} - #{$modules} #{$modules-label} #{$_tnl} - #{$tests} #{$tests-label} #{$_tnl} - #{$assertions} #{$assertions-label}';
+  }
+
+  @return $message;
+}

data/sass/true/_tests.scss

@@ -40,6 +40,7 @@
 /// @access private
 @mixin _true-test-stop {
   @include _true-update($_true-test-result);
+  @include _true-update-stats-count('tests');
   @include _true-context-pop();
   @include _true-message('', 'comments');
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: 'true'
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.2.2
 platform: ruby
 authors:
 - Miriam Eric Suzanne
@@ -16,14 +16,14 @@ dependencies:
   name: sass
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.4'
 description: Unit tests for maintaining test-driven Sass libraries.
@@ -40,6 +40,11 @@ extra_rdoc_files:
 - README.md
 - lib/true.rb
 files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- VERSION
+- bin/true-cli
 - lib/compass-true.rb
 - lib/main.js
 - lib/true.rb
@@ -52,37 +57,32 @@ files:
 - sass/true/_settings.scss
 - sass/true/_tests.scss
 - sass/true/_utilities.scss
-- CHANGELOG.md
-- LICENSE.txt
-- README.md
-- VERSION
-- bin/true-cli
 homepage: http://oddbird.net/true
 licenses: []
 metadata: {}
 post_install_message: 
 rdoc_options:
-- --line-numbers
-- --inline-source
-- --title
+- "--line-numbers"
+- "--inline-source"
+- "--title"
 - 'true'
-- --main
+- "--main"
 - README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '1.2'
 requirements: []
 rubyforge_project: 'true'
-rubygems_version: 2.1.10
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 3
 summary: Testing framework for Sass libraries.