Add doc for extractor mocks

This commit is contained in:
XiangRongLin 2021-05-30 21:28:58 +02:00
parent a05b04c778
commit b830bda352
4 changed files with 57 additions and 0 deletions

57
docs/05_Mock_tests.md Normal file
View File

@ -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
}
}
```