Add soft @return type declarations to interfaces and base classes

Author: mpdude

UPGRADING.md

@@ -0,0 +1,13 @@
+# Upgrade notes for FriendsOfBehat/MinkExtension
+
+This document summarizes the changes relevant for users when upgrading to new versions.
+
+# Upgrade to 2.8
+
+## Soft `@return` types added
+
+`@return` type hints have been added to the `MinkAwareContext` and `DriverFactory` interfaces and to all methods
+in `MinkContext` and `RawMinkContext`.
+
+If you implement or extend these classes or any of the drivers shipped here, make sure to add _real_ corresponding
+return types to your implementations now. Signatures will be changed to include return types in the next major version.

src/Behat/MinkExtension/Context/MinkAwareContext.php

@@ -24,13 +24,17 @@ interface MinkAwareContext extends Context
      * Sets Mink instance.
      *
      * @param Mink $mink Mink session manager
+     *
+     * @return void
      */
     public function setMink(Mink $mink);
 
     /**
      * Sets parameters provided for Mink.
      *
      * @param array $parameters
+     *
+     * @return void
      */
     public function setMinkParameters(array $parameters);
 }

src/Behat/MinkExtension/Context/MinkContext.php

@@ -29,6 +29,8 @@ class MinkContext extends RawMinkContext implements TranslatableContext
      *
      * @Given /^(?:|I )am on (?:|the )homepage$/
      * @When /^(?:|I )go to (?:|the )homepage$/
+     *
+     * @return void
      */
     public function iAmOnHomepage()
     {
@@ -43,6 +45,8 @@ public function iAmOnHomepage()
      *
      * @Given /^(?:|I )am on "(?P<page>[^"]+)"$/
      * @When /^(?:|I )go to "(?P<page>[^"]+)"$/
+     *
+     * @return void
      */
     public function visit($page)
     {
@@ -55,6 +59,8 @@ public function visit($page)
      * Example: And I reload the page
      *
      * @When /^(?:|I )reload the page$/
+     *
+     * @return void
      */
     public function reload()
     {
@@ -66,6 +72,8 @@ public function reload()
      * Example: When I move backward one page
      *
      * @When /^(?:|I )move backward one page$/
+     *
+     * @return void
      */
     public function back()
     {
@@ -77,6 +85,8 @@ public function back()
      * Example: And I move forward one page
      *
      * @When /^(?:|I )move forward one page$/
+     *
+     * @return void
      */
     public function forward()
     {
@@ -89,6 +99,8 @@ public function forward()
      * Example: And I press "Log In"
      *
      * @When /^(?:|I )press "(?P<button>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function pressButton($button)
     {
@@ -102,6 +114,8 @@ public function pressButton($button)
      * Example: And I follow "Log In"
      *
      * @When /^(?:|I )follow "(?P<link>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function clickLink($link)
     {
@@ -117,6 +131,8 @@ public function clickLink($link)
      * @When /^(?:|I )fill in "(?P<field>(?:[^"]|\\")*)" with "(?P<value>(?:[^"]|\\")*)"$/
      * @When /^(?:|I )fill in "(?P<field>(?:[^"]|\\")*)" with:$/
      * @When /^(?:|I )fill in "(?P<value>(?:[^"]|\\")*)" for "(?P<field>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function fillField($field, $value)
     {
@@ -135,6 +151,8 @@ public function fillField($field, $value)
      *              | password | iLoveBats123 |
      *
      * @When /^(?:|I )fill in the following:$/
+     *
+     * @return void
      */
     public function fillFields(TableNode $fields)
     {
@@ -149,6 +167,8 @@ public function fillFields(TableNode $fields)
      * Example: And I select "Bats" from "user_fears"
      *
      * @When /^(?:|I )select "(?P<option>(?:[^"]|\\")*)" from "(?P<select>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function selectOption($select, $option)
     {
@@ -163,6 +183,8 @@ public function selectOption($select, $option)
      * Example: And I additionally select "Deceased" from "parents_alive_status"
      *
      * @When /^(?:|I )additionally select "(?P<option>(?:[^"]|\\")*)" from "(?P<select>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function additionallySelectOption($select, $option)
     {
@@ -177,6 +199,8 @@ public function additionallySelectOption($select, $option)
      * Example: And I check "Pearl Necklace"
      *
      * @When /^(?:|I )check "(?P<option>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function checkOption($option)
     {
@@ -190,6 +214,8 @@ public function checkOption($option)
      * Example: And I uncheck "Broadway Plays"
      *
      * @When /^(?:|I )uncheck "(?P<option>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function uncheckOption($option)
     {
@@ -203,6 +229,8 @@ public function uncheckOption($option)
      * Example: And I attach the file "bwayne_profile.png" to "profileImageUpload"
      *
      * @When /^(?:|I )attach the file "(?P<path>[^"]*)" to "(?P<field>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function attachFileToField($field, $path)
     {
@@ -225,6 +253,8 @@ public function attachFileToField($field, $path)
      * Example: And I should be on "http://google.com"
      *
      * @Then /^(?:|I )should be on "(?P<page>[^"]+)"$/
+     *
+     * @return void
      */
     public function assertPageAddress($page)
     {
@@ -237,6 +267,8 @@ public function assertPageAddress($page)
      * Example: And I should be on the homepage
      *
      * @Then /^(?:|I )should be on (?:|the )homepage$/
+     *
+     * @return void
      */
     public function assertHomepage()
     {
@@ -250,6 +282,8 @@ public function assertHomepage()
      * Example: And the url should match "log in"
      *
      * @Then /^the (?i)url(?-i) should match (?P<pattern>"(?:[^"]|\\")*")$/
+     *
+     * @return void
      */
     public function assertUrlRegExp($pattern)
     {
@@ -262,6 +296,8 @@ public function assertUrlRegExp($pattern)
      * Example: And the response status code should be 400
      *
      * @Then /^the response status code should be (?P<code>\d+)$/
+     *
+     * @return void
      */
     public function assertResponseStatus($code)
     {
@@ -274,6 +310,8 @@ public function assertResponseStatus($code)
      * Example: And the response status code should not be 404
      *
      * @Then /^the response status code should not be (?P<code>\d+)$/
+     *
+     * @return void
      */
     public function assertResponseStatusIsNot($code)
     {
@@ -286,6 +324,8 @@ public function assertResponseStatusIsNot($code)
      * Example: And I should see "Who is the Batman?"
      *
      * @Then /^(?:|I )should see "(?P<text>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function assertPageContainsText($text)
     {
@@ -298,6 +338,8 @@ public function assertPageContainsText($text)
      * Example: And I should not see "Batman is Bruce Wayne"
      *
      * @Then /^(?:|I )should not see "(?P<text>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function assertPageNotContainsText($text)
     {
@@ -310,6 +352,8 @@ public function assertPageNotContainsText($text)
      * Example: And I should not see "Batman, the vigilante"
      *
      * @Then /^(?:|I )should see text matching (?P<pattern>"(?:[^"]|\\")*")$/
+     *
+     * @return void
      */
     public function assertPageMatchesText($pattern)
     {
@@ -322,6 +366,8 @@ public function assertPageMatchesText($pattern)
      * Example: And I should not see "Bruce Wayne, the vigilante"
      *
      * @Then /^(?:|I )should not see text matching (?P<pattern>"(?:[^"]|\\")*")$/
+     *
+     * @return void
      */
     public function assertPageNotMatchesText($pattern)
     {
@@ -334,6 +380,8 @@ public function assertPageNotMatchesText($pattern)
      * Example: And the response should contain "Batman is the hero Gotham deserves."
      *
      * @Then /^the response should contain "(?P<text>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function assertResponseContains($text)
     {
@@ -346,6 +394,8 @@ public function assertResponseContains($text)
      * Example: And the response should not contain "Bruce Wayne is a billionaire, play-boy, vigilante."
      *
      * @Then /^the response should not contain "(?P<text>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function assertResponseNotContains($text)
     {
@@ -358,6 +408,8 @@ public function assertResponseNotContains($text)
      * Example: And I should see "Batman" in the "heroes_list" element
      *
      * @Then /^(?:|I )should see "(?P<text>(?:[^"]|\\")*)" in the "(?P<element>[^"]*)" element$/
+     *
+     * @return void
      */
     public function assertElementContainsText($element, $text)
     {
@@ -370,6 +422,8 @@ public function assertElementContainsText($element, $text)
      * Example: And I should not see "Bruce Wayne" in the "heroes_alter_egos" element
      *
      * @Then /^(?:|I )should not see "(?P<text>(?:[^"]|\\")*)" in the "(?P<element>[^"]*)" element$/
+     *
+     * @return void
      */
     public function assertElementNotContainsText($element, $text)
     {
@@ -382,6 +436,8 @@ public function assertElementNotContainsText($element, $text)
      * Example: And the "body" element should contain "style=\"color:black;\""
      *
      * @Then /^the "(?P<element>[^"]*)" element should contain "(?P<value>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function assertElementContains($element, $value)
     {
@@ -394,6 +450,8 @@ public function assertElementContains($element, $value)
      * Example: And the "body" element should not contain "style=\"color:black;\""
      *
      * @Then /^the "(?P<element>[^"]*)" element should not contain "(?P<value>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function assertElementNotContains($element, $value)
     {
@@ -406,6 +464,8 @@ public function assertElementNotContains($element, $value)
      * Example: And I should see a "body" element
      *
      * @Then /^(?:|I )should see an? "(?P<element>[^"]*)" element$/
+     *
+     * @return void
      */
     public function assertElementOnPage($element)
     {
@@ -418,6 +478,8 @@ public function assertElementOnPage($element)
      * Example: And I should not see a "canvas" element
      *
      * @Then /^(?:|I )should not see an? "(?P<element>[^"]*)" element$/
+     *
+     * @return void
      */
     public function assertElementNotOnPage($element)
     {
@@ -430,6 +492,8 @@ public function assertElementNotOnPage($element)
      * Example: And the "username" field should contain "bwayne"
      *
      * @Then /^the "(?P<field>(?:[^"]|\\")*)" field should contain "(?P<value>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function assertFieldContains($field, $value)
     {
@@ -444,6 +508,8 @@ public function assertFieldContains($field, $value)
      * Example: And the "username" field should not contain "batman"
      *
      * @Then /^the "(?P<field>(?:[^"]|\\")*)" field should not contain "(?P<value>(?:[^"]|\\")*)"$/
+     *
+     * @return void
      */
     public function assertFieldNotContains($field, $value)
     {
@@ -458,6 +524,8 @@ public function assertFieldNotContains($field, $value)
      * Example: And I should see 5 "div" elements
      *
      * @Then /^(?:|I )should see (?P<num>\d+) "(?P<element>[^"]*)" elements?$/
+     *
+     * @return void
      */
     public function assertNumElements($num, $element)
     {
@@ -472,6 +540,8 @@ public function assertNumElements($num, $element)
      * @Then /^the "(?P<checkbox>(?:[^"]|\\")*)" checkbox should be checked$/
      * @Then /^the "(?P<checkbox>(?:[^"]|\\")*)" checkbox is checked$/
      * @Then /^the checkbox "(?P<checkbox>(?:[^"]|\\")*)" (?:is|should be) checked$/
+     *
+     * @return void
      */
     public function assertCheckboxChecked($checkbox)
     {
@@ -488,6 +558,8 @@ public function assertCheckboxChecked($checkbox)
      * @Then /^the "(?P<checkbox>(?:[^"]|\\")*)" checkbox is (?:unchecked|not checked)$/
      * @Then /^the checkbox "(?P<checkbox>(?:[^"]|\\")*)" should (?:be unchecked|not be checked)$/
      * @Then /^the checkbox "(?P<checkbox>(?:[^"]|\\")*)" is (?:unchecked|not checked)$/
+     *
+     * @return void
      */
     public function assertCheckboxNotChecked($checkbox)
     {
@@ -500,6 +572,8 @@ public function assertCheckboxNotChecked($checkbox)
      * Example: And print current URL
      *
      * @Then /^print current URL$/
+     *
+     * @return void
      */
     public function printCurrentUrl()
     {
@@ -512,6 +586,8 @@ public function printCurrentUrl()
      * Example: And print last response
      *
      * @Then /^print last response$/
+     *
+     * @return void
      */
     public function printLastResponse()
     {
@@ -527,6 +603,8 @@ public function printLastResponse()
      * Example: And show last response
      *
      * @Then /^show last response$/
+     *
+     * @return void
      */
     public function showLastResponse()
     {