cucumber 1.3.10 → 2.0.0

data/features/docs/wire_protocol/invoke_message.feature

@@ -0,0 +1,216 @@
+@wire
+Feature: Invoke message
+
+  Assuming a StepMatch was returned for a given step name, when it's time to
+  invoke that step definition, Cucumber will send an invoke message.
+
+  The invoke message contains the ID of the step definition, as returned by
+  the wire server in response to the the step_matches call, along with the
+  arguments that were parsed from the step name during the same step_matches
+  call.
+
+  The wire server will normally reply one of the following:
+
+  * `success`
+  * `fail`
+  * `pending` - optionally takes a message argument
+
+  This isn't quite the whole story: see also table_diffing.feature
+
+  Background:
+    Given a file named "features/wired.feature" with:
+      """
+      Feature: High strung
+        Scenario: Wired
+          Given we're all wired
+
+      """
+    And a file named "features/step_definitions/some_remote_place.wire" with:
+      """
+      host: localhost
+      port: 54321
+
+      """
+
+
+  @spawn
+  Scenario: Invoke a step definition which is pending
+    Given there is a wire server running on port 54321 which understands the following protocol:
+      | request                                              | response                            |
+      | ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]] |
+      | ["begin_scenario"]                                   | ["success"]                         |
+      | ["invoke",{"id":"1","args":[]}]                      | ["pending", "I'll do it later"]     |
+      | ["end_scenario"]                                     | ["success"]                         |
+    When I run `cucumber -f pretty -q`
+    And it should pass with:
+      """
+      Feature: High strung
+
+        Scenario: Wired
+          Given we're all wired
+            I'll do it later (Cucumber::Pending)
+            features/wired.feature:3:in `Given we're all wired'
+
+      1 scenario (1 pending)
+      1 step (1 pending)
+
+      """
+
+  Scenario: Invoke a step definition which passes
+    Given there is a wire server running on port 54321 which understands the following protocol:
+      | request                                              | response                            |
+      | ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]] |
+      | ["begin_scenario"]                                   | ["success"]                         |
+      | ["invoke",{"id":"1","args":[]}]                      | ["success"]                         |
+      | ["end_scenario"]                                     | ["success"]                         |
+    When I run `cucumber -f progress`
+    And it should pass with:
+      """
+      .
+
+      1 scenario (1 passed)
+      1 step (1 passed)
+
+      """
+
+  @spawn
+  Scenario: Invoke a step definition which fails
+
+    If an invoked step definition fails, it can return details of the exception
+    in the reply to invoke. This causes a Cucumber::WireSupport::WireException to be
+    raised.
+
+    Valid arguments are:
+
+    - `message` (mandatory)
+    - `exception`
+    - `backtrace`
+
+    See the specs for Cucumber::WireSupport::WireException for more details
+
+    Given there is a wire server running on port 54321 which understands the following protocol:
+      | request                                              | response                                                                            |
+      | ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]]                                                 |
+      | ["begin_scenario"]                                   | ["success"]                                                                         |
+      | ["invoke",{"id":"1","args":[]}]                      | ["fail",{"message":"The wires are down", "exception":"Some.Foreign.ExceptionType"}] |
+      | ["end_scenario"]                                     | ["success"]                                                                         |
+    When I run `cucumber -f progress`
+    Then the stderr should not contain anything
+    And it should fail with:
+      """
+      F
+
+      (::) failed steps (::)
+
+      The wires are down (Some.Foreign.ExceptionType from localhost:54321)
+      features/wired.feature:3:in `Given we're all wired'
+
+      Failing Scenarios:
+      cucumber features/wired.feature:2 # Scenario: Wired
+
+      1 scenario (1 failed)
+      1 step (1 failed)
+
+      """
+
+  Scenario: Invoke a step definition which takes string arguments (and passes)
+
+    If the step definition at the end of the wire captures arguments, these are
+    communicated back to Cucumber in the `step_matches` message.
+
+    Cucumber expects these StepArguments to be returned in the StepMatch. The keys
+    have the following meanings:
+
+    - `val` - the value of the string captured for that argument from the step
+      name passed in step_matches
+    - `pos` - the position within the step name that the argument was matched
+      (used for formatter highlighting)
+
+    The argument values are then sent back by Cucumber in the `invoke` message.
+
+    Given there is a wire server running on port 54321 which understands the following protocol:
+      | request                                              | response                                                     |
+      | ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[{"val":"wired", "pos":10}]}]] |
+      | ["begin_scenario"]                                   | ["success"]                                                  |
+      | ["invoke",{"id":"1","args":["wired"]}]               | ["success"]                                                  |
+      | ["end_scenario"]                                     | ["success"]                                                  |
+    When I run `cucumber -f progress`
+    Then the stderr should not contain anything
+    And it should pass with:
+      """
+      .
+
+      1 scenario (1 passed)
+      1 step (1 passed)
+
+      """
+
+  Scenario: Invoke a step definition which takes regular and table arguments (and passes)
+
+    If the step has a multiline table argument, it will be passed with the
+    invoke message as an array of array of strings.
+
+    In this scenario our step definition takes two arguments - one
+    captures the "we're" and the other takes the table.
+
+    Given a file named "features/wired_on_tables.feature" with:
+      """
+      Feature: High strung
+        Scenario: Wired and more
+          Given we're all:
+            | wired |
+            | high  |
+            | happy |
+      """
+    And there is a wire server running on port 54321 which understands the following protocol:
+      | request                                                               | response                                                    |
+      | ["step_matches",{"name_to_match":"we're all:"}]                       | ["success",[{"id":"1", "args":[{"val":"we're", "pos":0}]}]] |
+      | ["begin_scenario"]                                                    | ["success"]                                                 |
+      | ["invoke",{"id":"1","args":["we're",[["wired"],["high"],["happy"]]]}] | ["success"]                                                 |
+      | ["end_scenario"]                                                      | ["success"]                                                 |
+    When I run `cucumber -f progress features/wired_on_tables.feature`
+    Then the stderr should not contain anything
+    And it should pass with:
+      """
+      .
+
+      1 scenario (1 passed)
+      1 step (1 passed)
+
+      """
+
+  Scenario: Invoke a scenario outline step
+    Given a file named "features/wired_in_an_outline.feature" with:
+      """
+      Feature:
+        Scenario Outline:
+          Given we're all <arg>
+
+          Examples:
+            | arg   |
+            | wired |
+      """
+    And there is a wire server running on port 54321 which understands the following protocol:
+      | request                                              | response                            |
+      | ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]] |
+      | ["begin_scenario"]                                   | ["success"]                         |
+      | ["invoke",{"id":"1","args":[]}]                      | ["success"]                         |
+      | ["end_scenario"]                                     | ["success"]                         |
+    When I run `cucumber -f progress features/wired_in_an_outline.feature`
+    Then the stderr should not contain anything
+    And it should pass with:
+      """
+      .
+
+      1 scenario (1 passed)
+      1 step (1 passed)
+
+      """
+    And the wire server should have received the following messages:
+      | step_matches   |
+      | begin_scenario |
+      | invoke         |
+      | end_scenario   |
+
+
+

data/features/docs/wire_protocol/readme.md

@@ -0,0 +1,26 @@
+Cucumber's wire protocol allows step definitions to be
+implemented and invoked on any platform.
+
+Communication is over a TCP socket, which Cucumber connects to when it finds
+a definition file with the .wire extension in the step_definitions folder
+(or other load path). Note that these files are rendered with ERB when loaded.
+
+A WirePacket flowing in either direction is formatted as a JSON-encoded
+string, with a newline character signaling the end of a packet. See the
+specs for Cucumber::WireSupport::WirePacket for more details.
+
+Cucumber sends the following request messages out over the wire:
+
+* `step_matches` - Find out whether the wire server has a definition for a step
+* `invoke` - Ask for a step definition to be invoked
+* `begin_scenario` - signals that cucumber is about to execute a scenario
+* `end_scenario` - signals that cucumber has finished executing a scenario
+* `snippet_text` - requests a snippet for an undefined step
+
+Every message supports two standard responses:
+
+* `success` - expects different arguments (sometimes none at all) depending
+  on the request that was sent.
+* `fail` - causes a Cucumber::WireSupport::WireException to be raised.
+
+Some messages support more responses - see individual scenarios for details.

data/features/docs/wire_protocol/snippets_message.feature

@@ -0,0 +1,51 @@
+@wire
+Feature: Snippets message
+
+  If a step doesn't match, Cucumber will ask the wire server to return a snippet of code for a
+  step definition.
+
+  Background:
+    Given a file named "features/wired.feature" with:
+      """
+      Feature: High strung
+        Scenario: Wired
+          Given we're all wired
+
+      """
+    And a file named "features/step_definitions/some_remote_place.wire" with:
+      """
+      host: localhost
+      port: 54321
+
+      """
+
+  @spawn
+  Scenario: Wire server returns snippets for a step that didn't match
+    Given there is a wire server running on port 54321 which understands the following protocol:
+      | request                                                                                          | response                         |
+      | ["step_matches",{"name_to_match":"we're all wired"}]                                             | ["success",[]]                   |
+      | ["snippet_text",{"step_keyword":"Given","multiline_arg_class":"","step_name":"we're all wired"}] | ["success","foo()\n  bar;\nbaz"] |
+      | ["begin_scenario"]                                                                               | ["success"]                      |
+      | ["end_scenario"]                                                                                 | ["success"]                      |
+    When I run `cucumber -f pretty`
+    Then the stderr should not contain anything
+    And it should pass with:
+      """
+      Feature: High strung
+
+        Scenario: Wired         # features/wired.feature:2
+          Given we're all wired # features/wired.feature:3
+
+      1 scenario (1 undefined)
+      1 step (1 undefined)
+      """
+    And the output should contain:
+      """
+
+      You can implement step definitions for undefined steps with these snippets:
+
+      foo()
+        bar;
+      baz
+
+      """

data/features/docs/wire_protocol/step_matches_message.feature

@@ -0,0 +1,81 @@
+@wire
+Feature: Step matches message
+
+  When the features have been parsed, Cucumber will send a `step_matches`
+  message to ask the wire server if it can match a step name. This happens for
+  each of the steps in each of the features.
+
+  The wire server replies with an array of StepMatch objects.
+
+  When each StepMatch is returned, it contains the following data:
+
+  * `id` - identifier for the step definition to be used later when if it
+  needs to be invoked. The identifier can be any string value and
+  is simply used for the wire server's own reference.
+  * `args` - any argument values as captured by the wire end's own regular
+  expression (or other argument matching) process.
+
+  Background:
+    Given a file named "features/wired.feature" with:
+      """
+      Feature: High strung
+        Scenario: Wired
+          Given we're all wired
+
+      """
+    And a file named "features/step_definitions/some_remote_place.wire" with:
+      """
+      host: localhost
+      port: 54321
+
+      """
+
+  Scenario: Dry run finds no step match
+    Given there is a wire server running on port 54321 which understands the following protocol:
+      | request                                              | response       |
+      | ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[]] |
+    When I run `cucumber --dry-run --no-snippets -f progress`
+    And it should pass with:
+      """
+      U
+
+      1 scenario (1 undefined)
+      1 step (1 undefined)
+
+      """
+
+  Scenario: Dry run finds a step match
+    Given there is a wire server running on port 54321 which understands the following protocol:
+      | request                                              | response                            |
+      | ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[]}]] |
+    When I run `cucumber --dry-run -f progress`
+    And it should pass with:
+      """
+      -
+
+      1 scenario (1 skipped)
+      1 step (1 skipped)
+
+      """
+
+  Scenario: Step matches returns details about the remote step definition
+
+    Optionally, the StepMatch can also contain a source reference, and a native
+    regexp string which will be used by some formatters.
+
+    Given there is a wire server running on port 54321 which understands the following protocol:
+      | request                                              | response                                                                           |
+      | ["step_matches",{"name_to_match":"we're all wired"}] | ["success",[{"id":"1", "args":[], "source":"MyApp.MyClass:123", "regexp":"we.*"}]] |
+    When I run `cucumber -f stepdefs --dry-run`
+    Then it should pass with:
+      """
+      -
+
+      we.*   # MyApp.MyClass:123
+
+      1 scenario (1 skipped)
+      1 step (1 skipped)
+
+      """
+    And the stderr should not contain anything
+

data/{legacy_features/wire_protocol_table_diffing.feature → features/docs/wire_protocol/table_diffing.feature}

@@ -1,12 +1,12 @@
 @wire
 Feature: Wire protocol table diffing
+
   In order to use the amazing functionality in the Cucumber table object
   As a wire server
   I want to be able to ask for a table diff during a step definition invocation
 
   Background:
-    Given a standard Cucumber project directory structure
-    And a file named "features/wired.feature" with:
+    Given a file named "features/wired.feature" with:
       """
       Feature: Hello
         Scenario: Wired
@@ -20,6 +20,7 @@ Feature: Wire protocol table diffing
 
       """
 
+  @spawn
   Scenario: Invoke a step definition tries to diff the table and fails
     Given there is a wire server running on port 54321 which understands the following protocol:
       | request                                              | response                                                                                             |
@@ -28,9 +29,9 @@ Feature: Wire protocol table diffing
       | ["invoke",{"id":"1","args":[]}]                      | ["diff",[[["a","b"],["c","d"]],[["x","y"],["z","z"]]]]                                               |
       | ["diff_failed"]                                      | ["fail",{"message":"Not same", "exception":"DifferentException", "backtrace":["a.cs:12","b.cs:34"]}] |
       | ["end_scenario"]                                     | ["success"]                                                                                          |
-    When I run cucumber -f progress --backtrace
-    Then STDERR should be empty
-    And it should fail with
+    When I run `cucumber -f progress --backtrace`
+    Then the stderr should not contain anything
+    And it should fail with:
       """
       F
 
@@ -57,8 +58,8 @@ Feature: Wire protocol table diffing
       | ["invoke",{"id":"1","args":[]}]                      | ["diff",[[["a"],["b"]],[["a"],["b"]]]] |
       | ["diff_ok"]                                          | ["success"]                            |
       | ["end_scenario"]                                     | ["success"]                            |
-    When I run cucumber -f progress
-    And it should pass with
+    When I run `cucumber -f progress`
+    Then it should pass with:
       """
       .
 
@@ -67,6 +68,7 @@ Feature: Wire protocol table diffing
 
       """
 
+  @spawn
   Scenario: Invoke a step definition which successfully diffs a table but then fails
     Given there is a wire server running on port 54321 which understands the following protocol:
       | request                                              | response                                                      |
@@ -75,8 +77,8 @@ Feature: Wire protocol table diffing
       | ["invoke",{"id":"1","args":[]}]                      | ["diff",[[["a"],["b"]],[["a"],["b"]]]]                        |
       | ["diff_ok"]                                          | ["fail",{"message":"I wanted things to be different for us"}] |
       | ["end_scenario"]                                     | ["success"]                                                   |
-    When I run cucumber -f progress
-    And it should fail with
+    When I run `cucumber -f progress`
+    Then it should fail with:
       """
       F
 
@@ -93,6 +95,7 @@ Feature: Wire protocol table diffing
 
       """
 
+  @spawn
   Scenario: Invoke a step definition which asks for an immediate diff that fails
     Given there is a wire server running on port 54321 which understands the following protocol:
       | request                                              | response                            |
@@ -100,14 +103,17 @@ Feature: Wire protocol table diffing
       | ["begin_scenario"]                                   | ["success"]                         |
       | ["invoke",{"id":"1","args":[]}]                      | ["diff!",[[["a"]],[["b"]]]]         |
       | ["end_scenario"]                                     | ["success"]                         |
-    When I run cucumber -f progress
-    And it should fail with
+    When I run `cucumber -f progress`
+    And it should fail with exactly:
       """
       F
 
       (::) failed steps (::)
 
-      Tables were not identical (Cucumber::Ast::Table::Different)
+      Tables were not identical:
+      
+        | (-) a | (+) b |
+       (Cucumber::MultilineArgument::DataTable::Different)
       features/wired.feature:3:in `Given we're all wired'
 
       Failing Scenarios:
@@ -115,5 +121,6 @@ Feature: Wire protocol table diffing
 
       1 scenario (1 failed)
       1 step (1 failed)
+      0m0.012s
 
       """

data/{legacy_features/wire_protocol_tags.feature → features/docs/wire_protocol/tags.feature}

@@ -1,10 +1,10 @@
 @wire
 Feature: Wire protocol tags
+
   In order to use Before and After hooks in a wire server, we send tags with the 
   scenario in the begin_scenario and end_scenario messages
 
   Background:
-    Given a standard Cucumber project directory structure
     And a file named "features/step_definitions/some_remote_place.wire" with:
       """
       host: localhost
@@ -29,9 +29,9 @@ Feature: Wire protocol tags
       | ["begin_scenario", {"tags":["bar","baz","foo"]}]     | ["success"]                         |
       | ["invoke",{"id":"1","args":[]}]                      | ["success"]                         |
       | ["end_scenario", {"tags":["bar","baz","foo"]}]       | ["success"]                         |
-    When I run cucumber -f pretty -q
-    Then STDERR should be empty
-    And it should pass with
+    When I run `cucumber -f pretty -q`
+    Then the stderr should not contain anything
+    And it should pass with:
       """
       @foo @bar
       Feature: Wired
@@ -66,9 +66,9 @@ Feature: Wire protocol tags
     | ["begin_scenario", {"tags":["bar","baz","foo"]}]     | ["success"]                         |
     | ["invoke",{"id":"1","args":[]}]                      | ["success"]                         |
     | ["end_scenario", {"tags":["bar","baz","foo"]}]       | ["success"]                         |
-  When I run cucumber -f pretty -q
-  Then STDERR should be empty
-  And it should pass with
+  When I run `cucumber -f pretty -q`
+  Then the stderr should not contain anything
+  And it should pass with:
     """
     @foo @bar
     Feature: Wired

data/{legacy_features/wire_protocol_timeouts.feature → features/docs/wire_protocol/timeouts.feature}

@@ -1,11 +1,11 @@
 @wire
 Feature: Wire protocol timeouts
+
   We don't want Cucumber to hang forever on a wire server that's not even there,
   but equally we need to give the user the flexibility to allow step definitions
   to take a while to execute, if that's what they need.
 
   Background:
-    Given a standard Cucumber project directory structure
     And a file named "features/wired.feature" with:
       """
       Feature: Telegraphy
@@ -21,12 +21,13 @@ Feature: Wire protocol timeouts
       port: 54321
 
       """
-    When I run cucumber -f progress
-    Then STDERR should match
+    When I run `cucumber -f progress`
+    Then the stderr should contain:
       """
       Unable to contact the wire server at localhost:54321
       """
 
+  @spawn
   Scenario: Invoke a step definition that takes longer than its timeout
     Given a file named "features/step_definitions/some_remote_place.wire" with:
       """
@@ -43,9 +44,9 @@ Feature: Wire protocol timeouts
       | ["invoke",{"id":"1","args":["wired"]}]               | ["success"]                                                  |
       | ["end_scenario"]                                     | ["success"]                                                  |
     And the wire server takes 0.2 seconds to respond to the invoke message
-    When I run cucumber -f pretty
-    Then STDERR should be empty
-    And it should fail with
+    When I run `cucumber -f pretty`
+    Then the stderr should not contain anything
+    And it should fail with:
       """
       Feature: Telegraphy