From b830bda352c522583238c80bc777e959ad1f02b6 Mon Sep 17 00:00:00 2001
From: XiangRongLin <41164160+XiangRongLin@users.noreply.github.com>
Date: Sun, 30 May 2021 21:28:58 +0200
Subject: [PATCH] Add doc for extractor mocks

---
 docs/05_Mock_tests.md                         | 57 +++++++++++++++++++
 docs/{05_releasing.md => 06_releasing.md}     |  0
 ...6_documentation.md => 07_documentation.md} |  0
 ...tainers_view.md => 08_maintainers_view.md} |  0
 4 files changed, 57 insertions(+)
 create mode 100644 docs/05_Mock_tests.md
 rename docs/{05_releasing.md => 06_releasing.md} (100%)
 rename docs/{06_documentation.md => 07_documentation.md} (100%)
 rename docs/{07_maintainers_view.md => 08_maintainers_view.md} (100%)

diff --git a/docs/05_Mock_tests.md b/docs/05_Mock_tests.md
new file mode 100644
index 0000000..cb43525
--- /dev/null
+++ b/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
+     }
+}
+```
\ No newline at end of file
diff --git a/docs/05_releasing.md b/docs/06_releasing.md
similarity index 100%
rename from docs/05_releasing.md
rename to docs/06_releasing.md
diff --git a/docs/06_documentation.md b/docs/07_documentation.md
similarity index 100%
rename from docs/06_documentation.md
rename to docs/07_documentation.md
diff --git a/docs/07_maintainers_view.md b/docs/08_maintainers_view.md
similarity index 100%
rename from docs/07_maintainers_view.md
rename to docs/08_maintainers_view.md