[docs-only] Document running tests using ociswrapper (#6283)

* add README for ociswrapper

* add doc on how to tests env config test suites with ociswrapper

* document running tests using ociswrapper

* update local docker compose setup for running tests

* make ocis able to run with ociswrapper

* update wrapper doc

* run with ociswrapper by default

* ignore md files on codacy

* fix README format

docs/ocis/development/testing.md

@@ -45,7 +45,17 @@ For example `make -C tests/acceptance/docker localApiTests-apiAccountsHashDiffic
 
 For example `make -C tests/acceptance/docker localApiTests-apiAccountsHashDifficulty-s3ng` runs the oCIS test suite "apiAccountsHashDifficulty" against an oCIS with s3 storage.
 
-> Note: To run the tests from `apiAsyncUpload` suite you need to provide extra environment variable `POSTPROCESSING_DELAY`
+{{< hint info >}}
+While running the tests, oCIS server is started with [ociswrapper](https://github.com/owncloud/ocis/blob/master/tests/ociswrapper/README.md) (i.e. `WITH_WRAPPER=true`) by default. In order to run the tests without ociswrapper, provide `WITH_WRAPPER=false` when running the tests. For example:
+
+```bash
+WITH_WRAPPER=false \
+BEHAT_FEATURE='tests/acceptance/features/apiAccountsHashDifficulty/addUser.feature:21' \
+make -C tests/acceptance/docker test-ocis-feature-ocis-storage
+```
+
+But some test suites that are tagged with `@env-config` require the oCIS server to be run with ociswrapper. So, running those tests require `WITH_WRAPPER=true` (default setting).
+{{< /hint >}}
 
 For example `make -C tests/acceptance/docker Core-API-Tests-ocis-storage-3` runs the same tests as the `Core-API-Tests-ocis-storage-3` CI pipeline, which runs the third (out of ten) test suite transferred from ownCloud against an oCIS with ocis storage.
 
@@ -210,6 +220,47 @@ If you want to work on a specific issue
 5. remove those tests from the expected failures file
 6. make a PR that has the fixed code, and the relevant lines removed from the expected failures file.
 
+## Running ENV config tests (@env-config)
+
+Test suites tagged with `@env-config` are used to test the environment variables that are used to configure oCIS. These tests are special tests that require the oCIS server to be run using [ociswrapper](https://github.com/owncloud/ocis/blob/master/tests/ociswrapper/README.md).
+
+### Run oCIS with ociswrapper
+
+```bash
+# working dir: ocis repo root dir
+
+# init oCIS
+IDM_ADMIN_PASSWORD=admin \
+ocis/bin/ocis init --insecure true
+
+# build the wrapper
+cd tests/ociswrapper
+make build
+
+# run oCIS
+PROXY_ENABLE_BASIC_AUTH=true \
+./bin/ociswrapper serve --bin=../../ocis/bin/ocis
+```
+
+### Run the tests
+
+```bash
+OCIS_WRAPPER_URL=http://localhost:5000 \
+TEST_WITH_GRAPH_API=true \
+TEST_OCIS=true \
+TEST_SERVER_URL="https://localhost:9200" \
+BEHAT_FEATURE=tests/acceptance/features/apiAsyncUpload/delayPostprocessing.feature \
+make test-acceptance-api
+```
+
+### Writing new ENV config tests
+
+While writing tests for a new oCIS ENV configuration, please make sure to follow these guidelines:
+
+1. Tag the test suite (or test scenarios) with `@env-config`
+2. Use `OcisConfigHelper.php` for helper functions - provides functions to reconfigure the running oCIS instance.
+3. Recommended: add the new step implementations in `OcisConfigContext.php`
+
 ## Running tests for parallel deployment
 
 ### Setup the parallel deployment environment

tests/acceptance/docker/Makefile

@@ -26,6 +26,10 @@ else
 endif
 OCIS_IMAGE_TAG ?= dev
 
+# run tests with ociswrapper by default
+WITH_WRAPPER ?= true
+OCIS_WRAPPER := ../../ociswrapper/bin/ociswrapper
+
 # static
 DIVIDE_INTO_NUM_PARTS := 10
 PARTS = 1 2 3 4 5 6 7 8 9 10
@@ -171,7 +175,7 @@ $(targets):
 	$(MAKE) --no-print-directory testSuite
 
 .PHONY: testSuite
-testSuite: build-dev-image clean-docker-container
+testSuite: $(OCIS_WRAPPER) build-dev-image clean-docker-container
 	@if [ -n "${START_CEPH}" ]; then \
 		COMPOSE_PROJECT_NAME=$(COMPOSE_PROJECT_NAME) \
 		COMPOSE_FILE=src/ceph.yml \
@@ -181,6 +185,7 @@ testSuite: build-dev-image clean-docker-container
 	COMPOSE_FILE=$(COMPOSE_FILE) \
 	STORAGE_DRIVER=$(STORAGE_DRIVER) \
 	TEST_SOURCE=$(TEST_SOURCE) \
+	WITH_WRAPPER=$(WITH_WRAPPER) \
 	OCIS_IMAGE_TAG=$(OCIS_IMAGE_TAG) \
 	BEHAT_SUITE=$(BEHAT_SUITE) \
 	BEHAT_FEATURE=$(BEHAT_FEATURE) \
@@ -194,9 +199,13 @@ show-test-logs: ## show logs of test
 	COMPOSE_FILE=$(COMPOSE_FILE) \
 	docker-compose logs --no-log-prefix -f acceptance-tests | less
 
+$(OCIS_WRAPPER):
+	@if [ "$(WITH_WRAPPER)" == "true" ]; then \
+		$(MAKE) --no-print-directory -C ../../ociswrapper build \
+	; fi;
+
 .PHONY: build-dev-image
 build-dev-image:
-	@rm -rf ../../../vendor
 	@if [ $(BUILD_DEV_IMAGE) -eq 1 ]; then \
 		$(MAKE) --no-print-directory -C ../../../ocis dev-docker \
 	; fi;

tests/acceptance/docker/src/acceptance.yml

@@ -1,6 +1,7 @@
 services:
   acceptance-tests:
     image: owncloudci/php:7.4
+    working_dir: /drone/src
     command: /bin/bash /test/run-tests.sh
     environment:
       OCIS_ROOT: /drone/src
@@ -8,7 +9,7 @@ services:
       RUN_ON_OCIS: "true"
       TEST_SERVER_URL: https://ocis-server:9200
       TEST_WITH_GRAPH_API: "true"
-
+      OCIS_WRAPPER_URL: http://ocis-server:5000
       STORAGE_DRIVER: $STORAGE_DRIVER
       TEST_SOURCE: $TEST_SOURCE
       BEHAT_SUITE: ${BEHAT_SUITE:-}

tests/acceptance/docker/src/ocis-base.yml

@@ -1,8 +1,13 @@
 services:
   ocis-server:
-    image: owncloud/ocis:$OCIS_IMAGE_TAG
+    build:
+      dockerfile: ocis.Dockerfile
+      context: ./
+      args:
+        OCIS_IMAGE_TAG: $OCIS_IMAGE_TAG
     user: root
     environment:
+      WITH_WRAPPER: $WITH_WRAPPER
       OCIS_URL: "https://ocis-server:9200"
       STORAGE_USERS_DRIVER: $STORAGE_DRIVER
       STORAGE_USERS_DRIVER_LOCAL_ROOT: /srv/app/tmp/ocis/local/root
@@ -14,14 +19,9 @@ services:
       WEB_UI_CONFIG: /drone/src/tests/config/drone/ocis-config.json
       ACCOUNTS_HASH_DIFFICULTY: 4
       OCIS_INSECURE: "true"
-      "IDM_CREATE_DEMO_USERS": "true"
+      IDM_CREATE_DEMO_USERS: "true"
-      "IDM_ADMIN_PASSWORD": "admin"
+      IDM_ADMIN_PASSWORD: "admin"
-      "FRONTEND_SEARCH_MIN_LENGTH": "2"
+      FRONTEND_SEARCH_MIN_LENGTH: "2"
-
-      "OCIS_CORS_ALLOW_ORIGINS": "https://aphno.badal"
-
-      "POSTPROCESSING_DELAY": ${POSTPROCESSING_DELAY:-0s}
-
       # s3ng specific settings
       STORAGE_USERS_S3NG_ENDPOINT: http://ceph:8080
       STORAGE_USERS_S3NG_REGION: default
@@ -30,8 +30,4 @@ services:
       STORAGE_USERS_S3NG_BUCKET: test
     volumes:
       - ../../../config:/drone/src/tests/config
-    entrypoint: /bin/sh
+      - ../../../ociswrapper/bin/ociswrapper:/usr/bin/ociswrapper
-    # run ocis init to initialize a configuration file with random secrets
-    # it will fail on subsequent runs, because the config file already exists
-    # therefore we ignore the error and then start the ocis server
-    command: ["-c", "ocis init || true; ocis server"]

tests/acceptance/docker/src/ocis.Dockerfile

@@ -0,0 +1,13 @@
+# custom Dockerfile required to run ociswrapper command
+# mounting 'ociswrapper' binary doesn't work with image 'amd64/alpine:3.17' (busybox based)
+
+ARG OCIS_IMAGE_TAG
+FROM owncloud/ocis:${OCIS_IMAGE_TAG} as ocis
+
+FROM ubuntu:22.04
+COPY --from=ocis /usr/bin/ocis /usr/bin/ocis
+
+COPY ["./serve-ocis.sh", "/usr/bin/serve-ocis"]
+RUN chmod +x /usr/bin/serve-ocis
+
+ENTRYPOINT [ "serve-ocis" ]

tests/acceptance/docker/src/serve-ocis.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -e
+
+# init ocis
+ocis init
+
+if [ "$WITH_WRAPPER" = "true" ]; then
+    ociswrapper serve --bin=ocis
+else
+    ocis server
+fi

tests/ociswrapper/README.md

@@ -0,0 +1,54 @@
+## oCIS Wrapper
+
+A tool that wraps the oCIS binary and provides a way to re-configure the running oCIS instance.
+
+When run, **ociswrapper** starts an API server that exposes some endpoints to re-configure the oCIS server.
+
+### Usage
+
+1.  Build
+
+    ```bash
+    make build
+    ```
+
+2.  Run
+
+    ```bash
+    ./bin/ociswrapper serve --bin=<path-to-ocis-binary>
+    ```
+
+Access the API server at `http://localhost:5000`.
+
+Also, see `./bin/ociswrapper help` for more information.
+
+### API
+
+**ociswrapper** exposes two endpoints:
+
+1.  `PUT /config`
+
+    Updates the configuration of the running oCIS instance.
+    Body of the request should be a JSON object with the following structure:
+
+    ```json
+    {
+      "ENV_KEY1": "value1",
+      "ENV_KEY2": "value2"
+    }
+    ```
+
+    Returns:
+
+    *   `200 OK` - oCIS is successfully reconfigured
+    *   `400 Bad Request` - request body is not a valid JSON object
+    *   `500 Internal Server Error` - oCIS server is not running
+
+2.  `DELETE /rollback`
+
+    Rolls back the configuration to the starting point.
+
+    Returns:
+
+    *   `200 OK` - rollback is successful
+    *   `500 Internal Server Error` - oCIS server is not running