@bharper/atv-js 0.2.6 → 0.3.4

package/pyatv/docs/internals/internals.md

@@ -0,0 +1,157 @@
+---
+layout: template
+title: Internals
+permalink: /internals/
+link_group: internals
+---
+# :microscope: Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Internals
+
+Welcome to the developer documentation for pyatv, i.e. the documentation explaining how
+pyatv works (internally) and how to extend it. This section used to reside in the
+GitHub wiki, but has moved to the general documentation for greater availability. It is
+still under heavy development, so beware of missing and/or outdated content as it is
+migrated from the wiki.
+
+# Setting up a New Environment
+
+## Linux/macOS/*NIX
+
+You can run the script `scripts/setup_dev_env.sh` to set up a complete development environment. It will make sure that everything works as expected by running `chickn`, building documentation (with docker), etc.
+
+```shell
+$ ./scripts/setup_dev_env.sh
+$ ./scripts/chickn.py
+```
+
+## Windows
+
+There's no helper script for windows, but you can get started manually like this:
+
+```shell
+$ git clone https://github.com/postlund/pyatv.git
+$ cd pyatv
+$ python3 -m venv venv
+$ source venv/Scripts/activate
+$ python setup.py develop
+$ pip install pyyaml -r requirements/requirements_test.txt -r requirements/requirements_docs.txt
+$ python scripts/chickn.py
+```
+
+# Testing Changes
+
+If you followed the instructions above, then pyatv will be installed as "develop". This means that you can keep doing updates without having to do `python setup.py install` between changes.
+
+## Testing with chickn
+
+To test everything, just run `./scripts/chickn.py`:
+
+```shell
+$ ./scripts/chickn.py
+```
+
+This will make sure that tests pass, you have followed coding guidelines (pylint, flake8, etc), verify protobuf messages and generate coverage data. `chickn` is developed for pyatv and the documentation for it is
+[here](tools/#chickn). The configuration file is [here](https://github.com/postlund/pyatv/blob/master/pyatv/chickn.yaml)
+
+You can run steps individually as well:
+
+| What | Command |
+| ---- | ------- |
+| tests | ./scripts/chickn.py pytest
+| pylint | ./scripts/chickn.py pylint
+| protobuf | ./scripts/chickn.py protobuf
+| api | ./scripts/chickn.py api
+
+All available steps can be listed with `./scripts/chickn.py -l`:
+
+```raw
+$ ./scripts/chickn.py -l
+clean, fixup, pylint, api, protobuf, flake8, black, pydocstyle, isort, cs_docs, cs_code, typing, pytest, report, dist
+```
+
+The `fixup` will run black and isort to clean up basic mistakes before running rest of the commands.
+So it can be convenient to enable that step with the `fixup` tag:
+
+```raw
+./scripts/chickn.py -t fixup
+```
+
+Generally, `chickn` will install the latest version of all dependencies. There's however a
+wish to verify that everything works the lowest version that pyatv supports. This is denoted
+as "regression" in GitHub actions. These versions are listed in {% include code file="../base_versions.txt" %}
+and can be manually overridden when needed:
+
+```raw
+$ ./scripts/chickn.py -v requirements_file=base_versions.txt
+2021-10-24 11:16:19 [INFO] Installing dependencies
+2021-10-24 11:16:19 [INFO] Re-installing packages with mismatching versions: aiohttp==3.1.0 (3.7.4), bitarray==2.1.2 (2.3.4), cryptography==2.6 (35.0.0), netifaces==0.10.0 (0.11.0), protobuf==3.18.0 (3.19.0), srptools==0.2.0 (1.0.1), zeroconf==0.28.2 (0.36.8)
+...
+```
+
+You generally do not need to do this yourself as it is tested automatically by GitHub Actions.
+
+## Updating protobuf Definitions
+
+If you have made changes to the protobuf messages in `pyatv/mrp/protobuf`, you can make sure everything is updated by running:
+
+```shell
+$ ./scripts/protobuf.py --download generate
+```
+
+See [Protobuf](tools#protobuf) for more details.
+
+## Running Tests
+
+Recommended way to run unit tests:
+
+```shell
+$ pytest --log-level=debug --disable-warnings
+$ ./scripts/chickn.py pytests  # Can be run via chickn
+```
+
+Warnings are disabled because of deprecated `loop` argument in lots of places. This flag will be lifted eventually. See [Testing](testing) for details regarding tests.
+
+## Re-formatting code
+
+All python code is formatted using [black](https://github.com/psf/black), so you don't have to care about how the code looks. Just let black take care of it:
+
+```shell
+$ black .
+All done! ✨ 🍰 ✨
+77 files left unchanged.
+```
+
+Code formatting is checked by `chickn`, so it's not possible to check in code if it doesn't comply with black.
+
+## Documentation
+
+**NB: This step currently requires docker and is only tested on Linux!**
+
+To serve a local running web server that performs incremental updates of the documentation,
+run:
+
+```shell
+$ ./scripts/build_doc.sh
+```
+
+Navigate to [http://localhost:4000](http://localhost:4000) to see the result.
+
+The `cs_docs` step (`./scripts/chickn.py cs_docs`) will do basic spell checking of the documentation
+using [codespell](https://github.com/codespell-project/codespell).
+
+# Cheat Sheet
+
+Here are a few convenient commands in short form:
+
+| Command | What
+| ------- | ----
+| pytest --disable-warnings --log-level=debug -k XXX | Run tests matching XXX
+| black . | Re-format code with black
+| ./scripts/protobuf.py --download generate | Update protobuf definitions
+| ./scripts/build_doc.sh | Serve web server with documentation at [http://127.0.0.1:4000](http://127.0.0.1:4000)
+| ./scripts/api.sh generate | Update generate API `documentation in docs/api`
+| ./scripts/features.sh | Generate `pyatv.const.FeatureName` (you need to copy-paste it) and print next free index

package/pyatv/docs/internals/submit_pr.md

@@ -0,0 +1,56 @@
+---
+layout: template
+title: Submit a PR
+permalink: /internals/submit-pr
+link_group: internals
+---
+# :star: Submit a PR
+
+* Fork this repository
+* Make changes and push to fork
+  * Make sure that tests, linting, etc. pass by running `chickn` locally
+  * New code shall have [type hints](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html)
+  * Update documentation if needed
+  * PR cannot be merged if any check in `chickn` fails
+* Open a new PR
+  * If you are fixing a bug, please reference it with "Fixes #xxx" (alternatively "Relates
+    to #xxx") in commit message or pull request message to connect them
+  * Prefix the commit message with a topic, see [topics](#topics)
+* Await review comments
+* Fix potential comments
+* Wait for PR to be merged
+
+## Topics
+
+To make it easier to see where a commit makes changes, add a prefix topic to the commit message. Here are a few topics that are used (suggest new if necessary):
+
+| Topic | What/where you have changed |
+| ----- | --------------------------- |
+| airplay | Something related to `AirPlay`, likely in {% include code file="airplay" %}.
+| companion | Something related to `Companion`, likely in {% include code file="companion" %}.
+| cq | Code Quality, e.g, clean ups, added documentation, refactoring.
+| docs | Documentation in `docs`.
+| gha | GitHub Actions (`.github/workflows`).
+| dmap  | Something related to `DMAP`, likely in {% include code file="dmap" %}.
+| if | Interface related changes (e.g. {% include code file="interface.py" %}).
+| mrp   | Something related to `MRP`, likely in {% include code file="mrp" %}.
+| raop | Something related to `RAOP`, likely in {% include code file="raop" %}.
+| scan | Scanning related code, likely {% include code file="support/scan.py" %}.
+
+Try so split changes over multiple commits if possible, to keep them small (e.g. one for adding interface, one for implementing `MRP`, one for `DMAP` and one for documentation).
+
+Some examples of first lines in commit messages:
+
+```raw
+cq: Add typing hints to public interface
+if: Add interface for device information
+raop: Send feedback if supported by receiver
+test: Migrate from asynctest to pytest-asyncio
+```
+
+# Known Issues
+
+There are currently two known issues with GitHub Actions:
+
+* pytest sometimes fails with an "internal error". Reason is still unknown, restart jobs until it succeeds.
+* pip sometimes fails due to files being broken (bad CRC or BadGzipFile), not sure how to fix that

package/pyatv/docs/internals/testing.md

@@ -0,0 +1,176 @@
+---
+layout: template
+title: Testing
+permalink: /internals/testing
+link_group: internals
+---
+# :ok_hand: Table of Contents
+{:.no_toc}
+* TOC
+{:toc}
+
+# Testing
+
+Testing is an important part of pyatv and there are a lots of tests. The intention is not to have full test coverage, i.e. 100% line coverage (since branch coverage is not supported). The reasoning behind this is that it costs too much when it comes to maintaining the tests and the benefits too low. This does *not* mean that it is OK to not test, it just means that some parts might be easier to inspect manually rather than writing tests for. If the code is easy to test, it should be tested!
+
+*NB: Tests are being re-written to `pytest`-like tests, instead of using regular `unittest` tests. You might see a mix of variants until the work is done, see [#443](https://github.com/postlund/pyatv/issues/443).*
+
+# Running Tests
+
+For running tests, please see [Development Environment](Development-Environment#testing-changes).
+
+# Test Structure
+
+All tests reside in `tests` and follow the same structure as in the code directory (`pyatv/`). `AirPlay` tests can for instance be found in `tests/airplay`. Most tests are regular unit tests, but there are also functional tests that tests pyatv on interface level (see [Types of Tests](#types-of-tests) for more details). They have `functional` in their file names:
+
+| File name | Test Suite |
+| --------- | ---------- |
+| `tests/common_functional_tests.py` | Common tests that are *identical* to all protocols (i.e. inherited)
+| `tests/companion/test_companion_functional.py` | Functional tests for `Companion`
+| `tests/dmap/test_dmap_functional.py` | Functional tests for `DMAP`
+| `tests/mrp/test_mrp_functional.py` | Functional tests for `MRP`
+| `tests/raop/test_raop_functional.py` | Functional tests for `RAOP`
+| `tests/support/test_mdns_functional.py` | Functional tests for MDNS
+| `tests/test_scan_functional.py` | Functional tests for scanning routines
+
+
+
+Generally, if something protocol specific is to be tested it should be added to the protocol specific test suite. But ideally, as many test cases as possible should be added to `common_functional_tests.py` as this will make sure the interface is identical for all protocols.
+
+## Fake Device and Usecases
+
+Testing on interface level, i.e. using the same interface as a developer using pyatv would, comes with the big benefit of flexibility. It allows for great freedom when changing code internally within pyatv without breaking a lot of tests, so that is why these kinds of tests are preferred. They are called *functional tests* in this context. Some details are however hard to test using functional tests, so unit tests can be used in those cases.
+
+For functional tests to work, pyatv needs something to connect to. For this reason a *fake device* is used. It acts like a real devices, but takes a lot of shortcus, implement limited functionality and are only meant to be compatible with pyatv (for now). The fake device starts web servers or open TCP ports, depending on what the protocol uses and the test then sets everything up and connects to it. It short, it looks a bit like this:
+
+```python
+    async def setUpAsync(self):
+        await super().setUpAsync()
+        self.conf = AppleTV(IPv4Address("127.0.0.1"), "Test device")
+        self.conf.add_service(
+            MrpService("mrp_id", self.fake_atv.get_port(Protocol.MRP))
+        )
+        self.conf.add_service(
+            AirPlayService("airplay_id", self.server.port, DEVICE_CREDENTIALS)
+        )
+        self.atv = await self.get_connected_device()
+
+    async def get_application(self, loop=None):
+        self.fake_atv = FakeAppleTV(self.loop)
+        self.state, self.usecase = self.fake_atv.add_service(Protocol.MRP)
+        self.airplay_state, self.airplay_usecase = self.fake_atv.add_service(
+            Protocol.AirPlay
+        )
+        return self.fake_atv.app
+
+    async def get_connected_device(self):
+        return await pyatv.connect(self.conf, loop=self.loop)
+```
+
+The fake device is assigned to `self.fake_atv` and can be used to for instance get some internal state, like the last pressed button. Notice that `pyatv.connect` is used to connect to it. Also notice that scanning is not tested by the functional tests. There are other tests, that stubs zeroconf, for that.
+
+Another concept that is introduced here is `usecase`. A usecase is used to alter the state of a fake device, with some level of abstraction. So instead of modifying the fake device directly, a usecase can be used to for instance change what is currently playing:
+
+```python
+    @unittest_run_loop
+    async def test_metadata_video_paused(self):
+        self.usecase.video_playing(
+            paused=True, title="dummy", total_time=100, position=3
+        )
+
+        with faketime("pyatv", 0):
+            playing = await self.playing(title="dummy")
+            self.assertEqual(playing.media_type, MediaType.Video)
+            self.assertEqual(playing.device_state, DeviceState.Paused)
+            self.assertEqual(playing.title, "dummy")
+            self.assertEqual(playing.total_time, 100)
+            self.assertEqual(playing.position, 3)
+```
+
+Here the fake device is configured to play video with some properties set. The properties are then fetched via the public interface and verified. There are other usecases as well, just look at the implementations. Keeping this abstractions makes it a lot easier to write tests that are shared amongst protocol and is also easier to read. Please note that there's currently no explicit usecase "interface", so it's tricky to see which usescases are shared between all protocols. This would be nice to improve in the future...
+
+Previously one fake device existed per protocol. This has been changed to one fake device that can support multiple services (protocols) instead. To add a service to a fake device, call `add_service`. The state and usecase object for that service will be returned.
+
+Also, there are two new concepts introduced here: polling for a state (`await self.playing(...)`) and `faketime`. These are covered next.
+
+## Illustration of Functional Tests
+
+Here is a simple illustration of how to think of a functional test case:
+
+```raw
+     +-----------------+                +-----------------------+
+     |                 | video_playing  |                       |
+     |    Test case    |--------------->|    AppleTVUseCases    |
+     |                 |                |                       |
+     +--------+--------+                +-----------------------+
+              ^                                     |
+              | metadata.playing()                  |
+              v                                     |
+       +-------------+                              |
+       |             |                              |
+       |    pyatv    |                              |
+       |             |                              |
+       +-------------+                              |
+              ^                                     |
+              | DMAP/AirPlay/MRP/...                |
+              v                                     |
+    +-------------------+                           |
+    |                   |      configure video      |
+    |    FakeAppleTV    |<--------------------------+
+    |                   |
+    +-------------------+
+```
+
+## Polling Active State
+
+Because the fake devices uses regular communication protocols, like TCP and HTTP, there are delays in the system. It takes time for messages to be exchanged and everything to be updated correctly, so it's not always possible to assert values like in normal unit tests. Because of this the tests will have to poll the fake device until some expected state is reached. Here is an example:
+
+```python
+    @unittest_run_loop
+    async def test_button_up(self):
+        await self.atv.remote_control.up()
+        await until(lambda: self.fake_atv.last_button_pressed == "up")
+```
+
+The `up` button is pressed and `self.fake_atv.last_button_pressed` is polled using `await until`, until the correct button is set. The `until` function just calls the provided function until it returns `True`, with a short sleep between each call and a timeout (5s). There's also a convenience method for polling the playing state:
+
+```python
+    @unittest_run_loop
+    async def test_seek_in_playing_media(self):
+        self.usecase.video_playing(
+            paused=False, title="dummy", total_time=40, position=10
+        )
+
+        with faketime("pyatv", 0):
+            await self.atv.remote_control.set_position(30)
+            playing = await self.playing(position=30)
+            self.assertEqual(playing.position, 30)
+```
+
+Awaiting `self.playing` will continue fetching `self.atv.metadata.playing` and verify that all the provided properties have the specified value. Here, it will continue to poll until `position` is set to 30. The corresponding `interface.Playing` object with all information is returned to simplify further investigation.
+
+## Fake Time
+
+Due to `MRP` using real time to calculate current position, time has to be faked. Basically current position is calculated according to `current_time - time_when_something_started_to_play`. I will have to do a better write-up here later, but just use `with faketime("pyatv", 0):` and you'll be fine...
+
+# Types of Tests
+
+Summary of types of tests in pyatv.
+
+## Unit Tests
+
+For simple standalone modules, consider writing unit tests. Write them `pytest`-style. You can then just write some functional tests when integrating it (usually one or a few is enough), to make sure it works with rest of pyatv.
+
+## Functional Tests
+
+When adding features, focus on adding testing on interface level, i.e. write *functional tests*. In the functional tests and extend the fake device to support whatever function you need. The
+test case will automatically set the fake device up and make pyatv connect to it, so you can access the public interface. A simple test case might look like this:
+
+```python
+@unittest_run_loop
+async def test_button_previous(self):
+    await self.atv.remote_control.previous()
+    await until(lambda: self.fake_atv.last_button_pressed == "previtem")
+```
+
+The `previous` button is called with pyatv and the fake device is polled until the button is pressed. Polling is needed because communication is done over TCP, just like with a real device. So it takes some time before the event loop has processed everything. More on this later.