implement acceptance tests in docker for dev machine

docs/ocis/development/testing.md

@@ -9,7 +9,79 @@ geekdocFilePath: testing.md
 
 {{< toc >}}
 
-## Acceptance tests
+For running tests in the test suite you have two options. You may go the easy way and just run the test suite in docker. But for some tasks you could also need to install the test suite natively, which requires a little bit more setup since PHP and some dependencies need to be installed.
+
+Both ways to run tests with the test suites are described here.
+
+## Testing with test suite in docker
+
+Let's see what is available. Invoke the following command from within the root of the oCIS repository.
+
+```
+make -C tests/acceptance/docker help
+```
+
+Basically we have two sources for feature tests and test suites:
+
+- [oCIS feature test and test suites](https://github.com/owncloud/ocis/tree/master/tests/acceptance/features)
+- [ownCloud feature tests and test suites](https://github.com/owncloud/core/tree/master/tests/acceptance/features)
+
+At the moment both can be applied to oCIS since the api of oCIS is designed to be compatible to ownCloud.
+
+Since we have to offer an migration path to existing users of ownCloud, you can use your existing ownCloud as storage backend for oCIS. As another storage backend we offer oCIS native storage, also called "oCIS". This stores files directly on disk. Which storage backend is used is also reflected in the tests, there are always different tests for oCIS storage and ownCloud storage.
+
+You can invoke two types of test suite runs:
+
+- run a full test suite, which consists of multiple feature tests
+- run a single feature test
+
+### Run full test suite
+
+The names of the full test suite make targets have the same naming as in the CI pipeline.
+
+For example `make -C tests/acceptance/docker localApiTests-apiOcisSpecific-ocis` runs the same tests as the `localApiTests-apiOcisSpecific-ocis` CI pipeline, which runs the oCIS test suite "apiOcisSpecific" against an oCIS with oCIS storage.
+
+For example `make -C tests/acceptance/docker Core-API-Tests-owncloud-storage-3`runs the same tests as the `Core-API-Tests-owncloud-storage-3` CI pipline, which runs the third (out of ten) ownCloud test suite against an oCIS with owncloud storage.
+
+### Run single feature test
+
+The single feature tests can also be run against the different storage backends. Therefore multiple make targets with the schema test-<test source>-feature-<storage backend> exists. For selecting a single feature test you have to add an additional `BEHAT_FEATURE=...` parameter when invoking the make command:
+
+```
+make -C tests/acceptance/docker test-ocis-feature-ocis BEHAT_FEATURE='tests/acceptance/features/apiOcisSpecific/apiAuthOcs-ocsDELETEAuth.feature'
+```
+
+This must be pointing to a valid feature definition.
+
+### oCIS image to be tested (or: skip build and take existing image)
+
+By default the tests will be run against docker image built from your current working state of the oCIS repository. For some purposes it might also be handy to use a oCIS image from Docker Hub. Therefore you can provide the optional flag `OCIS_IMAGE_TAG=...` which must contain an available docker tag of the [owncloud/ocis registry on Docker Hub](https://hub.docker.com/r/owncloud/ocis) (eg. 'latest').
+
+```
+make -C tests/acceptance/docker localApiTests-apiOcisSpecific-ocis OCIS_IMAGE_TAG=latest
+```
+
+### Test log output
+
+While a test is running or when it is finished, you can attach to the logs generated by the tests.
+
+```
+make -C tests/acceptance/docker show-test-logs
+```
+
+{{< hint info >}}
+The log output is opened in `less`. You can navigate up and down with your cursors. By pressing "F" you can follow the latest line of the output.
+{{< /hint >}}
+
+### Cleanup
+
+During testing we start an redis and oCIS docker container. These will not be stopped automatically. You can stop them with:
+
+```
+make -C tests/acceptance/docker clean
+```
+
+## Testing with test suite natively installed
 
 We are using the ownCloud 10 acceptance test suite against oCIS. To set this up you need the ownCloud 10 core repo, a LDAP server that the acceptance tests can use to manage users, a redis server for file-versions and the oCIS code.