Metadata-Version: 2.4
Name: miniqa
Version: 0.1.0
Summary: An easy to use automated QA testing tool based on QEMU
License-Expression: GPL-3.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: Hypercorn>=0.18.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: pillow>=12.1.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: ruamel.yaml>=0.19.1
Requires-Dist: Quart>=0.20.0
Requires-Dist: tqdm>=4.67.3
Requires-Dist: websockify>=0.13.0
Provides-Extra: default
Provides-Extra: ocr
Requires-Dist: ppocr-lite[fast]>=0.5.5; extra == "ocr"
Dynamic: license-file


# miniQA

A simple to use automated QA test tool: miniQA runs an OS of your choice in QEMU, interacts with it based on your YAML test files and ensures the results match your criteria.

miniQA includes a simple web editor/mini IDE providing some helpful tools to write your test cases in quick iterations with the VM screen on the side.

## Setup

### Via PIP

miniQA can be installed via pip:

```bash
pip install miniqa
```

Make sure you have the runtime dependencies (`qemu-system-x86`, `qemu-utils` and optionally `ovmf`) installed as well:

- Debian: `sudo apt install qemu-system-x86 qemu-utils ovmf`
- Fedora: `sudo dnf install qemu-system-x86 qemu-img edk2-ovmf`

Now, you can just run your tests by running this from your tests folder:

```bash
miniqa run    # - or: `miniqa editor` for the webui
```

### Via Podman/Docker

Alternatively, miniQA can be used without any installation via podman or docker. The image includes QEMU already. To do so, just invoke a command such as this from your tests folder:

```bash
docker run \
    --rm \
    -it \
    --device /dev/kvm \
    --tmpfs /tmp:size=1G,mode=1700 \
    -p 8080:8080 \
    -p 6080:6080 \
    -v .:/tests \
    miniqa run    # - or: `miniqa editor` for the webui
```

## Quick Start

### Setup the Files:
In your project, create a `tests` folder. Everything miniQA will live in this folder. In this folder, you need to create:

- An `img` folder: Here, the OS image(s) will be located. For example, you can grab a copy of
  [GNOME OS Nightly](https://os.gnome.org/) and place it in `img/gnome_os_disk.img`.
- A `miniqa.yml` file: This file contains your overall miniQA configuration and can look like this:

	```yaml
    image: img/gnome_os_disk.img                   # the image our VM boots

    use_ovmf: true                                 # required to boot GNOME OS
    qemu_args: [
      "-device", "virtio-multitouch-pci",          # adds multitouch capabilities to the VM
      "-device", "VGA,edid=on,xres=1080,yres=720"  # ensures a fixed screen resolution
    ]
    
    cache_directory: ./miniqa-cache
	```
- A nested `tests` folder: This will contain your test cases, e.g. 
  [`example_test.yml`](sample_tests/tests/base.yml), or this one:

    ```yaml
    steps:
      - wait:                                      # - wait for boot to complete, and then for the GNOME OS
          for:                                     #   setup wizard (which has gray background) to show up
            dominant_color: '#fafafb' 
          timeout: 120s                            # - on timeout, our test will fail
      - click:                                     # - go to the next page      
          find:
            text: Next
      - snapshot: base                             # - create a snapshot other tests can start from
    ```

Your overall directory structure should now look like this:

```
your_project
├── …
└── tests
    ├── img
    │   └── gnome_os_disk.img
    ├── tests
    │   ├── example_test.yml
    │   ├── second_example_test.yml
    │   └── …
    └── miniqa.yml
```

### Run your Tests
Now, you're ready to run your first test:

```bash
cd your_project/tests
miniqa run
```

### Edit in the Webui

Afterward, you can edit your tests in any editor you like, but I'd highly recommend using miniQA's webui. 
This way you'll be able to

- run tests right away,
- see the VM's screen right next to the YAML editor, and
- have basic autocomplete making it easy to discover miniQA's features.

The webui also has tools allowing you to easily pick screen positions, regions and colors right from the VM.

To launch it, run:

```bash
miniqa editor
```

## Check the Docs

Well, docs might be a bit far-fetched, but there's a bit of reference in [./docs](./docs).

The aim is, that this should be enough to easily find your way into miniQA and work with it in the long run; should you have questions or miss anything in there, please don't hesitate to [create an issue](https://github.com/mityax/miniqa/issues/new) to get in touch.

## Contribute

I'd highly value your contributions – if you'd like to add a new feature or make bigger changes, please [create an issue](https://github.com/mityax/miniqa/issues/new) to briefly discuss it upfront, so we can make sure your work is not for nothing; for small fixes feel free to just open a PR.

Please be aware that the codebase is not yet quite as clean as I'd like it to be, since this project was originally just a sidequest and I haven't yet had much time to fully clean it up. However, I'm glad to help you around, should you have questions!

## Support

If miniQA is helpful for you, I'd appreciate you supporting me with a small amount. Even a dollar a month helps!

To donate, choose a platform below:

<a href='https://ko-fi.com/Q5Q41A9U4G' target='_blank'><img height='36' style='border:0px;height:36px;vertical-align:middle' src='https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a><br />
<i>Recommended! Most payment methods, one-time or recurring donations, no sign up required.</i>

<a href='https://buymeacoffee.com/mityax' target='_blank'><img height='36' style='border:0px;height:36px;vertical-align:middle' src='https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black' border='0' alt='Buy Me a Coffee' /></a><br />
<i>Donate by card, no sign up required.</i>


## License

This project is licensed under GPL-3.0-or-later.
