diff --git a/build/acceptance/features/core/NextcloudTestServerDockerHelper.php b/build/acceptance/features/core/NextcloudTestServerDockerHelper.php index 69dafc2276b..5e7c0b2df76 100644 --- a/build/acceptance/features/core/NextcloudTestServerDockerHelper.php +++ b/build/acceptance/features/core/NextcloudTestServerDockerHelper.php @@ -24,14 +24,13 @@ /** * Helper to manage the Docker container for the Nextcloud test server. * - * The NextcloudTestServerDockerHelper abstracts the calls to the Docker Command - * Line Interface (the "docker" command) to run, get information from, and - * destroy containers. It is not a generic abstraction, but one tailored - * specifically to the Nextcloud test server; a Docker image that provides an - * installed and ready to run Nextcloud server with the configuration and data - * expected by the acceptance tests must be available in the system. The - * Nextcloud server must use a local storage so all the changes it makes are - * confined to its running container. + * The NextcloudTestServerDockerHelper provides a Nextcloud test server using a + * Docker container. The "setUp" method creates and starts the container, while + * the "cleanUp" method destroys it. A Docker image that provides an installed + * and ready to run Nextcloud server with the configuration and data expected by + * the acceptance tests must be available in the system. The Nextcloud server + * must use a local storage so all the changes it makes are confined to its + * running container. * * Also, the Nextcloud server installed in the Docker image is expected to see * "127.0.0.1" as a trusted domain (which would be the case if it was installed @@ -42,8 +41,10 @@ * untrusted domain and refuse to work until the admin whitelisted it. The base * URL to access the Nextcloud server can be got from "getBaseUrl". * - * For better compatibility, Docker CLI commands used internally follow the - * pre-1.13 syntax (also available in 1.13 and newer). For example, + * Internally, the NextcloudTestServerDockerHelper uses the Docker Command Line + * Interface (the "docker" command) to run, get information from, and destroy + * the container, For better compatibility, the used Docker CLI commands follow + * the pre-1.13 syntax (also available in 1.13 and newer). For example, * "docker start" instead of "docker container start". * * In any case, the "docker" command requires special permissions to talk to the @@ -65,7 +66,7 @@ * just a warning for the test runner and nothing to be explicitly catched a * plain base Exception is used. */ -class NextcloudTestServerDockerHelper { +class NextcloudTestServerDockerHelper implements NextcloudTestServerHelper { /** * @var string diff --git a/build/acceptance/features/core/NextcloudTestServerHelper.php b/build/acceptance/features/core/NextcloudTestServerHelper.php new file mode 100644 index 00000000000..198d78e3fcb --- /dev/null +++ b/build/acceptance/features/core/NextcloudTestServerHelper.php @@ -0,0 +1,73 @@ +. + * + */ + +/** + * Interface for classes that manage a Nextcloud server during acceptance tests. + * + * A NextcloudTestServerHelper takes care of setting up a Nextcloud server to be + * used in acceptance tests through its "setUp" method. It does not matter + * wheter the server is a fresh new server just started or an already running + * server; in any case, the state of the server must comply with the initial + * state expected by the tests (like having performed the Nextcloud installation + * or having an admin user with certain password). + * + * As the IP address and thus its the base URL of the server is not known + * beforehand, the NextcloudTestServerHelper must provide it through its + * "getBaseUrl" method. Note that this must be the base URL from the point of + * view of the Selenium server, which may be a different value than the base URL + * from the point of view of the acceptance tests themselves. + * + * Once the Nextcloud test server is no longer needed the "cleanUp" method will + * be called; depending on how the Nextcloud test server was set up it may not + * need to do anything. + * + * All the methods throw an exception if they fail to execute; as, due to the + * current use of this interface, it is just a warning for the test runner and + * nothing to be explicitly catched a plain base Exception is used. + */ +interface NextcloudTestServerHelper { + + /** + * Sets up the Nextcloud test server. + * + * @throws \Exception if the Nextcloud test server can not be set up. + */ + public function setUp(); + + /** + * Cleans up the Nextcloud test server. + * + * @throws \Exception if the Nextcloud test server can not be cleaned up. + */ + public function cleanUp(); + + /** + * Returns the base URL of the Nextcloud test server (from the point of view + * of the Selenium server). + * + * @return string the base URL of the Nextcloud test server. + * @throws \Exception if the base URL can not be determined. + */ + public function getBaseUrl(); + +}