object_protocol 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22d8c5fa9114c23a89499e798c017b41402b0f10f45ffc53236db31222035e0c
-  data.tar.gz: e076ce8bd8b02a476f723b7cfe188ca66f6901e2d0e123b0a3210ddbd276c50c
+  metadata.gz: dd7f3c31f616d5f7d1d1e41c6aa8414dc0aa07b175f587e692878453d9735166
+  data.tar.gz: 43e98c4fa8a3f5efeb4dffe1eaf41e353dac9628b1ede3748ad3c8b79d7ab5de
 SHA512:
-  metadata.gz: 7df2d672dff3d0467c2ef90e0adda6196d2d255638b7f73f1d15cb5dbe7e18459851f0305d8975abee91348453fa4e29f56f059e213d1e2f2ad3f76c9f6cd753
-  data.tar.gz: fcc960d6e186b61093cf4ff2ea6487257e0ce813cc77af1ce3aff2c075af850e10e40bd4da9856cf7a5a8f7862c53cd6b247290d48ad8772c599f51fc9aeedf7
+  metadata.gz: a9af361219c6a9ee45684da4f7cc6196703827f2aa75ecd0562432f88ec47329759c027aaac141b24135be0f4cb23fa9a6733448bedcf6d4215173c0a3052063
+  data.tar.gz: 9a88fd2277328dfc311c350ee1c491fb25d5eb9470060593e2f25c68bec2e1cffc342b64f775c1fbb283ac6acad5a03b5594a8e573a6a19a1caff9a6ca53ce5f

data/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+/spec/examples.txt
 
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -1,12 +1,15 @@
 ## ROADMAP
 
 * in_order
-* in_any_order
-* doesnt_send (and figure out how it relates to ordering steps)
-* add diffs to failure message
+* doesnt_send (and figure out how it relates to ordering message expectations)
 * add color to failure message diffs
 * make failure message diff colors configurable via env vars for acessibility
 
+## RELEASE 0.2.0
+
+* FEATURE: `in_any_order` lets you declare a subset of protocol messages that you don't care about the order of, just that they are sent & received with the correct arguments (if any).
+* ENHANCEMENT: `ObjectProtocol#bind` now provides a helpful error message if you try to bind the wrong participant names.
+
 ## RELEASE 0.1.0
 
 * FEATURE: ObjectProtocols can be instantiated and used in tests

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    object_protocol (0.1.0)
+    object_protocol (0.2.0)
       binding_of_caller
 
 GEM
@@ -13,7 +13,7 @@ GEM
     coderay (1.1.2)
     debug_inspector (0.0.3)
     diff-lcs (1.3)
-    git (1.4.0)
+    git (1.5.0)
     method_source (0.9.0)
     pry (0.11.3)
       coderay (~> 1.1.0)
@@ -35,7 +35,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.1)
-    structured_changelog (0.10.0)
+    structured_changelog (0.10.2)
       git
 
 PLATFORMS

data/README.adoc

@@ -0,0 +1,133 @@
+= ObjectProtocol
+:ext-relative: .adoc
+:source-highlighter: coderay
+:sectanchors:
+:linkattrs:
+:toc: left
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+
+== Goals
+
+. Write message expectation tests with less boilerplate than when using RSpec spies
+. Resulting protocols should be usable as documentation
+. Be able to specify which object sent the message and which object received it (traditional message expectation test only allow the latter)
+
+== What's An Object Protocol?
+
+Protocols are the types of an OO program. They structure and order the messages passed between communicating agents.
+
+== Using Object Protocols
+
+=== A Simple Logger
+
+Given a unrealistically simple logger:
+[source,ruby]
+----
+class UnrealisticLogger
+  def initialize(device)
+    @device = device
+  end
+
+  def log(message)
+    @device << message
+  end
+
+  def rotate
+    @device.shift
+  end
+end
+----
+
+we can write a protocol for what happens when we call `#log` on an instance of `UnrealisticLogger`
+
+[source.ruby]
+----
+UnrealisticLoggingProtocol = ObjectProtocol.new(:device, :logger) do # <1>
+  logger.sends(:<<).to(device) # <2>
+end
+----
+<1> we need to tell the protocol the names of the participants
+<2> we switch to using local variables here instead of the symbols
+
+Then, we can test this protocol:
+
+[source,ruby]
+----
+require 'object_protocol/rspec'
+
+RSpec.describe UnrealisticLoggingProtocol do
+  it "is satisfied by calling #log on the logger" do
+    device = []
+    logger = UnrealisticLogger.new(device) # <1>
+
+    UnrealisticLoggingProtocol.bind( # <2>
+      device: device,
+      logger: logger,
+    )
+
+    expect(UnrealisticLoggingProtocol).to be_satisfied_by do
+      logger.log("message") # <3>
+    end
+  end
+end
+----
+<1> instantiate the participants
+<2> bind participants to the protocol
+<3> test an execution against the protocol
+
+Ok, but what was all that?
+
+Well, we created a protocol that we can use as documentation, and tested it with a lot less fanfare and boilerplate than you'd need with traditional message expectation tests!
+
+In real life, you'd use an actual object defined in your codebase in place of a fake logger, but you'd probably inject fake or stub collaborator objects to avoid side-effects.
+
+== How Does This All Work, Anyway?
+
+During an execution (the block passed to `satisfied_by`), we spy on every public method (except `#__send__` and `#object_id` because of the warnings) defined on each bound participant object. We record the message, the sender, the receiver, and the arguments (if any) that were passed. Then, we invoke the actual method behavior defined by that object.
+
+=== Interaction with `#method_missing`
+
+`#method_missing` is rarely a message that is sent from one object to another. We currently record the name of the missing method as the "sent message" and record any arguments beyond that message name, as well as the sender and receiver.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'object_protocol'
+----
+
+And then execute:
+
+[source,shell]
+----
+$ bundle
+----
+
+Or install it yourself as:
+
+[source,shell]
+----
+$ gem install object_protocol
+----
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to https://rubygems.org[rubygems.org].
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yarmiganosca/object_protocol. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the http://contributor-covenant.org[Contributor Covenant] code of conduct.
+
+== Code of Conduct
+
+Everyone interacting in the ObjectProtocol project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the https://github.com/yarmiganosca/object_protocol/blob/master/CODE_OF_CONDUCT.md[code of conduct].

data/lib/object_protocol.rb

@@ -1,30 +1,65 @@
 require "object_protocol/version"
 require 'object_protocol/stand_in'
 require 'object_protocol/satisfaction_attempt'
+require 'object_protocol/unordered_message_sequence_expectation'
 
 class ObjectProtocol
   attr_reader :participants_by_name
 
-  def initialize(*participant_names, &protocol)
+  def initialize(*participant_names, &expectations)
+    @participant_names = participant_names.map(&:to_sym)
+
     participant_names.each(&method(:define_stand_in))
-    instance_exec(&protocol)
+    instance_exec(&expectations)
     participant_names.each(&method(:undefine_stand_in))
   end
 
+  def in_any_order(&expectations)
+    unordered_message_sequence_expectation = UnorderedMessageSequenceExpectation.new(protocol: self)
+    self.expectations << unordered_message_sequence_expectation
+
+    expectation_sequence_stack.push(unordered_message_sequence_expectation)
+    instance_exec(&expectations)
+    expectation_sequence_stack.pop
+  end
+
   def bind(**participants_by_name)
-    @participants_by_name = participants_by_name
+    bind_attempt_participant_names = participants_by_name.keys.map(&:to_sym)
+
+    missing_participant_names = participant_names - bind_attempt_participant_names
+    extra_participant_names   = bind_attempt_participant_names - participant_names
+
+    if missing_participant_names.empty? && extra_participant_names.empty?
+      @participants_by_name = participants_by_name
+
+      @participants_by_name.each(&method(:define_participant))
+
+      self
+    else
+      key_error_message_parts = []
 
-    @participants_by_name.each(&method(:define_participant))
+      if missing_participant_names.any?
+        key_error_message_parts << "These keys are required by this protocol but weren't provided: #{missing_participant_names.join(', ')}"
+      end
 
-    self
+      if extra_participant_names.any?
+        key_error_message_parts << "These keys aren't used in this protocol but were provided: #{extra_participant_names.join(', ')}"
+      end
+
+      raise KeyError, key_error_message_parts.join("\n          ") # makes the second line indent correctly
+    end
   end
 
   def satisfied_by?(&blk)
     SatisfactionAttempt.new(self, &blk).to_bool
   end
 
-  def steps
-    @steps ||= []
+  def add_expectation(expectation)
+    expectation_sequence_stack.last.expectations << expectation
+  end
+
+  def expectations
+    @expectations ||= []
   end
 
   def participant_by_name(name)
@@ -40,11 +75,13 @@ class ObjectProtocol
   end
 
   def to_rspec_matcher_failure_message_lines
-    steps.map(&:to_rspec_matcher_failure_message_line)
+    expectations.flat_map(&:to_rspec_matcher_failure_message_lines)
   end
 
   private
 
+  attr_reader :participant_names
+
   def define_participant(name, participant)
     instance_variable_set("@#{name}_participant", participant)
 
@@ -65,4 +102,8 @@ class ObjectProtocol
     instance_eval("undef :#{name}")
     remove_instance_variable("@#{name}_stand_in")
   end
+
+  def expectation_sequence_stack
+    @expectation_sequence_stack ||= [self]
+  end
 end

data/lib/object_protocol/execution.rb

@@ -62,13 +62,23 @@ class ObjectProtocol
                             args
                           end
 
-              sent_message = SentMessage.new(
-                sender:   sender,
-                receiver: self,
-                name:     method_name,
-              )
-
-              sent_message.with(arguments) if arguments.any?
+              if method_name == :method_missing
+                sent_message = SentMessage.new(
+                  sender:   sender,
+                  receiver: self,
+                  name:     arguments.first
+                )
+
+                sent_message.with(arguments[1..-1]) if arguments.size > 1
+              else
+                sent_message = SentMessage.new(
+                  sender:   sender,
+                  receiver: self,
+                  name:     method_name
+                )
+
+                sent_message.with(arguments) if arguments.any?
+              end
 
               execution.messages << sent_message
             end

data/lib/object_protocol/{step.rb → message_expectation.rb}

@@ -1,10 +1,13 @@
+require 'object_protocol/satisfiable_message_expectation'
+
 class ObjectProtocol
-  class Step
+  class MessageExpectation
     attr_reader :sender, :message, :receiver, :arguments
 
-    def initialize(sender:, message:)
-      @sender  = sender
-      @message = message
+    def initialize(protocol:, sender:, message:)
+      @protocol = protocol
+      @sender   = sender
+      @message  = message
 
       @arguments_specified = false
     end
@@ -23,17 +26,21 @@ class ObjectProtocol
       self
     end
 
+    def to_satisfiable
+      SatisfiableMessageExpectation.new(protocol: protocol, message_expectation: self)
+    end
+
     def inspect
-      "<Step[#{sender.name}, :#{message}, #{receiver.name}]>"
+      "<#{self.class.name.split('::').last}[#{sender.name}, :#{message}, #{receiver.name}]>"
     end
 
-    def to_rspec_matcher_failure_message_line
+    def to_rspec_matcher_failure_message_lines
       fragment_base = "#{sender.name}.sends(:#{message}).to(#{receiver.name})"
 
       if arguments_specified?
-        "#{fragment_base}.with(#{arguments})"
+        ["#{fragment_base}.with(#{arguments})"]
       else
-        fragment_base
+        [fragment_base]
       end
     end
 
@@ -51,5 +58,9 @@ class ObjectProtocol
     def arguments_specified?
       @arguments_specified
     end
+
+    private
+
+    attr_reader :protocol
   end
 end

data/lib/object_protocol/rspec.rb

@@ -18,9 +18,9 @@ class SatisfactionAttemptVerifier
   def failure_message
     [
       "expected",
-      protocol.to_rspec_matcher_failure_message_lines.map(&"  ".method(:+)).flatten,
+      *protocol.to_rspec_matcher_failure_message_lines.flat_map(&"  ".method(:+)),
       "to be satisfied by",
-      attempt.to_rspec_matcher_failure_message_lines.map(&"  ".method(:+)).flatten,
+      *attempt.to_rspec_matcher_failure_message_lines.flat_map(&"  ".method(:+)),
     ].join("\n")
   end
 

data/lib/object_protocol/satisfaction_attempt.rb

@@ -1,5 +1,4 @@
 require 'object_protocol/execution'
-require 'object_protocol/satisfiable_step'
 
 class ObjectProtocol
   class SatisfactionAttempt
@@ -11,21 +10,19 @@ class ObjectProtocol
     def to_bool
       execution.call(protocol)
 
-      unsatisfied_steps = protocol.steps.map do |step|
-        SatisfiableStep.new(protocol: protocol, step: step)
-      end
+      satisfiable_expectations = protocol.expectations.map(&:to_satisfiable)
 
       execution.messages.each do |sent_message|
-        next_step = unsatisfied_steps.first
+        next_expectation = satisfiable_expectations.first
 
-        next_step.attempt_to_apply_sent_message(sent_message)
+        next_expectation.attempt_to_apply_sent_message(sent_message)
 
-        if next_step.satisfied?
-          unsatisfied_steps.shift
+        if next_expectation.satisfied?
+          satisfiable_expectations.shift
         end
       end
 
-      unsatisfied_steps.empty?
+      satisfiable_expectations.empty?
     end
 
     def to_rspec_matcher_failure_message_lines

data/lib/object_protocol/{satisfiable_step.rb → satisfiable_message_expectation.rb}

@@ -1,14 +1,14 @@
 require 'forwardable'
 
 class ObjectProtocol
-  class SatisfiableStep
+  class SatisfiableMessageExpectation
     extend Forwardable
 
-    delegate %i(sender receiver message arguments arguments_specified?) => :@step
+    delegate %i(sender receiver message arguments arguments_specified?) => :@message_expectation
 
-    def initialize(protocol:, step:)
-      @protocol = protocol
-      @step     = step
+    def initialize(protocol:, message_expectation:)
+      @protocol            = protocol
+      @message_expectation = message_expectation
 
       @satisfied = false
     end
@@ -36,6 +36,10 @@ class ObjectProtocol
       !!@satisfied
     end
 
+    def unsatisfied?
+      !satisfied?
+    end
+
     private
 
     attr_reader :protocol

data/lib/object_protocol/satisfiable_unordered_message_sequence_expectation.rb

@@ -0,0 +1,36 @@
+require 'forwardable'
+
+class ObjectProtocol
+  class SatisfiableUnorderedMessageSequenceExpectation
+    extend Forwardable
+
+    def initialize(protocol:, sequence_expectation:)
+      @protocol             = protocol
+      @sequence_expectation = sequence_expectation
+    end
+
+    def attempt_to_apply_sent_message(sent_message)
+      return if satisfied?
+
+      satisfiable_expectations.each do |satisfiable_expectation|
+        if satisfiable_expectation.unsatisfied?
+          satisfiable_expectation.attempt_to_apply_sent_message(sent_message)
+
+          break if satisfiable_expectation.satisfied?
+        end
+      end
+    end
+
+    def satisfied?
+      satisfiable_expectations.all?(&:satisfied?)
+    end
+
+    private
+
+    attr_reader :protocol, :sequence_expectation
+
+    def satisfiable_expectations
+      @satisfiable_expectations ||= sequence_expectation.expectations.map(&:to_satisfiable)
+    end
+  end
+end

data/lib/object_protocol/stand_in.rb

@@ -1,4 +1,4 @@
-require 'object_protocol/step'
+require 'object_protocol/message_expectation'
 
 class ObjectProtocol
   class StandIn
@@ -10,9 +10,11 @@ class ObjectProtocol
     end
 
     def sends(message)
-      Step.new(sender: self, message: message).tap do |step|
-        protocol.steps << step
-      end
+      MessageExpectation.new(
+        protocol: protocol,
+        sender:   self,
+        message:  message
+      ).tap(&protocol.method(:add_expectation))
     end
 
     private

data/lib/object_protocol/unordered_message_sequence_expectation.rb

@@ -0,0 +1,31 @@
+require 'object_protocol/satisfiable_unordered_message_sequence_expectation'
+
+class ObjectProtocol
+  class UnorderedMessageSequenceExpectation
+    def initialize(protocol:)
+      @protocol = protocol
+    end
+
+    def expectations
+      @expectations ||= []
+    end
+
+    def to_rspec_matcher_failure_message_lines
+      [
+        "in_any_order",
+        *expectations.flat_map(&:to_rspec_matcher_failure_message_lines).map(&"  ".method(:+)),
+      ]
+    end
+
+    def to_satisfiable
+      SatisfiableUnorderedMessageSequenceExpectation.new(
+        protocol:             protocol,
+        sequence_expectation: self
+      )
+    end
+
+    private
+
+    attr_reader :protocol
+  end
+end

data/lib/object_protocol/version.rb

@@ -1,3 +1,3 @@
 class ObjectProtocol
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: object_protocol
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chris Hoffman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-04 00:00:00.000000000 Z
+date: 2018-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -109,18 +109,20 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README.md
+- README.adoc
 - Rakefile
 - bin/console
 - bin/setup
 - lib/object_protocol.rb
 - lib/object_protocol/execution.rb
+- lib/object_protocol/message_expectation.rb
 - lib/object_protocol/rspec.rb
 - lib/object_protocol/satisfaction_attempt.rb
-- lib/object_protocol/satisfiable_step.rb
+- lib/object_protocol/satisfiable_message_expectation.rb
+- lib/object_protocol/satisfiable_unordered_message_sequence_expectation.rb
 - lib/object_protocol/sent_message.rb
 - lib/object_protocol/stand_in.rb
-- lib/object_protocol/step.rb
+- lib/object_protocol/unordered_message_sequence_expectation.rb
 - lib/object_protocol/version.rb
 - object_protocol.gemspec
 homepage: https://www.github.com/yarmiganosca/object_protocol

data/README.md

@@ -1,39 +0,0 @@
-# ObjectProtocol
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/object_protocol`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'object_protocol'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install object_protocol
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/yarmiganosca/object_protocol. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
-## Code of Conduct
-
-Everyone interacting in the ObjectProtocol project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yarmiganosca/object_protocol/blob/master/CODE_OF_CONDUCT.md).