rast 0.18.0 → 0.19.0

data/README.md

@@ -2,33 +2,97 @@
 
 RSpec All Scenario Testing
 
-This library runs on top of RSpec to provide basically a parameterized unit testing pattern. It follows a specific pattern of writing unit tests, enabling a predictable, complete and easy to analyze report result.
+[![Gem Version](https://badge.fury.io/rb/rast.svg)](https://badge.fury.io/rb/rast)
+[![Build Status](https://travis-ci.com/roycetech/rast.svg?branch=master)](https://travis-ci.com/roycetech/rast)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/280a80e7e03350b7a3d3/test_coverage)](https://codeclimate.com/github/roycetech/rast/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/280a80e7e03350b7a3d3/maintainability)](https://codeclimate.com/github/roycetech/rast/maintainability)
 
+This library runs on top of RSpec to provide basically a parameterized unit testing pattern. It follows a specific pattern of writing unit tests, enabling a predictable, complete and outputs a result that is simple to analyze.
 
-## Definition of terms
+### A Basic Example
 
-`spec` - as defined in the yaml file, the individual elements under `specs`
-`scenario` - a specific combination of tokens from vars, it can uniquely identify a fixture.
-`fixture` - instance of a spec, containing a scenario, reference back to the spec, and the expected result for the given scenario.
-`variables` - raw list of variables to be combined into multiple fixtures.
-`rule` - set of outcome paired with rule clause.
-`exemption/exclusions` - rule defining variable combinations to be excluded from the test.
-`outcome` - the left portion of a rule e.g. `true: true&true`
-`clause` - the right portion of a rule
-`token` - used loosely to denote the individual variable in a rule. e.g. `true: you & me`, 'you' and 'me' are tokens.
+Suppose we want to create a class that checks if a number is a positive number or not.
 
+#### Create a spec file `spec/positive_spec.rb`
 
-##
+```ruby
+require 'rast'
+
+rast Positive do
+  spec 'Is Positive Example' do
+    execute { |number| subject.positive?(number) }
+  end
+end
+```
+
+#### Create a spec configuration `spec/rast/positive_spec.yml`
+
+```yaml
+specs:
+  Is Positive Exaple:
+    variables: {number: [-1, 0, 1]}
+    outcomes: {true: 1}
+```
+
+The class to test:
+
+```ruby
+# positive.rb
+class Positive
+  def positive?(number)
+    number > 0
+  end
+end
+```
+
+Running the test:
+
+`$ rspec -fd spec/examples/positive_spec.rb`
+
+Test result:
+
+```
+Positive: #positive?
+  [false]=[number: -1]
+  [false]=[number: 0]
+  [true]=[number: 1]
+
+Finished in 0.00471 seconds (files took 0.47065 seconds to load)
+3 examples, 0 failures
+```
+
+Read the [documentation](./Documentation.md) for more examples.
+
+## Contributing
+
+### Definition of terms
+
+- `spec` - as defined in the yaml file, the individual elements under `specs`
+- `scenario` - a specific combination of tokens from vars, it can uniquely identify a fixture.
+- `token` - used loosely to denote the individual variable in a rule. e.g. `true: you & me`, `you` and `me` are tokens.
+- `fixture` - a hash containing a scenario, reference back to the spec, and the expected result for the given scenario.
+- `variables` - raw list of variables to be combined into multiple fixtures.
+- `rule` - set of outcomes, each paired with rule clause.
+- `exclusions` - rule defining variable combinations to be excluded from the test.
+- `inclusions` - rule that limits the scenarios to be included. Useful for isolating test cases.
+- `outcome` - the left portion `us` of a rule e.g. `us: you&me`
+- `clause` - the right portion `you&me` of a rule e.g. `us: you&me`
+
+## Notes to author
 
 When running the tests, the execution starts at the spec file, then invoking the
 DSL. The DSL will then invoke the parameter generator to generate the scenarios.
 
-## Adding new features
+### Releasing new features/bugfix
 
 - Increment the .gemspec
 - Modify the CHANGELOG.md
 
-## Releasing GEM
+### Releasing GEM
+
+- Build gem with `gem build rast.gemspec`
+- Publish with `gem push <gem-filename>`
+
+## References
 
-Build gem with `gem build rast.gemspec`
-Publish with `gem push <gem-filename>`
+[Semantic Versioning](https://semver.org)

data/examples/enum_module.rb

@@ -3,13 +3,11 @@
 # Functions for detecting an enum.
 module EnumModule
   def enum?(back_card)
-    return false unless back_card.is_a?(Array) && back_card.any?
+    return false unless valid?(back_card)
 
-    return true if ordered?(back_card) || enum_with_header?(back_card)
+    return true if ordered_or_headered?(back_card)
 
-    back_card.each { |element| return false unless element[/^[-+*]\s.*/] }
-
-    return false unless same_prefix?(back_card)
+    return false if detect_non_ol(back_card) || !same_prefix?(back_card)
 
     true
   end
@@ -24,10 +22,26 @@ module EnumModule
 
   private
 
+  def valid?(back_card)
+    back_card.is_a?(Array) && back_card.any?
+  end
+
+  def ordered_or_headered?(back_card)
+    ordered?(back_card) || enum_with_header?(back_card)
+  end
+
+  def detect_non_ol(back_card)
+    back_card.each { |element| return true unless element[/^[-+*]\s.*/] }
+
+    false
+  end
+
   def enum_with_header?(back_card)
     return false if back_card.first[/^[-+*]\s.*/]
 
-    back_card[1..back_card.size].each { |element| return false unless element[/^[-+*]\s.*/] }
+    back_card[1..back_card.size].each do |element|
+      return false unless element[/^[-+*]\s.*/]
+    end
 
     true
   end

data/examples/factory_example.rb

@@ -2,10 +2,10 @@
 
 # Sample module
 module FactoryExample
-  def phone_plan_name
-    return @phone.third_name if @phone.third_name
-    return @phone.second_name if @phone.second_name
+  def person_name
+    return @person.alias_name if @person.alias_name
+    return @person.last_name if @person.last_name
 
-    @phone.first_name
+    @person.first_name
   end
 end

data/examples/hotel_finder.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Example
+class HotelFinder
+  def aircon; end
+
+  def security; end
+
+  def applicable?
+    return false if aircon.nil? || security.nil?
+
+    aircon.operational? && security.grade == :diplomat
+  end
+end

data/examples/person.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+#
+class Person
+  attr_accessor :first_name, :last_name, :alias_name
+end

data/examples/prime_number.rb

@@ -3,17 +3,22 @@
 # Example that returns true if the number passed is a prime number
 class PrimeNumber
   def prime?(number)
-    is_prime = true
     raise "Invalid number: #{number}" if number <= 0
 
-    if number == 1
-      is_prime = false
-    elsif number > 2
-      (2...number).each do |i|
-        is_prime = number % i != 0
-        break unless is_prime
-      end
+    return false if number == 1
+
+    compute_prime(number)
+  end
+
+  private
+
+  def compute_prime(number)
+    is_prime = true
+    (2...number).each do |i|
+      is_prime = number % i != 0
+      break unless is_prime
     end
+
     is_prime
   end
 end

data/lib/rast/parameter_generator.rb

@@ -21,18 +21,22 @@ class ParameterGenerator
 
     spec_config = @specs_config[spec_id]
 
+    raise "Spec not found for: #{spec_id}. Check yaml file." if spec_config.nil?
+
     spec_config[:description] = spec_id
 
     # Keep, for backwards compatibility
     spec_config['rules'] ||= spec_config['outcomes']
     spec_config['default'] ||= spec_config['else']
 
-    spec = instantiate_spec(spec_config)
+    spec_config['variables'] = expand_variables(spec_config['variables'])
+
+    spec = build_spec(spec_config)
 
     list = []
 
     variables = spec.variables
-    var_first = spec.variables.first
+    var_first = variables.first
     multipliers = []
 
     (1...variables.size).each { |i| multipliers << variables.values[i].dup }
@@ -44,26 +48,52 @@ class ParameterGenerator
 
   private
 
-  def valid_case?(scenario, spec)
-    return true if spec.exclude_clause.nil? && spec.include_clause.nil?
+  def expand_variables(variables)
+    return nil unless variables
 
-    rule_evaluator = RuleEvaluator.new(converters: spec.converters)
+    expanded_variables = {}
+    variables.each do |key, tokens|
+      expanded_variables[key] = if tokens == 'boolean'
+                                  [false, true]
+                                else
+                                  tokens
+                                end
+    end
+    expanded_variables
+  end
+
+  def valid_case?(scenario, spec)
+    return true unless with_optional_clause?(spec)
 
     include_result = true
     unless spec.exclude_clause.nil?
-      exclude_clause = Rule.sanitize(clause: spec.exclude_clause)
-      rule_evaluator.parse(expression: exclude_clause)
-      evaluate_result = rule_evaluator.evaluate(scenario: scenario, rule_token_convert: spec.token_converter)
-      include_result = evaluate_result == 'false'
+      include_result = qualify_secario?(spec, scenario, false)
     end
 
-    return include_result if spec.include_clause.nil? || !include_result
+    return include_result if no_include_or_dont_include?(spec, include_result)
 
-    include_clause = Rule.sanitize(clause: spec.include_clause)
-    rule_evaluator.parse(expression: include_clause)
-    include_result = rule_evaluator.evaluate(scenario: scenario, rule_token_convert: spec.token_converter) == "true"
+    qualify_secario?(spec, scenario, true)
+  end
 
-    include_result
+  # blech!
+  def no_include_or_dont_include?(spec, include_result)
+    spec.include_clause.nil? || !include_result
+  end
+
+  def qualify_secario?(spec, scenario, is_included)
+    action = is_included ? 'include' : 'exclude'
+    rule_evaluator = RuleEvaluator.new(converters: spec.converters)
+    clause = Rule.sanitize(clause: spec.send("#{action}_clause"))
+    rule_evaluator.parse(expression: clause)
+    rule_evaluator.evaluate(
+      scenario: scenario,
+      rule_token_convert: spec.token_converter
+    ) == is_included.to_s
+  end
+
+  # Has an exclude or include clause
+  def with_optional_clause?(spec)
+    !spec.exclude_clause.nil? || !spec.include_clause.nil?
   end
 
   # add all fixtures to the list.
@@ -89,18 +119,15 @@ class ParameterGenerator
       param[:scenario][var_name] = var_value
     end
 
-    param[:expected_outcome] = validator.validate(
-      scenario: scenario,
-      fixture: param
-    )
+    param[:expected] = validator.validate(scenario: scenario, fixture: param)
 
     param
   end
 
   # Detects if rule config has one outcome to one token mapping.
   def one_to_one(outcome_to_clause)
-    outcome_to_clause.each do |outcome, clause|
-      next if clause.is_a?(Array) && clause.size == 1
+    outcome_to_clause.each do |_outcome, clause|
+      next if outcome_to_one_array?(clause)
 
       return false if RuleEvaluator.tokenize(clause: clause).size > 1
     end
@@ -108,53 +135,69 @@ class ParameterGenerator
     true
   end
 
-  # Used to optimize by detecting the variables if rules config is a 1 outcome to 1 rule token.
+  def outcome_to_one_array?(clause)
+    clause.is_a?(Array) && clause.size == 1
+  end
+
+  # Used to optimize by detecting the variables if rules config is a 1 outcome
+  # to 1 rule token.
   def detect_variables(spec_config)
     return nil unless one_to_one(spec_config['rules'])
 
     tokens = spec_config['rules'].values
-    return { vars: tokens.map(&:first) } if tokens.first.is_a?(Array) && tokens.first.size == 1
+    if tokens.first.is_a?(Array) && tokens.first.size == 1
+      return { vars: tokens.map(&:first) }
+    end
 
     { vars: spec_config['rules'].values }
   end
 
   def instantiate_spec(spec_config)
-    if spec_config['variables'].nil?
-      spec_config['variables'] = detect_variables(spec_config)
-    end
-
-    spec = RastSpec.new(
+    RastSpec.new(
       description: spec_config[:description],
       variables: spec_config['variables'],
       rule: Rule.new(rules: spec_config['rules']),
       default_outcome: spec_config['default'] || spec_config['else']
     )
+  end
 
+  def build_spec(spec_config)
+    if spec_config['variables'].nil?
+      spec_config['variables'] = detect_variables(spec_config)
+    end
+
+    spec = instantiate_spec(spec_config)
     pair_config = calculate_pair(spec_config)
     spec.init_pair(pair_config: pair_config) unless pair_config.nil?
 
-    unless spec_config['exclude'].nil?
-      spec.init_exclusion(spec_config['exclude'])
+    configure_include_exclude(spec, spec_config)
+    spec.init_converters(converters: generate_converters(spec_config))
+  end
+
+  def generate_converters(spec_config)
+    converters_config = spec_config['converters']
+    return converters unless converters_config.nil?
+
+    # when no converters defined, we detect if type is consistent, otherwise
+    # assume it's string.
+    default_converter = DefaultConverter.new
+    spec_config['variables'].map do |_key, array|
+      if same_data_type(array)
+        RuleEvaluator::DEFAULT_CONVERT_HASH[array.first.class]
+      else
+        default_converter
+      end
     end
+  end
 
-    unless spec_config['include'].nil?
-      spec.init_inclusion(spec_config['include'])
+  def configure_include_exclude(spec, spec_config)
+    unless spec_config['exclude'].nil?
+      spec.init_exclusion(spec_config['exclude'])
     end
 
-    converters_config = spec_config['converters']
-    converters = if converters_config.nil?
-                   # when no converters defined, we detect if type is consistent, otherwise assume it's string.
-                   default_converter = DefaultConverter.new
-                   spec_config['variables'].map do |_key, array|
-                     if same_data_type(array)
-                       RuleEvaluator::DEFAULT_CONVERT_HASH[array.first.class]
-                     else
-                       default_converter
-                     end
-                   end
-                 end
+    return if spec_config['include'].nil?
 
-    spec.init_converters(converters: converters)
+    spec.init_inclusion(spec_config['include'])
   end
 
   def calculate_pair(spec_config)
@@ -162,19 +205,30 @@ class ParameterGenerator
     return pair_config unless pair_config.nil?
 
     outcomes = spec_config['rules'].keys
-    if outcomes.size == 1
-      if [TrueClass, FalseClass].include?(outcomes.first.class)
-        return { outcomes.first => !outcomes.first }
-      end
+    return {} unless outcomes.size == 1
 
-      if %w[true false].include?(outcomes.first)
-        return { outcomes.first => outcomes.first == 'true' ? 'false' : 'true' }
-      end
+    boolean_pair = boolean_pair(outcomes, spec_config)
+    return boolean_pair if boolean_pair
+
+    default_pair(spec_config)
+  end
+
+  def default_pair(spec_config)
+    outcomes = spec_config['rules'].keys
+    { outcomes.first => spec_config['default'] } if spec_config['default']
+  end
+
+  # refactored out of calculate_pair.
+  def boolean_pair(outcomes, spec_config)
+    return false if spec_config['default']
 
-      return { outcomes.first => spec_config['default'] } if spec_config['default']
+    if [TrueClass, FalseClass].include?(outcomes.first.class)
+      return { outcomes.first => !outcomes.first }
     end
 
-    {}
+    return unless %w[true false].include?(outcomes.first)
+
+    { outcomes.first => (outcomes.first != 'true').to_s }
   end
 
   def same_data_type(array)

data/lib/rast/rast_spec.rb

@@ -12,7 +12,12 @@ class RastSpec
 
   attr_accessor :exclude
 
-  def initialize(description: '', variables: [][], rule: nil, default_outcome: '')
+  def initialize(
+    description: '',
+    variables: [][],
+    rule: nil,
+    default_outcome: ''
+  )
     @description = description
     @variables = variables
     @pair = {}
@@ -37,7 +42,8 @@ class RastSpec
 
     @variables.keys.each_with_index do |key, index|
       @variables[key].each do |element|
-        converter = RuleEvaluator::DEFAULT_CONVERT_HASH[element.class] || converters[index]
+        converter = RuleEvaluator::DEFAULT_CONVERT_HASH[element.class] ||
+                    converters[index]
         @token_converter[element.to_s] = converter
       end
     end