Merge branch '0.x' into 'master'

Author: itnelo

CHANGELOG.md

@@ -8,7 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Changed
 
-- No changes yet.
+- No description yet.
+
+## [0.2.1] - 2020-12-22
+### Fixed
+
+- `WebDriverInterface::waitUntil()`: a resulting value from the promise, that has been generated by the
+"condition-to-satisfy" callback, is now properly forwarded to the `onFulfilled` handler, for the `waitUntil` method
+itself.
 
 ## [0.2.0] - 2020-12-18
 ### Added
@@ -77,6 +84,7 @@ browser instance).
 This early development version doesn't yet contain full implementation for the introduced `WebDriverInterface`, only
 core design solutions and library interfaces are defined.
 
-[Unreleased]: https://github.com/itnelo/reactphp-webdriver/compare/0.2.0...0.x
+[Unreleased]: https://github.com/itnelo/reactphp-webdriver/compare/0.2.1...0.x
+[0.2.1]: https://github.com/itnelo/reactphp-webdriver/compare/0.2.0..0.2.1
 [0.2.0]: https://github.com/itnelo/reactphp-webdriver/compare/0.1.0..0.2.0
 [0.1.0]: https://github.com/itnelo/reactphp-webdriver/releases/tag/0.1.0

README.md

@@ -86,7 +86,7 @@ $socketConnector = new SocketConnector(
             'verify_peer' => false,
             'verify_peer_name' => false,
         ],
-    ],
+    ]
 );
 $browser = new Browser($loop, $socketConnector);
 $browser = $browser->withRejectErrorResponse(false);

src/Routine/Condition/CheckRoutine.php

@@ -127,9 +127,9 @@ private function runInternal(callable $conditionMetCallback, float $checkInterva
                 // handling evaluation results.
                 $this->_isEvaluating = true;
                 $resultPromise->then(
-                    function () use ($evaluationDeferred) {
-                        // at some point, a promise has been successfully resolved.
-                        $evaluationDeferred->resolve(null);
+                    function ($value) use ($evaluationDeferred) {
+                        // at some point, a promise has been successfully resolved (preserving resval).
+                        $evaluationDeferred->resolve($value);
                     },
                     function (Throwable $rejectionReason) {
                         // signals that we can take another promise from the condition callback to continue our checks.
@@ -154,11 +154,11 @@ function (Throwable $rejectionReason) {
         );
 
         return $conditionMetTimedPromise->then(
-            function () {
+            function ($value) {
                 // cleaning up a related timer with condition-check logic.
                 $this->loop->cancelTimer($this->_evaluationTimer);
 
-                return null;
+                return $value;
             },
             function (Throwable $rejectionReason) {
                 $this->loop->cancelTimer($this->_evaluationTimer);

src/WebDriverInterface.php

@@ -75,9 +75,12 @@ public function wait(float $time = 30.0): PromiseInterface;
      * A condition callback must return an instance of PromiseInterface. Whenever that promise becomes rejected, driver
      * will try to get a new promise from the callback, until it reaches a given timeout for retry attempts.
      *
-     * Note: waitUntil itself doesn't apply any timeouts for a single result promise (check iteration), the user-side
+     * Note 1: waitUntil itself doesn't apply any timeouts for a single result promise (check iteration), the user-side
      * MUST control any kind of promise timeouts for the condition callback, which is supplied to the method.
      *
+     * Note 2: the resulting value for the waitUntil promise will be a value, which is forwarded by the condition
+     * callback (see an example below).
+     *
      * Usage example:
      *
      * ```
@@ -90,16 +93,21 @@ public function wait(float $time = 30.0): PromiseInterface;
      *                 if (!$isVisible) {
      *                     throw new RuntimeException("Not visible yet! Let's retry!");
      *                 }
+     *
+     *                 // this value will be forwarded as a "result value" for the waitUntil promise.
+     *                 return 'it is visible now!';
      *             }
      *         );
      *     },
      *     15.5
      * );
      *
      * $becomeVisiblePromise->then(
-     *     function () use ($webDriver) {
+     *     function (string $forwardedValue) use ($webDriver) {
      *         // try-catch
      *         $webDriver->clickElement(...);    // sending a click command only if we are sure the target is visible.
+     *
+     *         // $forwardedValue === 'it is visible now!'
      *     }
      *     // handle case when the element is not visible on the page
      * );
@@ -109,7 +117,7 @@ public function wait(float $time = 30.0): PromiseInterface;
      * @param float    $time                 Time (in seconds) to wait for successfully resolved promise from the
      *                                       condition callback (minimum: 0.5)
      *
-     * @return PromiseInterface<null>
+     * @return PromiseInterface<mixed>
      */
     public function waitUntil(callable $conditionMetCallback, float $time = 30.0): PromiseInterface;
 
@@ -118,7 +126,7 @@ public function waitUntil(callable $conditionMetCallback, float $time = 30.0): P
      * {filePath}, rejection reason with error message will be provided otherwise.
      *
      * @param string $sessionIdentifier Session identifier for Selenium Grid server (hub)
-     * @param string $filePath          Path where a screenshot image will be saved
+     * @param string $filePath          Path, where a screenshot image must be saved
      *
      * @return PromiseInterface<null>
      */