Extract NextcloudTestServerHelper interface

The NextcloudTestServerHelper interface provides the needed methods to
manage the Nextcloud server used in acceptance tests.

Signed-off-by: Daniel Calviño Sánchez <danxuliu@gmail.com>

2 files changed, 85 insertions, 11 deletions

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 @@
+<?php
+
+/**
+ *
+ * @copyright Copyright (c) 2017, Daniel Calviño Sánchez (danxuliu@gmail.com)
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+/**
+ * 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();
+
+}