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.

Sign up for GitHub

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

Jump to bottom

avatar doc #92

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

avatar doc #92

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
36c039e
avatar doc: atest is preferred over avatar cli
SilverBzH Oct 11, 2024
4d30e2f
avatar doc: fix link
SilverBzH Oct 11, 2024
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
50 changes: 27 additions & 23 deletions doc/android-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
Project: /pandora/_project.yaml
Book: /pandora/_book.yaml

# Avatar with Android

Since Android provides an implementation of the [Pandora APIs](
Expand Down Expand Up @@ -39,10 +42,21 @@ Note: For Googlers, from an internal Android repository, use the
`cf_x86_64_phone-userdebug` target instead. You can also use a CF remote
instance by removing `--local-instance`.

### `avatar` CLI (preferred)
### `atest` CLI (preferred)

You can run all the existing Avatar tests on Android by running the following
commands from the root of your Android repository:
You can run all Avatar tests using [`atest`](
https://source.android.com/docs/core/tests/development/atest):

```shell
atest avatar -v # All tests in verbose
atest avatar:<classA>#<testA> # run a specific test
atest avatar:<classA>#<testA> avatar:<classA>#<testB> # Run two specific tests
```

### `avatar` CLI (alternative)

You can also run all the existing Avatar tests on Android by running the
following commands from the root of your Android repository:

```shell
cd packages/modules/Bluetooth
Expand All @@ -56,15 +70,6 @@ avatar run --mobly-std-log # '--mobly-std-log' to print mobly logs, silent othe
Note: If you have errors such as `ModuleNotFoundError: no module named pip`,
reset your Avatar cache by doing `rm -rf ~/.cache/avatar/venv`.

### `atest` CLI

You can also run all Avatar tests using [`atest`](
https://source.android.com/docs/core/tests/development/atest):

```shell
atest avatar -v # All tests in verbose
```

## Build a new Avatar test

Follow the instructions below to create your first Avatar test.
Expand All @@ -75,8 +80,6 @@ Create a new Avatar test class file `codelab_test.py` in the Android Avatar
tests folder, `packages/modules/Bluetooth/android/pandora/test/`:

```python
import asyncio # Provides utilities for calling asynchronous functions.

from typing import Optional # Avatar is strictly typed.

# Importing Mobly modules required for the test.
Expand All @@ -92,15 +95,15 @@ from pandora.host_pb2 import RANDOM, DataTypes


# The test class to test the LE (Bluetooth Low Energy) Connectivity.
class CodelabTest(base_test.BaseTestClass): # type: ignore[misc]
class CodelabTest(base_test.BaseTestClass):
devices: Optional[PandoraDevices] = None
dut: PandoraClient
ref: BumblePandoraClient # `BumblePandoraClient` is a sub-class of `PandoraClient`

# Method to set up the DUT and REF devices for the test (called once).
def setup_class(self) -> None:
self.devices = PandoraDevices(self) # Create Pandora devices from the config.
self.dut, ref, *_ = self.devices
self.dut, ref = self.devices
assert isinstance(ref, BumblePandoraClient) # REF device is a Bumble device.
self.ref = ref

Expand Down Expand Up @@ -145,18 +148,18 @@ index a124306e8f..742e087521 100644
+_TEST_CLASSES_LIST = [example.ExampleTest, codelab_test.CodelabTest]
```

You can now try to run your test class using `avatar`:
You can now try to run your test class using `atest`:

```shell
avatar run --mobly-std-log --include-filter 'CodelabTest' # All the CodelabTest tests
avatar run --mobly-std-log --include-filter 'CodelabTest#test_void' # Run only test_void
atest avatar -v # all tests
atest avatar:'CodelabTest#test_void' -v # Run only test_void
```

Or using `atest`:
Or using `avatar`:

```shell
atest avatar -v # all tests
atest avatar:'CodelabTest#test_void' -v # Run only test_void
avatar run --mobly-std-log --include-filter 'CodelabTest' # All the CodelabTest tests
avatar run --mobly-std-log --include-filter 'CodelabTest#test_void' # Run only test_void
```

### Add a real test
Expand Down Expand Up @@ -211,7 +214,7 @@ def test_le_connect_central(self) -> None:
Then, run your new `test_le_connect_central` test:

```shell
avatar run --mobly-std-log --include-filter 'CodelabTest'
atest avatar:CodelabTest#test_le_connect_central
```

### Implement your own tests
Expand Down Expand Up @@ -322,3 +325,4 @@ Android postsubmit tests.
[avatar-code]: https://cs.android.com/android/platform/superproject/+/main:external/pandora/avatar

[avatar-android-suite-runner-code]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Bluetooth/android/pandora/test/main.py

2 changes: 1 addition & 1 deletion doc/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ The third approach is to start from a code coverage report: uncovered code
paths are identified and corresponding Avatar tests are implemented to target
them.

## Extended architecture
## Extended architecture <a name=extended-architecture></a>

Avatar is capable to handle any setup with multiple devices which implement
the Pandora APIs. Avatar tests can be run physically or virtually (with
Expand Down
Loading