Copy files from codeception/codeception

Author: Naktibalda

composer.json

@@ -13,7 +13,8 @@
     ],
     "homepage": "https://codeception.com/",
     "require": {
-        "php": "^8.0"
+        "php": "^8.0",
+        "phpunit/phpunit": "^9.5 | ^10.0"
     },
     "conflict": {
         "codeception/codeception": "<5.0.0-alpha3"

src/Constraint/Page.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codeception\Constraint;
+
+use Codeception\Lib\Console\Message;
+use PHPUnit\Framework\Constraint\Constraint;
+
+use function codecept_output_dir;
+use function mb_stripos;
+use function mb_strlen;
+use function mb_substr;
+use function preg_replace;
+use function sprintf;
+use function strtr;
+use function trim;
+
+class Page extends Constraint
+{
+    /**
+     * @var string
+     */
+    protected $uri;
+    /**
+     * @var string
+     */
+    protected $string;
+
+    public function __construct(string $string, string $uri = '')
+    {
+        $this->string = $this->normalizeText($string);
+        $this->uri = $uri;
+    }
+
+    /**
+     * Evaluates the constraint for parameter $other. Returns true if the
+     * constraint is met, false otherwise.
+     *
+     * @param string $other Value or object to evaluate.
+     * @return bool
+     */
+    protected function matches($other): bool
+    {
+        $other = $this->normalizeText($other);
+        return mb_stripos($other, $this->string, 0, 'UTF-8') !== false;
+    }
+
+    private function normalizeText(string $text): string
+    {
+        $text = strtr($text, "\r\n", "  ");
+        return trim(preg_replace('/\\s{2,}/', ' ', $text));
+    }
+
+    /**
+     * Returns a string representation of the constraint.
+     */
+    public function toString(): string
+    {
+        return sprintf(
+            'contains "%s"',
+            $this->string
+        );
+    }
+
+    /**
+     * @param string $pageContent
+     */
+    protected function failureDescription($pageContent): string
+    {
+        $message = $this->uriMessage('on page');
+        $message->append("\n--> ");
+        $message->append(mb_substr($pageContent, 0, 300, 'utf-8'));
+        if (mb_strlen($pageContent, 'utf-8') > 300) {
+            $debugMessage = new Message(
+                "[Content too long to display. See complete response in '" . codecept_output_dir() . "' directory]"
+            );
+            $message->append("\n")->append($debugMessage);
+        }
+        $message->append("\n--> ");
+        return $message->getMessage() . $this->toString();
+    }
+
+    protected function uriMessage(string $onPage = ''): Message
+    {
+        if (!$this->uri) {
+            return new Message('');
+        }
+        $message = new Message($this->uri);
+        $message->prepend(" {$onPage} ");
+        return $message;
+    }
+}

src/Exception/ElementNotFound.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codeception\Exception;
+
+use Codeception\Util\Locator;
+use PHPUnit\Framework\AssertionFailedError;
+
+use function is_string;
+
+class ElementNotFound extends AssertionFailedError
+{
+    public function __construct($selector, string $message = '')
+    {
+        if (!is_string($selector) || !str_contains($selector, "'")) {
+            $selector = Locator::humanReadableString($selector);
+        }
+        parent::__construct("{$message} element with {$selector} was not found.");
+    }
+}

src/Exception/MalformedLocatorException.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codeception\Exception;
+
+use function ucfirst;
+
+class MalformedLocatorException extends TestRuntimeException
+{
+    public function __construct(string $locator, string $type = 'CSS or XPath')
+    {
+        parent::__construct(ucfirst($type) . " locator is malformed: {$locator}");
+    }
+}

src/Lib/Interfaces/ElementLocator.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Codeception\Lib\Interfaces;
+
+use Symfony\Component\DomCrawler\Crawler;
+
+interface ElementLocator
+{
+    /**
+     * Locates element using available Codeception locator types:
+     *
+     * * XPath
+     * * CSS
+     * * Strict Locator
+     *
+     * Use it in Helpers or GroupObject or Extension classes:
+     *
+     * ```php
+     * <?php
+     * $els = $this->getModule('{{MODULE_NAME}}')->_findElements('.items');
+     * $els = $this->getModule('{{MODULE_NAME}}')->_findElements(['name' => 'username']);
+     *
+     * $editLinks = $this->getModule('{{MODULE_NAME}}')->_findElements(['link' => 'Edit']);
+     * // now you can iterate over $editLinks and check that all them have valid hrefs
+     * ```
+     *
+     * WebDriver module returns `Facebook\WebDriver\Remote\RemoteWebElement` instances
+     * PhpBrowser and Framework modules return `Symfony\Component\DomCrawler\Crawler` instances
+     *
+     * @return Crawler|array of interactive elements
+     * @api
+     */
+    public function _findElements(mixed $locator): iterable;
+}

src/Lib/Interfaces/MultiSession.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Codeception\Lib\Interfaces;
+
+interface MultiSession
+{
+    public function _initializeSession(): void;
+
+    public function _loadSession($session): void;
+
+    public function _backupSession();
+
+    public function _closeSession($session = null): void;
+
+    public function _getName(): string;
+}

src/Lib/Interfaces/PageSourceSaver.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Codeception\Lib\Interfaces;
+
+interface PageSourceSaver
+{
+    /**
+     * Saves page source of to a file
+     *
+     * ```php
+     * $this->getModule('{{MODULE_NAME}}')->_savePageSource(codecept_output_dir().'page.html');
+     * ```
+     * @api
+     */
+    public function _savePageSource(string $filename): void;
+
+    /**
+     * Use this method within an [interactive pause](https://codeception.com/docs/02-GettingStarted#Interactive-Pause) to save the HTML source code of the current page.
+     *
+     * ```php
+     * <?php
+     * $I->makeHtmlSnapshot('edit_page');
+     * // saved to: tests/_output/debug/edit_page.html
+     * $I->makeHtmlSnapshot();
+     * // saved to: tests/_output/debug/2017-05-26_14-24-11_4b3403665fea6.html
+     * ```
+     */
+    public function makeHtmlSnapshot(string $name = null): void;
+}

src/Lib/Interfaces/Remote.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Codeception\Lib\Interfaces;
+
+interface Remote
+{
+    /**
+     * Changes the subdomain for the 'url' configuration parameter.
+     * Does not open a page; use `amOnPage` for that.
+     *
+     * ``` php
+     * <?php
+     * // If config is: 'https://mysite.com'
+     * // or config is: 'https://www.mysite.com'
+     * // or config is: 'https://company.mysite.com'
+     *
+     * $I->amOnSubdomain('user');
+     * $I->amOnPage('/');
+     * // moves to https://user.mysite.com/
+     * ```
+     *
+     */
+    public function amOnSubdomain(string $subdomain): void;
+
+    /**
+     * Open web page at the given absolute URL and sets its hostname as the base host.
+     *
+     * ``` php
+     * <?php
+     * $I->amOnUrl('https://codeception.com');
+     * $I->amOnPage('/quickstart'); // moves to https://codeception.com/quickstart
+     * ```
+     */
+    public function amOnUrl(string $url): void;
+
+    public function _getUrl();
+}

src/Lib/Interfaces/ScreenshotSaver.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Codeception\Lib\Interfaces;
+
+interface ScreenshotSaver
+{
+    /**
+     * Saves screenshot of current page to a file
+     *
+     * ```php
+     * $this->getModule('{{MODULE_NAME}}')->_saveScreenshot(codecept_output_dir().'screenshot_1.png');
+     * ```
+     * @api
+     */
+    public function _saveScreenshot(string $filename);
+}

src/Lib/Interfaces/SessionSnapshot.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Codeception\Lib\Interfaces;
+
+interface SessionSnapshot
+{
+    /**
+     * Saves current cookies into named snapshot in order to restore them in other tests
+     * This is useful to save session state between tests.
+     * For example, if user needs log in to site for each test this scenario can be executed once
+     * while other tests can just restore saved cookies.
+     *
+     * ``` php
+     * <?php
+     * // inside AcceptanceTester class:
+     *
+     * public function login()
+     * {
+     *      // if snapshot exists - skipping login
+     *      if ($I->loadSessionSnapshot('login')) return;
+     *
+     *      // logging in
+     *      $I->amOnPage('/login');
+     *      $I->fillField('name', 'jon');
+     *      $I->fillField('password', '123345');
+     *      $I->click('Login');
+     *
+     *      // saving snapshot
+     *      $I->saveSessionSnapshot('login');
+     * }
+     * ```
+     *
+     * @return mixed
+     */
+    public function saveSessionSnapshot(string $name);
+
+    /**
+     * Loads cookies from a saved snapshot.
+     * Allows to reuse same session across tests without additional login.
+     *
+     * See [saveSessionSnapshot](#saveSessionSnapshot)
+     *
+     * @return mixed
+     */
+    public function loadSessionSnapshot(string $name);
+
+    /**
+     * Deletes session snapshot.
+     *
+     * See [saveSessionSnapshot](#saveSessionSnapshot)
+     *
+     * @return mixed
+     */
+    public function deleteSessionSnapshot(string $name);
+}