yaffs.net Git - yaffs-website/blob - vendor/behat/mink/src/Driver/DriverInterface.php

   1 <?php
   2
   3 /*
   4  * This file is part of the Mink package.
   5  * (c) Konstantin Kudryashov <ever.zet@gmail.com>
   6  *
   7  * For the full copyright and license information, please view the LICENSE
   8  * file that was distributed with this source code.
   9  */
  10
  11 namespace Behat\Mink\Driver;
  12
  13 use Behat\Mink\Element\NodeElement;
  14 use Behat\Mink\Exception\DriverException;
  15 use Behat\Mink\Exception\UnsupportedDriverActionException;
  16 use Behat\Mink\Session;
  17
  18 /**
  19  * Driver interface.
  20  *
  21  * @author Konstantin Kudryashov <ever.zet@gmail.com>
  22  */
  23 interface DriverInterface
  24 {
  25     /**
  26      * Sets driver's current session.
  27      *
  28      * @param Session $session
  29      */
  30     public function setSession(Session $session);
  31
  32     /**
  33      * Starts driver.
  34      *
  35      * Once started, the driver should be ready to visit a page.
  36      *
  37      * Calling any action before visiting a page is an undefined behavior.
  38      * The only supported method calls on a fresh driver are
  39      * - visit()
  40      * - setRequestHeader()
  41      * - setBasicAuth()
  42      * - reset()
  43      * - stop()
  44      *
  45      * Calling start on a started driver is an undefined behavior. Driver
  46      * implementations are free to handle it silently or to fail with an
  47      * exception.
  48      *
  49      * @throws DriverException When the driver cannot be started
  50      */
  51     public function start();
  52
  53     /**
  54      * Checks whether driver is started.
  55      *
  56      * @return Boolean
  57      */
  58     public function isStarted();
  59
  60     /**
  61      * Stops driver.
  62      *
  63      * Once stopped, the driver should be started again before using it again.
  64      *
  65      * Calling any action on a stopped driver is an undefined behavior.
  66      * The only supported method call after stopping a driver is starting it again.
  67      *
  68      * Calling stop on a stopped driver is an undefined behavior. Driver
  69      * implementations are free to handle it silently or to fail with an
  70      * exception.
  71      *
  72      * @throws DriverException When the driver cannot be closed
  73      */
  74     public function stop();
  75
  76     /**
  77      * Resets driver state.
  78      *
  79      * This should reset cookies, request headers and basic authentication.
  80      * When possible, the history should be reset as well, but this is not enforced
  81      * as some implementations may not be able to reset it without restarting the
  82      * driver entirely. Consumers requiring a clean history should restart the driver
  83      * to enforce it.
  84      *
  85      * Once reset, the driver should be ready to visit a page.
  86      * Calling any action before visiting a page is an undefined behavior.
  87      * The only supported method calls on a fresh driver are
  88      * - visit()
  89      * - setRequestHeader()
  90      * - setBasicAuth()
  91      * - reset()
  92      * - stop()
  93      *
  94      * Calling reset on a stopped driver is an undefined behavior.
  95      */
  96     public function reset();
  97
  98     /**
  99      * Visit specified URL.
 100      *
 101      * @param string $url url of the page
 102      *
 103      * @throws UnsupportedDriverActionException When operation not supported by the driver
 104      * @throws DriverException                  When the operation cannot be done
 105      */
 106     public function visit($url);
 107
 108     /**
 109      * Returns current URL address.
 110      *
 111      * @return string
 112      *
 113      * @throws UnsupportedDriverActionException When operation not supported by the driver
 114      * @throws DriverException                  When the operation cannot be done
 115      */
 116     public function getCurrentUrl();
 117
 118     /**
 119      * Reloads current page.
 120      *
 121      * @throws UnsupportedDriverActionException When operation not supported by the driver
 122      * @throws DriverException                  When the operation cannot be done
 123      */
 124     public function reload();
 125
 126     /**
 127      * Moves browser forward 1 page.
 128      *
 129      * @throws UnsupportedDriverActionException When operation not supported by the driver
 130      * @throws DriverException                  When the operation cannot be done
 131      */
 132     public function forward();
 133
 134     /**
 135      * Moves browser backward 1 page.
 136      *
 137      * @throws UnsupportedDriverActionException When operation not supported by the driver
 138      * @throws DriverException                  When the operation cannot be done
 139      */
 140     public function back();
 141
 142     /**
 143      * Sets HTTP Basic authentication parameters.
 144      *
 145      * @param string|Boolean $user     user name or false to disable authentication
 146      * @param string         $password password
 147      *
 148      * @throws UnsupportedDriverActionException When operation not supported by the driver
 149      * @throws DriverException                  When the operation cannot be done
 150      */
 151     public function setBasicAuth($user, $password);
 152
 153     /**
 154      * Switches to specific browser window.
 155      *
 156      * @param string $name window name (null for switching back to main window)
 157      *
 158      * @throws UnsupportedDriverActionException When operation not supported by the driver
 159      * @throws DriverException                  When the operation cannot be done
 160      */
 161     public function switchToWindow($name = null);
 162
 163     /**
 164      * Switches to specific iFrame.
 165      *
 166      * @param string $name iframe name (null for switching back)
 167      *
 168      * @throws UnsupportedDriverActionException When operation not supported by the driver
 169      * @throws DriverException                  When the operation cannot be done
 170      */
 171     public function switchToIFrame($name = null);
 172
 173     /**
 174      * Sets specific request header on client.
 175      *
 176      * @param string $name
 177      * @param string $value
 178      *
 179      * @throws UnsupportedDriverActionException When operation not supported by the driver
 180      * @throws DriverException                  When the operation cannot be done
 181      */
 182     public function setRequestHeader($name, $value);
 183
 184     /**
 185      * Returns last response headers.
 186      *
 187      * @return array
 188      *
 189      * @throws UnsupportedDriverActionException When operation not supported by the driver
 190      * @throws DriverException                  When the operation cannot be done
 191      */
 192     public function getResponseHeaders();
 193
 194     /**
 195      * Sets cookie.
 196      *
 197      * @param string $name
 198      * @param string $value
 199      *
 200      * @throws UnsupportedDriverActionException When operation not supported by the driver
 201      * @throws DriverException                  When the operation cannot be done
 202      */
 203     public function setCookie($name, $value = null);
 204
 205     /**
 206      * Returns cookie by name.
 207      *
 208      * @param string $name
 209      *
 210      * @return string|null
 211      *
 212      * @throws UnsupportedDriverActionException When operation not supported by the driver
 213      * @throws DriverException                  When the operation cannot be done
 214      */
 215     public function getCookie($name);
 216
 217     /**
 218      * Returns last response status code.
 219      *
 220      * @return int
 221      *
 222      * @throws UnsupportedDriverActionException When operation not supported by the driver
 223      * @throws DriverException                  When the operation cannot be done
 224      */
 225     public function getStatusCode();
 226
 227     /**
 228      * Returns last response content.
 229      *
 230      * @return string
 231      *
 232      * @throws UnsupportedDriverActionException When operation not supported by the driver
 233      * @throws DriverException                  When the operation cannot be done
 234      */
 235     public function getContent();
 236
 237     /**
 238      * Capture a screenshot of the current window.
 239      *
 240      * @return string screenshot of MIME type image/* depending
 241      *                on driver (e.g., image/png, image/jpeg)
 242      *
 243      * @throws UnsupportedDriverActionException When operation not supported by the driver
 244      * @throws DriverException                  When the operation cannot be done
 245      */
 246     public function getScreenshot();
 247
 248     /**
 249      * Return the names of all open windows.
 250      *
 251      * @return array array of all open windows
 252      *
 253      * @throws UnsupportedDriverActionException When operation not supported by the driver
 254      * @throws DriverException                  When the operation cannot be done
 255      */
 256     public function getWindowNames();
 257
 258     /**
 259      * Return the name of the currently active window.
 260      *
 261      * @return string the name of the current window
 262      *
 263      * @throws UnsupportedDriverActionException When operation not supported by the driver
 264      * @throws DriverException                  When the operation cannot be done
 265      */
 266     public function getWindowName();
 267
 268     /**
 269      * Finds elements with specified XPath query.
 270      *
 271      * @param string $xpath
 272      *
 273      * @return NodeElement[]
 274      *
 275      * @throws UnsupportedDriverActionException When operation not supported by the driver
 276      * @throws DriverException                  When the operation cannot be done
 277      */
 278     public function find($xpath);
 279
 280     /**
 281      * Returns element's tag name by it's XPath query.
 282      *
 283      * @param string $xpath
 284      *
 285      * @return string
 286      *
 287      * @throws UnsupportedDriverActionException When operation not supported by the driver
 288      * @throws DriverException                  When the operation cannot be done
 289      */
 290     public function getTagName($xpath);
 291
 292     /**
 293      * Returns element's text by it's XPath query.
 294      *
 295      * @param string $xpath
 296      *
 297      * @return string
 298      *
 299      * @throws UnsupportedDriverActionException When operation not supported by the driver
 300      * @throws DriverException                  When the operation cannot be done
 301      */
 302     public function getText($xpath);
 303
 304     /**
 305      * Returns element's inner html by it's XPath query.
 306      *
 307      * @param string $xpath
 308      *
 309      * @return string
 310      *
 311      * @throws UnsupportedDriverActionException When operation not supported by the driver
 312      * @throws DriverException                  When the operation cannot be done
 313      */
 314     public function getHtml($xpath);
 315
 316     /**
 317      * Returns element's outer html by it's XPath query.
 318      *
 319      * @param string $xpath
 320      *
 321      * @return string
 322      *
 323      * @throws UnsupportedDriverActionException When operation not supported by the driver
 324      * @throws DriverException                  When the operation cannot be done
 325      */
 326     public function getOuterHtml($xpath);
 327
 328     /**
 329      * Returns element's attribute by it's XPath query.
 330      *
 331      * @param string $xpath
 332      * @param string $name
 333      *
 334      * @return string|null
 335      *
 336      * @throws UnsupportedDriverActionException When operation not supported by the driver
 337      * @throws DriverException                  When the operation cannot be done
 338      */
 339     public function getAttribute($xpath, $name);
 340
 341     /**
 342      * Returns element's value by it's XPath query.
 343      *
 344      * @param string $xpath
 345      *
 346      * @return string|bool|array
 347      *
 348      * @throws UnsupportedDriverActionException When operation not supported by the driver
 349      * @throws DriverException                  When the operation cannot be done
 350      *
 351      * @see \Behat\Mink\Element\NodeElement::getValue
 352      */
 353     public function getValue($xpath);
 354
 355     /**
 356      * Sets element's value by it's XPath query.
 357      *
 358      * @param string            $xpath
 359      * @param string|bool|array $value
 360      *
 361      * @throws UnsupportedDriverActionException When operation not supported by the driver
 362      * @throws DriverException                  When the operation cannot be done
 363      *
 364      * @see \Behat\Mink\Element\NodeElement::setValue
 365      */
 366     public function setValue($xpath, $value);
 367
 368     /**
 369      * Checks checkbox by it's XPath query.
 370      *
 371      * @param string $xpath
 372      *
 373      * @throws UnsupportedDriverActionException When operation not supported by the driver
 374      * @throws DriverException                  When the operation cannot be done
 375      *
 376      * @see \Behat\Mink\Element\NodeElement::check
 377      */
 378     public function check($xpath);
 379
 380     /**
 381      * Unchecks checkbox by it's XPath query.
 382      *
 383      * @param string $xpath
 384      *
 385      * @throws UnsupportedDriverActionException When operation not supported by the driver
 386      * @throws DriverException                  When the operation cannot be done
 387      *
 388      * @see \Behat\Mink\Element\NodeElement::uncheck
 389      */
 390     public function uncheck($xpath);
 391
 392     /**
 393      * Checks whether checkbox or radio button located by it's XPath query is checked.
 394      *
 395      * @param string $xpath
 396      *
 397      * @return Boolean
 398      *
 399      * @throws UnsupportedDriverActionException When operation not supported by the driver
 400      * @throws DriverException                  When the operation cannot be done
 401      *
 402      * @see \Behat\Mink\Element\NodeElement::isChecked
 403      */
 404     public function isChecked($xpath);
 405
 406     /**
 407      * Selects option from select field or value in radio group located by it's XPath query.
 408      *
 409      * @param string  $xpath
 410      * @param string  $value
 411      * @param Boolean $multiple
 412      *
 413      * @throws UnsupportedDriverActionException When operation not supported by the driver
 414      * @throws DriverException                  When the operation cannot be done
 415      *
 416      * @see \Behat\Mink\Element\NodeElement::selectOption
 417      */
 418     public function selectOption($xpath, $value, $multiple = false);
 419
 420     /**
 421      * Checks whether select option, located by it's XPath query, is selected.
 422      *
 423      * @param string $xpath
 424      *
 425      * @return Boolean
 426      *
 427      * @throws UnsupportedDriverActionException When operation not supported by the driver
 428      * @throws DriverException                  When the operation cannot be done
 429      *
 430      * @see \Behat\Mink\Element\NodeElement::isSelected
 431      */
 432     public function isSelected($xpath);
 433
 434     /**
 435      * Clicks button or link located by it's XPath query.
 436      *
 437      * @param string $xpath
 438      *
 439      * @throws UnsupportedDriverActionException When operation not supported by the driver
 440      * @throws DriverException                  When the operation cannot be done
 441      */
 442     public function click($xpath);
 443
 444     /**
 445      * Double-clicks button or link located by it's XPath query.
 446      *
 447      * @param string $xpath
 448      *
 449      * @throws UnsupportedDriverActionException When operation not supported by the driver
 450      * @throws DriverException                  When the operation cannot be done
 451      */
 452     public function doubleClick($xpath);
 453
 454     /**
 455      * Right-clicks button or link located by it's XPath query.
 456      *
 457      * @param string $xpath
 458      *
 459      * @throws UnsupportedDriverActionException When operation not supported by the driver
 460      * @throws DriverException                  When the operation cannot be done
 461      */
 462     public function rightClick($xpath);
 463
 464     /**
 465      * Attaches file path to file field located by it's XPath query.
 466      *
 467      * @param string $xpath
 468      * @param string $path
 469      *
 470      * @throws UnsupportedDriverActionException When operation not supported by the driver
 471      * @throws DriverException                  When the operation cannot be done
 472      *
 473      * @see \Behat\Mink\Element\NodeElement::attachFile
 474      */
 475     public function attachFile($xpath, $path);
 476
 477     /**
 478      * Checks whether element visible located by it's XPath query.
 479      *
 480      * @param string $xpath
 481      *
 482      * @return Boolean
 483      *
 484      * @throws UnsupportedDriverActionException When operation not supported by the driver
 485      * @throws DriverException                  When the operation cannot be done
 486      */
 487     public function isVisible($xpath);
 488
 489     /**
 490      * Simulates a mouse over on the element.
 491      *
 492      * @param string $xpath
 493      *
 494      * @throws UnsupportedDriverActionException When operation not supported by the driver
 495      * @throws DriverException                  When the operation cannot be done
 496      */
 497     public function mouseOver($xpath);
 498
 499     /**
 500      * Brings focus to element.
 501      *
 502      * @param string $xpath
 503      *
 504      * @throws UnsupportedDriverActionException When operation not supported by the driver
 505      * @throws DriverException                  When the operation cannot be done
 506      */
 507     public function focus($xpath);
 508
 509     /**
 510      * Removes focus from element.
 511      *
 512      * @param string $xpath
 513      *
 514      * @throws UnsupportedDriverActionException When operation not supported by the driver
 515      * @throws DriverException                  When the operation cannot be done
 516      */
 517     public function blur($xpath);
 518
 519     /**
 520      * Presses specific keyboard key.
 521      *
 522      * @param string     $xpath
 523      * @param string|int $char     could be either char ('b') or char-code (98)
 524      * @param string     $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta')
 525      *
 526      * @throws UnsupportedDriverActionException When operation not supported by the driver
 527      * @throws DriverException                  When the operation cannot be done
 528      */
 529     public function keyPress($xpath, $char, $modifier = null);
 530
 531     /**
 532      * Pressed down specific keyboard key.
 533      *
 534      * @param string     $xpath
 535      * @param string|int $char     could be either char ('b') or char-code (98)
 536      * @param string     $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta')
 537      *
 538      * @throws UnsupportedDriverActionException When operation not supported by the driver
 539      * @throws DriverException                  When the operation cannot be done
 540      */
 541     public function keyDown($xpath, $char, $modifier = null);
 542
 543     /**
 544      * Pressed up specific keyboard key.
 545      *
 546      * @param string     $xpath
 547      * @param string|int $char     could be either char ('b') or char-code (98)
 548      * @param string     $modifier keyboard modifier (could be 'ctrl', 'alt', 'shift' or 'meta')
 549      *
 550      * @throws UnsupportedDriverActionException When operation not supported by the driver
 551      * @throws DriverException                  When the operation cannot be done
 552      */
 553     public function keyUp($xpath, $char, $modifier = null);
 554
 555     /**
 556      * Drag one element onto another.
 557      *
 558      * @param string $sourceXpath
 559      * @param string $destinationXpath
 560      *
 561      * @throws UnsupportedDriverActionException When operation not supported by the driver
 562      * @throws DriverException                  When the operation cannot be done
 563      */
 564     public function dragTo($sourceXpath, $destinationXpath);
 565
 566     /**
 567      * Executes JS script.
 568      *
 569      * @param string $script
 570      *
 571      * @throws UnsupportedDriverActionException When operation not supported by the driver
 572      * @throws DriverException                  When the operation cannot be done
 573      */
 574     public function executeScript($script);
 575
 576     /**
 577      * Evaluates JS script.
 578      *
 579      * The "return" keyword is optional in the script passed as argument. Driver implementations
 580      * must accept the expression both with and without the keyword.
 581      *
 582      * @param string $script
 583      *
 584      * @return mixed
 585      *
 586      * @throws UnsupportedDriverActionException When operation not supported by the driver
 587      * @throws DriverException                  When the operation cannot be done
 588      */
 589     public function evaluateScript($script);
 590
 591     /**
 592      * Waits some time or until JS condition turns true.
 593      *
 594      * @param int    $timeout   timeout in milliseconds
 595      * @param string $condition JS condition
 596      *
 597      * @return bool
 598      *
 599      * @throws UnsupportedDriverActionException When operation not supported by the driver
 600      * @throws DriverException                  When the operation cannot be done
 601      */
 602     public function wait($timeout, $condition);
 603
 604     /**
 605      * Set the dimensions of the window.
 606      *
 607      * @param int    $width  set the window width, measured in pixels
 608      * @param int    $height set the window height, measured in pixels
 609      * @param string $name   window name (null for the main window)
 610      *
 611      * @throws UnsupportedDriverActionException When operation not supported by the driver
 612      * @throws DriverException                  When the operation cannot be done
 613      */
 614     public function resizeWindow($width, $height, $name = null);
 615
 616     /**
 617      * Maximizes the window if it is not maximized already.
 618      *
 619      * @param string $name window name (null for the main window)
 620      *
 621      * @throws UnsupportedDriverActionException When operation not supported by the driver
 622      * @throws DriverException                  When the operation cannot be done
 623      */
 624     public function maximizeWindow($name = null);
 625
 626     /**
 627      * Submits the form.
 628      *
 629      * @param string $xpath Xpath.
 630      *
 631      * @throws UnsupportedDriverActionException When operation not supported by the driver
 632      * @throws DriverException                  When the operation cannot be done
 633      *
 634      * @see \Behat\Mink\Element\NodeElement::submitForm
 635      */
 636     public function submitForm($xpath);
 637 }