speq 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d4e8796522782ab6e954f384d21d6b6d1d5e6728c773c68e587873f4183173e
-  data.tar.gz: f0e4a46ce5889abf250761d4f990a43a61792c6bade4e30e88fd7e9c45869699
+  metadata.gz: efc22fe2da50ca215a4ca412a768e04e70fe97ff535d50ab8bd38cf918676fbf
+  data.tar.gz: 2daeaccd796d8eaa2fd8369495675ffd7df8171fb7bdaed2529a781dfeb4544d
 SHA512:
-  metadata.gz: 9a08b7857d12e9b57af750fb35db681884a7af03a6224424abf659ad2eb4fde5353c8dbb3b873ab6c9f0ed6ac90ae4732338150748def36ddda786ad1921845f
-  data.tar.gz: e4ac157417ac3cda5a872b1b13a39ece575d437b10ea8fbca320d71ab383b255ca66be76085ce07bc3f20054d796dacfe17ad9a855632b10b44e21fe67c26681
+  metadata.gz: c6ed8070160429f4fa4badfda408e09a5d95900f5df0b6a3014c09a85496aa5ca6baca3efb76d0bff9b2ff9211b234133512df8d300ab833b4bd707831b53479
+  data.tar.gz: c61f81ead1d0e33220cd0e0697376a28cb4be9db73156670d4ab1d945cb06c491e13b27d105535470c552428f27a0b7eeaebfeb99963b565269026709790486b

data/.ruby-version

@@ -0,0 +1 @@
+2.6.5

data/.travis.yml

@@ -3,5 +3,5 @@ sudo: false
 language: ruby
 cache: bundler
 rvm:
-  - 2.5.1
-before_install: gem install bundler -v 1.16.6
+  - 2.6.5
+before_install: gem install bundler -v 1.17.2

data/README.md

@@ -1,5 +1,7 @@
 # Speq
 
+**Ready to use! Issue reports are welcome!**
+
 ## Build specs with fewer words
 
 Speq is a testing library for rapid prototyping in Ruby.
@@ -7,18 +9,8 @@ Speq is a testing library for rapid prototyping in Ruby.
 Speq favors simplicity and minimalism.
 
 ```ruby
-is(Array.new).empty?
-# Passed (1/1)
-#   [] is empty.
-```
-
-But also values flexibility.
-
-```ruby
-speq(Array(nil), 'an array created by calling Array(nil)').eq?([nil])
-
-# Failed (1/1)
-#   An array created by calling Array(nil) is NOT equal to [nil]. ( [] != [nil] )
+is([]).empty?
+#  ✔ [] is empty.
 ```
 
 Speq is ideal whenever it would feel excessive to use one of the existing frameworks, but it's not enough to just print & inspect outputs.
@@ -33,271 +25,55 @@ gem 'speq'
 
 And then execute:
 
-    bundle
-
-Or install it yourself as:
-
-    gem install speq
-
-## Design & Syntax
-
-Speq is loosely based on the given-when-then or arrange-act-assert testing pattern. Speq's design choices are guided by the competing motivations of having tests be as short and simple as possible while maintaining the flexibility to be as descriptive as needed.
-
-In contrast to similar tools, speqs are typically framed as _questions_ about a program's behavior rather than assertions about the desired behavior. The most basic test involves passing a string to the method `speq` followed by `pass?` and a block that evaluates strictly to true or false.
-
-```ruby
-speq("Does Ruby properly calculate Euler's identity?").pass? do
-  e = Math::E
-  π = Math::PI
-  i = (1i)
-
-  e**(i*π) + 1 == 0
-end
-
-# Passed (1/1)
-#   Testing 'does Ruby properly calculate Euler's identity?' passes.
-```
-
-The above works, but it's not much shorter than existing solutions. More importantly, it's missing vital information about what action was taken, what the outcome was, and what assertion led to the success.
-
-Shown below is the basic two-part pattern for most speqs and the resulting report combining explicit and implicit descriptions:
-
-```ruby
-speq(Math::E**((1i) * Math::PI ) + 1, 'e^iπ + 1').eq?(0)
-# Passed (1/1)
-#     e^iπ + 1 is equal to 0. ( (0.0+0.0i) == 0 )
-```
-
-### Actions
-
-Descriptions for simple unit tests are often closely tied to the source code, and as such, Speq tries to eliminate them wherever possible. To automatically generate descriptions, the action or subject of interest is supplied to be evaluated dynamically.
-
-More specifically, we begin by setting up the program state and then explicitly supply the action being tested using the methods below. By breaking down the expression's method/message, arguments, and receiver, Speq can use the additional information to help generate an often sufficiently detailed description of the test. Actions are evaluated when they reach a [matcher](#matchers).
-
-- message: `does(*:symbol` or `is(*:symbol)`, default: `:itself`
-- arguments: `with(...)` or `of(...)`, default: `*[]`
-- receiver: `on(object, description(optional))`, default: `Object`
-
-```ruby
-is(:prime?).of(2).true?
-
-on((1..4).to_a.reverse).does(:sort).eq?([1, 2, 3, 4])
-
-# .with() accepts arguments with the exact same format as any other method
-does(:map).with { |idx| idx * idx }.on(0..3).eq?([0, 1, 4, 9])
-
-# Passed (3/3)
-#   prime? of 2 is true.
-#   sort on [4, 3, 2, 1] equals [1, 2, 3, 4].
-#   map with a block on 1..4 equals [0, 1, 4, 9].
-```
-
-Chaining methods can be accomplished by providing multiple symbols. If an intermediate value needs to be tested or a method needs to be given arguments, this can be accomplished by using `.then(:next_method).with`. An example of this is shown below. An alternative, unconventional syntax for accomplishing the same can be found in the section on [syntactic sugar](#Sugar)
-
-```ruby
-on(1..4)
-  .does(:to_a, :shuffle, :sort)
-  .eq?([1, 2, 3, 4])
-  .then(:sort).with { | a, b | b <=> a }
-  .eq?([4, 3, 2, 1])
-
-# Passed (1/1)
-#   to_a on 1..4 then reverse (on [1, 2, 3, 4]) then sort (on [4, 3, 2, 1]) equals [1, 2, 3, 4].
+```sh
+bundle
 ```
 
-### Matchers
-
-All speq methods that end with a question mark are matchers.
-
-The matcher `pass?` is the most general and simply expects to be given a code block that evaluates to true or false. The output from the action is passed along as the first piped variable.
-
-```ruby
-does(:strip)
-  .on(' speq ')
-  .pass? { |str|  str == 'speq' && !str.include?(' ') }
-
-does(:rand)
-  .pass? { |val| val.is_a?(Float) }
-
-does(:prime?)
-  .with(-1)
-  .raise?('Prime is not defined for negative numbers')
-
-on(User)
-  .does(:new)
-  .with(id: 1, name: 'user name')
-  .have?(:id)
-```
-
-#### Prefixes and Compound Matchers
-
-Multiple matchers can follow an action. By default, all matchers must pass for the test to be considered successful. To run multiple tests on the same action, see the section on [test subjects](#subjects)
-
-The logical inverse of any matcher can be achieved by prefixing the matcher with `not_`.
-
-```ruby
-# Equivalent to the previous speq
-does(:strip).on(' speq ').not_include?(' ').eq?('speq')
-```
-
-For simple combinations, it's sufficient to prefix the second matcher with one of the following: `or_, nand_, nor_, xor_, xnor_`
-
-```ruby
-arr = Array.new(10, rand.round)
-speq(arr, '10 element array filled with zeros or ones').has?(length: 100).all?(0).or_all?(1)
-
-# arr.length == 100 && (arr.all?(0) || arr.all?(1))
-```
-
-Although it's best to avoid complex combinations of matchers, logical operators can be combined unambiguously if absolutely needed by chaining operators with prefix notation.
-
-```ruby
-default = rand.round(1) <=> 0.5
-length = default.zero? ? 0 : 100
+Or install it yourself as:
 
-arr = Array.new(length, default)
-speq(arr, 'Either empty, all 1, or all -1').or?.empty?.xor?.include?(-1).include?(1)
+```sh
+gem install speq
 ```
 
-#### Generated & built-in matchers
-
-If the object being tested responds to the method ending with `?`, then an appropriate matcher is automatically generated. As a result, existing methods such as `instance_of?`, `nil?`, or `empty?` can be used despite the fact that they are not in the list below.
-
-```ruby
-pass?(*description, &block)
-has?(*:message, **(message: val)) # alias: have?
-
-eq?(obj)   # result == obj
-case?(obj) # obj === result
-
-true?
-false?
-truthy?
-falsy?
-
-raise?('The following error message')
-raise?(ErrorClass)
+## Design & Syntax
 
-# Compound matchers
-either?(*matcher)  # matcher1 || matcher2 || ...
-neither?(*matcher) # !matcher1 || !matcher2 ||  ...
+Speq's design choices are guided by the competing motivations of having tests be as short and simple as possible while maintaining the flexibility to be as descriptive as needed. In contrast to similar tools, speqs are typically framed as _questions_ about a program's behavior rather than assertions about the desired behavior.
 
-```
+Descriptions for simple unit tests are often closely tied to the source code, and as such, Speq tries to eliminate them wherever possible. By breaking down an expression's method/message, arguments, and receiver, Speq can use the additional information to help generate an often sufficiently detailed description of the test.
 
-#### Matcher name precedence
+- receiver: `on(object [, description])`
+- message: `does(symbol [, description])`
+- arguments: `with(*args , &block)` or `of(*args, &block)`
+- question: `*?(*args, &block)`
 
-Parsing the name of a matcher gives highest precedence to the object being tested. For example, consider the following test:
+Note that Speq executes expressions immediately, avoiding the unintuitive execution order of most testing libraries.
 
 ```ruby
-class Display
-  attr_reader :type
-
-  def initialize(type = :case)
-    @type = type.to_sym
-  end
+speq('Example test') do
+  on((1..4).to_a.shuffle, 'a shuffled array').does(:sort).eq?([1, 2, 3, 4])
 
-  def case?
-    @type == :case
+  does(:reverse) do
+    on('3 2 1').eq?('1 2 3')
+    on([3, 2, 1]).eq?([1, 2, 3])
   end
-end
-
-window_display = Display.new('window')
-
-speq(window_display).not_case? # Will use Display#case
-on(window_display).is(:type).case?(Symbol) # Will use Speq#case?
-```
-
-To resolve `not_case?`, speq will do the following:
-
-1. Checks for the prefix `speq_`, reserved in case of name conflicts.
-2. Generates a matcher if the object responds to `not_case?`.
-3. Generates a matcher if the object responds to `case?` and applies prefixes.
-4. Uses the built-in `case?` and applies prefixes.
-
-### Additional Functionality
-
-#### Object Descriptions
-
-It may be advantageous to describe an object in advance such that, from there on, the report will automatically include the object description anytime that object is encountered.
-
-```ruby
-MyClass = Class.new
-
-call(MyClass, 'my class, an instance of the class Class')
-speq(MyClass).instance_of?(Class)
-
-# call tracks both object identity and object equality
-my_arr = []
-call(my_arr, 'a specific empty array')
-call([], 'an empty array')
-
-speq(my_arr).eq?([])
-
-# Passed (2/2)
-#  'my class, an instance of the class Class' is an instance of the class Class.
-#  'my specific empty array' equals 'an empty array'
-```
-
-#### Fakes
 
-Fakes are Speq's simple implementation of a test double. Most closely resembling a stub, fakes provide canned or computed responses, allowing for additional test isolation for objects that rely on objects not within the scope of testing.
+  with(&->(idx) { idx * idx }).does(:map).on(0..3).eq?([0, 1, 4, 9])
 
-```ruby
-fake_bank = fake(
-  balance: 5000,
-  print_balance: '$50.00',
-  withdraw: proc {|amount| [50, amount].min }
-)
-```
-
-#### Subjects
-
-Speq has the distinct advantage of making it particularly easy to run many similar tests on the same subject.
-Opening a block on an action that has not been clo
-
-```ruby
-not_prime = [0, 1, 4, 6, 8, 9]
-prime = [2, 3, 5, 7]
-
-#
-does(:prime?) do
-  with[not_prime].false?
-  with[prime].true?
-end
-
-does(:my_sort) do
-  small_array = [3, 2, 1]
-  large_array = Array.new(10**6) {rand}
-
-  on(small_array).eq?(small_array.sort)
-  on(large_array).eq?(large_array.sort)
+  is(:rand).a?(Float) # symbol -> does
+  is([]).empty? # not symbol -> on
 end
 ```
 
-#### Sugar
-
-```ruby
-# Action-Question Chains
-on('3 2 1')
-  << :split
-  << has?(length: 3)
-  << :map << with(&:to_i)
-  << :reduce << with(&:+)
-  << eq?(6)
-
-# Can start with the usual syntax and switch when convenient
-on(1..4).does(:to_a, :shuffle, :sort).eq?([1, 2, 3, 4])
-  << :sort << with { | a, b | b <=> a } << eq?([4, 3, 2, 1])
-
-# Broadcasting
-def add(a, b)
-  a + b
-end
-
-a = [1, 2, 3]
-b = [4, 5, 6]
-
-does(:add).with[a, b].eq?([5, 7, 9])
+```
+✔ Example test
+  ✔ sort on a shuffled array equals [1, 2, 3, 4].
+  ✔ reverse...
+    ✔ "3 2 1" equals "1 2 3".
+    ✔ [3, 2, 1] equals [1, 2, 3].
+  ✔ map(&{ ... }) on 0..3 equals [0, 1, 4, 9].
+  ✔ rand is a Float.
+  ✔ [] is empty.
+pass: 5, fail: 0, errors: 0
 ```
 
 ## Usage
@@ -312,7 +88,7 @@ To run individual files, specify a list of speq file prefixes. For example, to r
 
     speq example sample
 
-Speq files only `require 'speq'` by default, so any external code being tested will still need to be required.
+Note that you don't need to require 'speq' within a speq file if running from the CLI.
 
 ### Anywhere: Speq.test
 
@@ -321,37 +97,11 @@ Speq can be used anywhere as long as it is required and all tests are written wi
 ```ruby
 require 'speq'
 
-Speq.test(self) do | context |
-  # You can pass the surrounding context if needed.
-  # Calling 'report' prints the tests seen so far to $stdout.
-
-  # By default, Speq.test Returns the instance of Speq::Test created here.
-  # Using the return keyword, you can choose to return the following instead:
-  # 'return score': returns the proportion of tests passed as a Rational number
-  # 'return pass?': returns true or false for whether all the tests passed
-end
-```
-
-Speq can also be included to be used in a more direct manner. Here is an example of using Speq within another class for added functionality.
-
-```ruby
-require 'speq'
-
-class Exam
-  include Speq
-
-  def initialize(questions)
-    @questions = questions
-  end
-
-  def grade
-    @questions.each do | question |
-      speq(question.response, question.to_s).eq?(question.answer)
-    end
-
-    score
-  end
+speq("testing anywhere") do
+  ...
 end
+# '.score': returns the proportion of tests passed as a Rational number
+# '.pass?': returns true or false for whether all the tests passed
 ```
 
 ## Contributing

data/bin/console

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'pry'
-
-require 'speq'
-include Speq
+load 'speq.rb'
+load 'speq/cli.rb'
 
 Pry.start

data/exe/speq

@@ -1,3 +1,7 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'speq'
 require 'speq/cli'
-Speq::CLI.new(ARGV)
+
+Speq::CLI.run_and_report(ARGV)

data/lib/speq/cli.rb

@@ -1,24 +1,45 @@
-require 'speq'
+# frozen_string_literal: true
+
 require 'find'
-require 'colorize'
+require 'date'
+require 'pry'
 
-# Provides a CLI for running Speq
 module Speq
-  class CLI
-    def initialize(cli_args)
-      @files = find_files(cli_args)
-      run
+  # Includes useful methods for running Speq from a CLI
+  module CLI
+    def self.run(cli_args)
+      run_tests(find_files(cli_args))
+    end
+
+    def self.run_and_report(cli_args)
+      print_report(run(cli_args))
+    end
+
+    def self.run_tests(paths)
+      paths.map { |file| file_test(file) }
+    end
+
+    def self.file_test(file)
+      speq(file_description(file)) { instance_eval(File.read(file), file) }
     end
 
-    def find_files(file_prefixes)
-      file_prefixes << '*' if file_prefixes.empty?
+    def self.file_description(path)
+      path
+        .split('/').last
+        .delete_suffix('_speq.rb')
+        .split('_')
+        .map(&:capitalize)
+        .join(' ')
+    end
 
-      Dir.glob("#{Dir.pwd}/**/{#{file_prefixes.join(',')}}_speq.rb")
+    def self.find_files(cli_args)
+      prefixes = cli_args.empty? ? ['*'] : cli_args
+      glob_pattern = "#{Dir.pwd}/**/{#{prefixes.join(',')}}_speq.rb"
+      Dir.glob(glob_pattern)
     end
 
-    def run
-      @files.each { |file| Speq.module_eval(File.read(file), file) }
-      Speq.report
+    def self.print_report(tests)
+      puts tests
     end
   end
 end

data/lib/speq/question.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'speq/values'
+
+module Speq
+  # Error class for Question
+  class QuestionError < StandardError
+    def initialize(question_name, error)
+      super("#{question_name}: #{error}")
+    end
+  end
+
+  # Records the question name, result, and constructs the corresponding matcher
+  class Question
+    def self.question?(method_name)
+      method_name.to_s.end_with?('?')
+    end
+
+    attr_reader :question_name, :matcher, :result
+
+    def initialize(question_name, result, matcher)
+      @question_name = question_name
+      @result = result
+      @matcher = matcher
+    end
+
+    def phrase
+      matcher.phrase(result)
+    rescue StandardError => e
+      QuestionError.new(@question_name, e.inspect).to_s
+    end
+
+    def outcome
+      matcher.match?(result) ? Outcome.pass : Outcome.fail
+    rescue StandardError
+      Outcome.error
+    end
+
+    def self.for(result, question_name, *args, &block)
+      matcher = Matcher.for(question_name, *args, &block)
+
+      Question.new(
+        question_name,
+        result,
+        matcher
+      )
+    end
+  end
+
+  # Boolean #match? for a given result and descriptive phrase
+  class Matcher
+    def initialize(matcher, pass_phrase, fail_phrase)
+      @matcher = matcher
+      @pass_phrase = pass_phrase
+      @fail_phrase = fail_phrase
+    end
+
+    def match?(actual)
+      @matcher[actual]
+    end
+
+    def phrase(actual)
+      @matcher[actual] ? @pass_phrase : @fail_phrase
+    end
+
+    def self.matcher_is(match, thing)
+      new(match, "is #{thing}", "is not #{thing}")
+    end
+
+    def self.for(question_name, *args, &block)
+      if respond_to?(question_name)
+        send(question_name, *args, &block)
+      else
+        result_matcher(question_name, *args, &block)
+      end
+    end
+
+    def self.match?(description, &block)
+      new(block, "matches #{description}", "does not match #{description}")
+    end
+
+    def self.result_matcher(question_name, *args, &block)
+      new(
+        lambda do |obj|
+          if obj.respond_to?(question_name)
+            return obj.send(question_name, *args, &block)
+          end
+
+          raise "No question called #{question_name.inspect} or existing method on #{obj.inspect}"
+        end,
+        "is #{question_name[0..-2]}",
+        "is not #{question_name[0..-2]}"
+      )
+    end
+
+    def self.eq?(expected_value)
+      new(
+        ->(result) { expected_value == result },
+        "equals #{expected_value.inspect}",
+        "does not equal #{expected_value.inspect}"
+      )
+    end
+
+    def self.true?
+      matcher_is(->(result) { result == true }, 'true')
+    end
+
+    def self.truthy?
+      matcher_is(->(actual_value) { actual_value ? true : false }, 'truthy')
+    end
+
+    def self.falsy?
+      matcher_is(->(actual_value) { actual_value ? false : true }, 'falsey')
+    end
+
+    def self.a?(type)
+      matcher_is(->(val) { val.is_a?(type) }, "a #{type}")
+    end
+
+    def self.have?(*symbols, **key_value_pairs)
+      new(
+        lambda do |object|
+          symbols.each do |symbol|
+            return false unless object.respond_to?(symbol)
+          end
+          key_value_pairs.each do |key, value|
+            return false unless object.send(key) == value
+          end
+        end,
+        "has #{symbols.empty? ? nil : symbols}#{key_value_pairs}",
+        "doesn't have #{symbols.empty? ? nil : symbols}#{key_value_pairs}"
+      )
+    end
+
+    def self.raise?(expected_except)
+      case expected_except
+      when Class
+        raise_class(expected_except)
+      when String
+        raise_message(expected_except)
+      else
+        raise ArgumentError
+      end
+    end
+
+    def self.raise_class(expected_error)
+      Matcher.new(
+        ->(actual_except) { actual_except.class <= expected_error },
+        "raises #{expected_error}",
+        "does not raise #{expected_error}"
+      )
+    end
+
+    def self.raise_message(expected_message)
+      Matcher.new(
+        ->(actual_except) { actual_except.message == expected_message },
+        "raises #{expected_message.inspect}",
+        "does not raise #{expected_message.inspect}"
+      )
+    end
+  end
+end