rast 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77e02b108231f3d36dd5e490e9a0ab9cf1334ebb53ae6ffce93cbec2c124423b
-  data.tar.gz: a738c7603f64ec75eff5a13c87fa472d147c1262efb0340d2b500d76fa590826
+  metadata.gz: 3f3ab7d817085dca4c5fc3c3fd0956ca6a6f87eadd9d97554f693aa81908f5e8
+  data.tar.gz: 5e2f9d234c29e5cfc0ccab251980099e13af8c3355d7ea83ad3d8dc8a97ff4c1
 SHA512:
-  metadata.gz: 88fc71ee6789773bd21b743c9e8bafbabc07654fbc2494f65e7b855930f32f686222ffe0ada7ecafeab1a828b9f45f8a9d94debf5ca7c87603edfbf39e10e4b3
-  data.tar.gz: '01409ef86dc48e884d0a4afd8cfa6113c054a4bd70aa19e8d5ab34d0fac5f50119f4e26924634dea6c8e710ba131fc1cfaf79ae07a884a40a48e8e6be2a84346'
+  metadata.gz: 3fe3b7af6cbc40ce1ab44a8120ac66865b262a751a448d382f72a2cc28999ab45761a21a4747b8c362e27e46e06eaf4f34f4cf794fb64951d680621c9b1a1deb
+  data.tar.gz: 1e07f58dd3fa04a7e84b6cf25a4b4956847f1975e21973b4b3ecc62d74c9f28b3676fd7b185224a2a65b0f4eee612efaea92999c8e8dc7dda01f312db1f825c8

data/.travis.yml

@@ -0,0 +1,15 @@
+---
+language: ruby
+rvm:
+  - 2.0.0
+
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+
+script:
+  - bundle exec rspec
+
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change log
 
+## Unreleased
+
+- Add travis-ci build.
+- Add RubyGems badge
+- Update documentation.
+
+## Released
+
+
+- 0.19.0 - [feature] boolean in variables definition to automatically infer
+           false and true
+           [feature] xrast to skip entire test.
+           [feature] Add default outcome in yaml-less configuration. Default
+           config will take higher precedence than boolean outcomes.
 - 0.18.0 - [feature] xspec to skip a test
          - [feature] Added include rule to isolate scenarios.
          - [feature] Asterisk can be used as token character.

data/Documentation.md

@@ -0,0 +1,297 @@
+# Documentation
+
+## The YAML File
+
+YAML is the preferred because it simplifies the content of the spec file. YAML contains the variables that affect the outcome, and the expected outcome based on rules that involve the said variables.
+
+```yaml
+specs:
+  # spec key uniquely identifies a spec. It has to match the ID when the spec
+  # block is invoked in the ruby spec file. Usually the method name.
+  spec_key:
+    description: Spec Description
+
+    variables:
+      param1: [one, two]
+
+    outcomes:  # required (dictionary)
+      true: one[0]  # sample outcome.
+
+    default: DEFAULT  # optional (scalar) fall off value.
+```
+
+### Using a subscript when variables clash
+
+A subscript may be used in cases where a variable token used multiple times.
+In the example below, the left variable has the subscript of `0`, and the right variable have the subscript of `1`.
+
+[logic_checker_spec.yml](./spec/examples/rast/logic_checker_spec.yml)
+
+```yaml
+specs:
+  Logical AND:
+    variables:
+      left: [false, true]
+      right: [false, true]
+    outcomes: {true: 'true[0] & true[1]'}
+
+  Logical OR:
+    variables:
+      left: [false, true]
+      right: [false, true]
+    outcomes: {true: 'true[0] | true[1]'}
+
+  Logical XOR:
+    variables:
+      left: [false, true]
+      right: [false, true]
+    outcomes: {true: 'false[0] & true[1] | true[0] & false[1]'}
+```
+
+### Isolating scenarios
+
+For troubleshooting purposes, you can use the `include` attribute to focus on one or more scenarios.
+
+```yaml
+---
+specs:
+  '#positive?':
+    variables: {number: [-1, 0, 1]}
+    outcomes: {true: 1}
+    include: 0
+```
+
+Running `rspec -fd` will result to
+
+```
+Positive: #positive?, ONLY: '0'
+  [false]=[number: 0]
+
+Finished in 0.00292 seconds (files took 0.26024 seconds to load)
+1 example, 0 failures
+```
+
+
+### Filtering Out Invalid Cases
+
+In a prior example `HotelFinder`, some cases are invalid. For example, if an
+ aircon is not available, then it makes to sense to check if it is operational
+ not. In such case, we should limit the scenarios with `exclude` clause.
+
+```yaml
+# double_example_spec.yml
+---
+specs:
+  '#applicable?':
+    variables:
+      Air Conditioning: [false, true]
+      Security: [false, true]
+      Operational: [false, true]
+      Security Grade: [basic, advanced, diplomat]
+
+    # If airconditioning is false, it does not make sense to test if it is
+    # operational. We limit the invalid scenarios to at most 1, so that
+    # a scenario where airconditioning is false will still be tested.
+    exclude: false[0] & false[2] | false[1] & !basic
+    outcomes: {PASSED: 'true[0] & true[1] & true[2] & diplomat'}
+    else: INADEQUATE
+```
+
+### Using a default outcome
+
+Defining the rules to outcomes can be the most time consuming part of the process
+ especially for complex tests. If this example, we can remove the `ERROR` outcome
+ and replace it with `default: ERROR` so that any scenario that don't fall into
+ any of the defined outcomes, will result to the default.
+
+```yaml
+---
+specs:
+  '#prime?':
+    variables:
+      number: [-4, -1, 0, 1, 2, 3, 4, 5, 3331, 5551]
+
+    outcomes:
+      true: 2 | 3 | 5 | 3331
+      false: 1 | 4 | 5551
+      # ERROR: -4 | -1 | 0
+    default: ERROR
+```
+
+Here is another simplified example of the above.  In case the outcome is of
+ boolean type, we can omit the `default` altogether.
+```yaml
+---
+specs:
+  '#prime?':
+    variables:
+      number: [1, 2, 3, 4, 5, 3331, 5551]
+
+    outcomes:
+      true: 2 | 3 | 5 | 3331
+```
+The outcome will now be either `true` or `false`. Do note that the variables
+ list have been simplified and does not check negative numbers for demo
+ purpose only.
+
+### Optional variables for 1 to 1 outcomes.
+
+`variables` definition can be omitted when each outcome matches each variables.
+
+```yaml
+---
+specs:
+  '#person_name':
+    outcomes:
+      Will.I.Am: musician
+      Ford: soldier
+      John: personal
+```
+
+### Detecting invalid rule where a scenario matches multiple outcomes
+
+In this example, the scenario `1` is defined to result in both `true`, and
+`false`, which is impossible.
+
+```yaml
+---
+specs:
+  '#positive?':
+    variables: {number: [-1, 0, 1]}
+    outcomes: {true: 1, false: 1 | -1 | 0}
+```
+
+It will result in an error.
+
+```
+RuntimeError:
+  #positive? [1] must fall into a unique rule outcome/clause, matched: ["true", "false"]
+```
+
+In the same way if a scenario does not fall into any outcome, a similar error
+will be displayed.
+
+```
+RuntimeError:
+  #positive? [1] must fall into a unique rule outcome/clause, matched: []
+```
+
+### Using special characters as part of variable tokens.
+
+An array may be used as variable token, this will allow for the special
+ characters like `!` to be used as part of the token without confusing the rule
+ engine.
+
+```yaml
+---
+specs:
+  '#identify_sentence_type':
+    variables:
+      - "Let's do it!"
+      - "Will this work?"
+      - "Let's make a statement"
+...
+
+```
+
+The rules must then be written in a different way, as arrays.
+
+```yaml
+...
+    outcomes:
+      exclamation: ["Let's do it!"]
+      question: ['Will this work?']
+      statement: ["Let's make a statement"]
+```
+
+If an operation is involved:
+
+```yaml
+outcomes:
+  non-question: ["Let's do it!", '|', "Let's make a statement"]
+```
+
+## The spec file
+
+### Stubbing
+
+In this example, stubbing is done as you normally would. A `prepare` block is an
+ optional block to organize the parts of the test into preparation and execution
+ parts.
+
+[worker_spec.rb](./spec/examples/worker_spec.rb)
+
+```ruby
+# spec/examples/worker_spec.rb
+rast Worker do
+  spec '#goto_work?' do
+    prepare do |day_type, dow|
+      allow(subject).to receive(:day_of_week) { dow.to_sym }
+      allow(subject).to receive(:holiday?) { day_type == 'Holiday' }
+    end
+
+    execute { subject.goto_work? ? :Work : :Rest }
+  end
+end
+```
+
+### Using a factory
+
+See [examples/factory_example.rb](./examples/factory_example.rb)
+
+```ruby
+rast FactoryExample do
+  spec '#person_name' do
+    prepare do |service_type|
+      subject.instance_variable_set(:@person, build(service_type.to_sym))
+    end
+
+    execute { subject.person_name }
+  end
+end
+```
+
+### Using doubles
+
+Suppose we have a HotelFinder class that has a dependency to air conditioning
+ and security
+
+ ```ruby
+ rast HotelFinder do
+   spec '#applicable?' do
+     prepare do |with_ac, is_opererational, with_security, security_grade|
+       if with_ac
+         allow(subject)
+           .to receive(:aircon) { double(operational?: is_opererational) }
+       end
+
+       if with_security
+         allow(subject)
+           .to receive(:security) { double(grade: security_grade.to_sym) }
+       end
+     end
+
+     execute { subject.applicable? ? :PASSED : :INADEQUATE }
+   end
+ end
+
+ ```
+
+### Spec file without yaml
+
+If a single spec is preferred, like in cases where it's much simplier,
+ the required configuration can be written with similar name except for the
+ `inclusion` and `exclusion`.  The difference is due to the name clash with the
+ `include` keyword in ruby.
+
+```ruby
+rast Positive do
+  spec '#positive?' do
+    variables({ number: [-1, 0, 1, 2, 3] })
+    outcomes(true: 1)
+    inclusion('!3')
+    exclusion(2)
+    execute { |number| subject.positive?(number) }
+  end
+end
+```

data/Gemfile

@@ -4,13 +4,11 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-
 group :development, :test do
   gem 'factory_girl', '~> 4.7'
 end
 
 group :test do
-
   gem 'listen', '>= 3.0.8'
   gem 'lumberjack', '~> 1.0', '>= 1.0.13'
   gem 'rb-inotify', '~> 0.9.10'

data/Getting-Started-Detailed.md

@@ -0,0 +1,122 @@
+# Getting Started (WIP)
+
+
+## Tutorials
+
+
+
+### Writing a simple test.
+
+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
+```
+
+- On line: 1, the library is required:
+
+```ruby
+require 'rast'
+```
+
+- On line: 3, invoke the DSL:
+
+```ruby
+rast Positive do
+```
+`Positive` is the fully qualified name of the class or the module to be tested.
+
+- On line: 4, define the first spec:
+
+```ruby
+  spec 'Is Positive Example' do
+```
+
+`'Is Positive Example'` is a descriptive identifier for the test. It can be the name of the method like `#positive?`.
+
+- On line: 5, define the `execute` block..
+
+```ruby
+execute { |number| subject.positive?(number) }
+```
+
+There is a lot going on here.<br>
+- Inside the block, we define how our subject will be invoked. The `positive?` method is invoked on the `subject`
+accepting a parameter.
+- Block parameter `number` will contain the test scenario we want to execute. More on this later. Just know that whichever values are passed here, the `subject` has to be able to handle it correctly.
+- `subject` is an instance of the module or class that we defined on line: 3.
+- And lastly, `execute` block expects a return value that will be verified when the spec is run.
+
+#### Step 2: Defining outcomes and the variables that affects the test.
+
+For the sake of simplicity, we will define the variables and outcomes in a separate yaml file, mainly because the next
+steps are purely configurations. Using yaml is completely optional.
+
+Create a folder `rast` in the same level as the spec file:
+
+- spec
+    - rast
+
+Create a yaml file with the same name as the spec, but with `.yml` extension.
+
+`spec/rast/positive_spec.yml` would contain:
+
+```yaml
+specs:
+  Is Positive Exaple:
+    variables: {number: [-1, 0, 1]}
+    outcomes: {true: 1}
+```
+
+- On line: 1 is the root configuration element `specs` that will contain one or more specs.
+- On line: 2 `Is Positive Example` is the spec identifier, this must match what we've defined on `positive_spec.rb:4`
+- On line: 3, The variables that affect the SUT are defined, in this case there is only one variable called `number`,
+which has 3 different possibilities `-1`, `0`, and `1`.
+- On line: 4, This is where outcome to rule mapping is defined.
+
+### The implementation file
+
+positive.rb will have:
+
+```ruby
+class Positive
+  def positive?(number)
+    number > 0
+  end
+end
+```
+
+## How To's
+
+### Use token subscript when there's a variable token clash.
+
+In cases where multiple variables, `left` and `right`, has the same set of tokens `false` and `true`:
+
+```yaml
+    variables:
+      left: [false, true]
+      right: [false, true]
+```
+
+We need a way to uniquely identify the tokens in the `outcomes` configuration. We can do so by using a subscript in the format: `token[n]`
+For Example:
+
+```yaml
+outcomes: {true: 'true[0] & true[1]'}
+```
+
+The subscript `0` would refer to the `true` token in the `left` variable and subscript `1` would refer to the `true`
+token in the `right` variable.
+
+
+## References
+
+### Outcomes

data/Getting-Started.md

@@ -1,26 +1,12 @@
-# Getting Started
+# Getting Started (WIP)
 
-
-
-## Tutorials
-
-
-
-### Writing a simple test.
+### A Basic Example
 
 Suppose we want to create a class that checks if a number is a positive number or not.
 
-#### Step 1: Defining how to exercise the system under test.
-
-Start by creating a spec file inside your `spec` folder, let's call it `positive_spec.rb`
-
-- spec
-    - positive_spec.rb
+#### Create a spec file `spec/positive_spec.rb`
 
-
-`positive_spec.rb` would look like this:
-
-```
+```ruby
 require 'rast'
 
 rast Positive do
@@ -30,72 +16,19 @@ rast Positive do
 end
 ```
 
-- On line: 1, the library is required:
-
-```
-require 'rast'
-```
-
-- On line: 3, invoke the DSL:
-
-```
-rast Positive do
-```
-`Positive` is the fully qualified name of the class or the module to be tested.
-
-- On line: 4, define the first spec:
-
-```
-  spec 'Is Positive Example' do
-```
-
-`'Is Positive Example'` is a descriptive identifier for the test. It can be the name of the method like `#positive?`.
-
-- On line: 5, define the `execute` block..
-
-```
-execute { |number| subject.positive?(number) }
-```
-
-There is a lot going on here.<br>
-- Inside the block, we define how our subject will be invoked. The `positive?` method is invoked on the `subject`
-accepting a parameter.
-- Block parameter `number` will contain the test scenario we want to execute. More on this later. Just know that whichever values are passed here, the `subject` has to be able to handle it correctly.
-- `subject` is an instance of the module or class that we defined on line: 3.
-- And lastly, `execute` block expects a return value that will be verified when the spec is run.
-
-#### Step 2: Defining outcomes and the variables that affects the test.
-
-For the sake of simplicity, we will define the variables and outcomes in a separate yaml file, mainly because the next
-steps are purely configurations. Using yaml is completely optional.
-
-Create a folder `rast` in the same level as the spec file:
-
-- spec
-    - rast
+#### Create a spec configuration `spec/rast/positive_spec.yml`
 
-Create a yaml file with the same name as the spec, but with `.yml` extension.
-
-`spec/rast/positive_spec.yml` would contain:
-
-```
+```yaml
 specs:
   Is Positive Exaple:
     variables: {number: [-1, 0, 1]}
     outcomes: {true: 1}
 ```
 
-- On line: 1 is the root configuration element `specs` that will contain one or more specs.
-- On line: 2 `Is Positive Example` is the spec identifier, this must match what we've defined on `positive_spec.rb:4`
-- On line: 3, The variables that affect the SUT are defined, in this case there is only one variable called `number`,
-which has 3 different possibilities `-1`, `0`, and `1`.
-- On line: 4, This is where outcome to rule mapping is defined.
-
-### The implementation file
+The class to test:
 
-positive.rb will have:
-
-```
+```ruby
+# positive.rb
 class Positive
   def positive?(number)
     number > 0
@@ -103,37 +36,21 @@ class Positive
 end
 ```
 
-## How To's
+Running the test:
 
-### Use token subscript when there's a variable token clash.
+`$ rspec -fd spec/examples/positive_spec.rb` 
 
-In cases where multiple variables, `left` and `right`, has the same set of tokens `false` and `true`:
+Test result:
 
 ```
-    variables:
-      left: [false, true]
-      right: [false, true]
-```
-
-We need a way to uniquely identify the tokens in the `outcomes` configuration. We can do so by using a subscript in the format: `token[n]`
-For Example:
+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
 ```
-outcomes: {true: 'true[0] & true[1]'}
-```
-
-The subscript `0` would refer to the `true` token in the `left` variable and subscript `1` would refer to the `true` 
-token in the `right` variable.  
-
-
-## References
-
-### Outcomes
-
-
-## Current Limitations.
-
-
-
 
+## How To's