Repository navigation
Expand file tree
/
Copy pathWebDriverInterface.php
More file actions
139 lines (132 loc) · 5.61 KB
/
Copy pathWebDriverInterface.php
File metadata and controls
139 lines (132 loc) · 5.61 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<?php
/*
* This file is part of the ReactPHP WebDriver <https://github.com/itnelo/reactphp-webdriver>.
*
* (c) 2020-2021 Pavel Petrov <itnelo@gmail.com>.
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*
* @license https://opensource.org/licenses/mit MIT
*/
declare(strict_types=1);
namespace Itnelo\React\WebDriver;
use React\Promise\PromiseInterface;
/**
* Manipulates a remote browser instance asynchronously, using Selenium Grid (hub) API.
*
* As an extension to the base client, it can perform both action requests and some client-side (offline) tasks,
* between these actions, such as conditional waits.
*/
interface WebDriverInterface extends ClientInterface
{
/**
* Returns a promise that will be resolved when the driver completes idling for the specified amount of time.
*
* Usage example:
*
* ```
* $navigationPromise = $webDriver->openUri('https://github.com/itnelo');
*
* $elementIdentifierPromise = $navigationPromise->then(
* function () use ($webDriver) {
* // try-catch
* $timeHasComePromise = $webDriver->wait(5.0);
*
* return $timeHasComePromise->then(
* function () use ($webDriver) {
* return $webDriver->getElementIdentifier('sessionIdentifier', 'xpathQuery');
* }
* );
* }
* // handle rejection reason (e.g. a connection timeout due to unexpected rate limiting)
* );
*
* $elementClickPromise = $elementIdentifierPromise->then(
* function (string $elementIdentifier) use ($webDriver) {
* // try-catch
* return $webDriver->clickElement('sessionIdentifier', $elementIdentifier);
* }
* // handle rejection reason (e.g. invalid xpath or element not found error)
* );
* ```
*
* Note: each wait call is a separate action and starts its own timer; that timer will not wait for any other
* timers to fire (i.e. this method is not suited for "shooting" an array of concurrent requests with delays, to
* bypass rate limits, but to wait page loading and javascript code). Basically, it is just a syntactic sugar for
* promise timer boilerplate, so you should use the event reactor directly, to limit driver calls for some
* sensitive operations.
*
* @param float $time Time in seconds to wait (e.g. 0.351; max precision can be 3)
*
* @return PromiseInterface<null>
*/
public function wait(float $time = 30.0): PromiseInterface;
/**
* Returns a promise that will be resolved, when a given condition is met within specified amount of time, and
* rejected, otherwise.
*
* 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 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:
*
* ```
* $becomeVisiblePromise = $webDriver->waitUntil(
* function () use ($webDriver) {
* $visibilityStatePromise = $webDriver->getElementVisibility(...);
*
* return $visibilityStatePromise->then(
* function (bool $isVisible) {
* 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 (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
* );
* ```
*
* @param callable $conditionMetCallback A condition to be met, as a callback
* @param float $time Time (in seconds) to wait for successfully resolved promise from the
* condition callback (minimum: 0.5)
* @param float $checkInterval The interval for condition checks, in seconds (minimum: 0.1)
*
* @return PromiseInterface<mixed>
*/
public function waitUntil(
callable $conditionMetCallback,
float $time = 30.0,
float $checkInterval = 0.5
): PromiseInterface;
/**
* Returns a promise that will be resolved if a screenshot is successfully received and saved using the specified
* {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 must be saved
*
* @return PromiseInterface<null>
*/
public function saveScreenshot(string $sessionIdentifier, string $filePath): PromiseInterface;
}