Metadata-Version: 2.4
Name: maestro-reporter
Version: 0.9.0
Summary: Customized tool to run Maestro tests, parse Maestro report file, and push reports to Lark.
Author: Ryan Febriansyah
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: lxml
Requires-Dist: python-dotenv
Dynamic: license-file

## py-maestro-reporter

![badge](https://gitlab.com/ryaneatfood/py-maestro-reporter/badges/master/pipeline.svg) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/maestro-reporter) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/maestro-reporter?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/maestro-reporter)
![coverage](https://gitlab.com/ryaneatfood/py-maestro-reporter/badges/master/coverage.svg)

`py-maestro-reporter` is a lightweight tool that helps you:

- Run Maestro test seamlessly
- Parse Maestro JUnit reports
- Send summarized test results to a Lark/Slack respective group

It can be used either as a CLI tool or a python package into your own test pipelines

### Prerequisites

- Python 3.10 or above
- [Maestro framework](https://docs.maestro.dev/getting-started/installing-maestro) installed on your system (version 2.0.0 or above)
- Device/emulator with the app under test installed
- Lark/Slack webhook URL (optional)

### Installation

For the installation, you can either install the package from PyPI or from source. If you'd like to install from PyPI, you can install it with:

```bash
pip install maestro-reporter
```

Or, using uv:

```bash
uv pip install maestro-reporter
```

Or, if you'd prefer to install from source, you'll need to clone this repository and install it in editable mode:

```bash
pip install -e .
```

### Usage

**Using as a CLI argument**

This package expose a CLI via the `reporter` module

All you need to do is, ensure you have Maestro installed on your device, example flows which is going to be tested, physical device / emulator and Webhook URL from Lark. Once you have all of these, you can run with :

```bash
python -m reporter \
    -c "maestro test examples/facebook-sign-up-flow.yaml --format junit --output tests/report.xml" \
    -r "tests/report.xml" \
    -w "https://webhook.url.com"
```

**Parsing an existing report**

Or, if you only want to run and parse the report without testing, you can use `--no-run` flag

```bash
python -m reporter \
    --no-run \
    -r "tests/report.xml" \
    -w "https://webhook.url.com"
```

> You can also overrides the Webhook URL by setting the `LARK_URL` or `SLACK_URL` environment variable in your `.env` file, depending on the provider you choose.

**Using the reporter package**

Otherwise, if you'd like to run the tests without using the CLI arguments and you need to run the tests with the `reporter` package, you can follow the example below:

```python
# this will test the Facebook sign-up flow
import os
from dotenv import load_dotenv
from reporter import parse_xml_report, send_report_to_lark, run_maestro_command


load_dotenv()


command = "maestro test examples/facebook-sign-up-flow.yaml --format junit --output build/maestro-results/report.xml"
report_path = run_maestro_command(command=command, cwd="tests")
parsed_result = parse_xml_report(file_path=str(report_path))
report = send_report_to_lark(
    summary=parsed_result,
    title="Maestro Reporter Test",
    color_template="Green",
    webhook_url=os.getenv("LARK_URL"),
)
```

> The parameters of `color_template` and `title` are mandatory, if you don't provide them, the default values will be used

> **Note (v0.8.0)**: `run_maestro_command` reads the `--output` argument from your command, creates the report's parent directory automatically, and returns the resolved report path. When Maestro exits with a non-zero code, the report is still returned if it exists, so failed-test results can be reported. `RuntimeError` is raised only when no report file is found. `run_maestro_command` and `parse_xml_report` raise an exception on failure instead of silently returning `None`.

All successful tests will be displayed in the log stream handler, for example:

```
27-11-2025 : 10:51:46 : main : [WARNING] : No color template provided, using default color template or you can set it with `--color` flag
27-11-2025 : 10:51:46 : main : [WARNING] : No title provided, using default title or you can set it with `--title` flag
27-11-2025 : 10:51:46 : main : [INFO] : --no-run flag is set, skipping Maestro tests
27-11-2025 : 10:51:46 : main : [INFO] : Parsing Maestro report file: tests/report.xml
27-11-2025 : 10:51:46 : main : [INFO] : Sending Maestro report to Lark...
27-11-2025 : 10:51:46 : reporter.sender : [INFO] : Lark message sent successfully
27-11-2025 : 10:51:46 : main : [INFO] : Maestro report sent successfully
```

Once the report is sent successfully, you should be able to see the interactive card message in your Lark group like the following image

![Lark Interactive Card Message](https://gitlab.com/ryaneatfood/py-maestro-reporter/-/raw/master/images/maestro-result.png)

Otherwise, if you want to use Slack as a reporting platform, the card message will be displayed as follows

![Slack Card Message](https://gitlab.com/ryaneatfood/py-maestro-reporter/-/raw/master/images/slack-result.png)

### CLI arguments

List of available CLI arguments that you can use with this package:

| arguments           | description                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `-h` / `--help`     | show this help message and exit                                                           |
| `-c` / `--command`  | Maestro command to run                                                                    |
| `-r` / `--report`   | Path to Maestro report, by default it's `report.xml` but you can configure it by yourself |
| `-w` / `--webhook`  | Specify a webhook URL to send the report to Lark                                          |
| `-n` / `--no-run`   | No need to run Maestro tests, just parse the report and send the result to Lark           |
| `-t` / `--title`    | Set a custom title for the interactive card Lark message                                  |
| `-ct` / `--color`   | Set a custom color template for the interactive card Lark message                         |
| `-p` / `--provider` | Specify the reporting platform (`lark` or `slack`). Default is `lark`                     |

**Notes**

- At the moment, this package only supports the parsing of the `junit` format as follows for the Maestro report
- In addition, the webhook integration currently supports **Lark** and **Slack**
- The interactive card message is built using the `msg_actioncard` message type for Lark and `Block Kit` for Slack

**Further references**

- [Generate report with Maestro](https://docs.maestro.dev/cli/test-suites-and-reports)
- [Setup Lark Webhook URL in Lark group](https://open.larksuite.com/document/client-docs/bot-v3/add-custom-bot)
