Add doc for extractor mocks

docs/05_Mock_tests.md

@@ -0,0 +1,57 @@
+# Mock Tests
+
+A web crawler is by nature dependant on the external service which it is crawling.
+In order to have a reliable CI pipeline, this external dependency needs to be removed.
+For this there is a system in place to automatically save the requests made to a service and their responses.
+These can then be used in CI to reliably test changes made to the Extractor and not have test failures due to API changes on the side of the service.
+
+## Multiple downloader implementations
+
+There are multiple implementations of the abstract class `Downloader`
+
+1. `DownloaderTestImpl` is used for running the test against the actual service.
+2. `RecordingDownloader` is used the save the request and response to the disk, thus creating the mock.
+3. `MockDownloader` is used to answer requests with the saved mocks.
+
+### Usage
+
+There are 2 ways to specify which downloader should be used.
+
+First one is passing the `-Ddownloader=<value>` argument from the command line, where `value` can be one of
+[DownloaderType](https://github.com/TeamNewPipe/NewPipeExtractor/blob/dev/extractor/src/test/java/org/schabi/newpipe/downloader/DownloaderType.java)
+. The main usecase is in the CI pipeline like this: `./gradlew check --stacktrace -Ddownloader=MOCK`.  
+Other than that it can also be used to mass generate mocks by specifying which package should be tested. As example if
+one wanted to update all YouTube mocks:
+`gradle clean test --tests 'org.schabi.newpipe.extractor.services.youtube.*' -Ddownloader=RECORDING`
+
+The second way is changing the field `DownloaderFactory.DEFAULT_DOWNLOADER`.
+The default value is `DownloaderType.REAL` which should be changed on the master branch.
+Locally one can change this to `DownloaderType.RECORDING`, run the tests and commit
+the generated mocks.  
+This is the main use case for when developing locally.
+
+### Mock only tests
+
+There are some things which cannot ever be tested reliably against an actual service.
+For example tests for an upcoming livestream would fail, after the livestream was started.
+
+For this there is a marker interface `MockOnly` and a custom TestRule `MockOnlyRule`.
+It skips the tests in the CI pipeline if they are not run with mocks.
+
+See `MockOnlyRule` for further details.
+
+Example usage:
+
+``` java
+public static class TestClass {
+
+     @Rule
+     public MockOnlyRule rule = new MockOnlyRule();
+
+     @MockOnly
+     @Test
+     public void myTest() throws Exception {
+         //assertions
+     }
+}
+```