Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add doc for extractor mocks #31

Merged
merged 5 commits into from
Nov 28, 2021
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions docs/05_Mock_tests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Mock Tests

A web crawler is, by its very nature, dependent 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, as well as the responses received.
These can then be used in the CI pipeline to reliably test changes made to the Extractor, and avoid 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 to save the request and response to a file, thus creating the mock.
3. `MockDownloader` is used to answer requests using 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 use case 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. For 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.
XiangRongLin marked this conversation as resolved.
Show resolved Hide resolved
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 starts.

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
}
}
```
File renamed without changes.
File renamed without changes.
File renamed without changes.