diff --git a/Testing-Guide.md b/Testing-Guide.md new file mode 100644 index 0000000..95718b1 --- /dev/null +++ b/Testing-Guide.md @@ -0,0 +1,176 @@ +This document provides guidance on running tests and development servers in the +[aurweb (base branch: **pu**)](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu) +project. + +Before you begin, ensure that you've got the relevent dependencies +described in the [Requirements](#requirements) table. + +## Requirements + +| Package | Distribution | Method | +|------------------|--------------|-----------------------------------------| +| docker | Arch Linux | `pacman -S docker` | +| docker-compose | Arch Linux | `pacman -S docker-compose` | +| docker | Other | https://docs.docker.com/engine/install/ | +| docker-compose | Other | https://docs.docker.com/engine/install/ | + +## Introduction + +The aurweb project now maintains a +[Dockerfile](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu/Dockerfile) +and [docker-compose.yml](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu/docker-compose.yml). +The Dockerfile builds a very basic image, and the docker-compose services +use that image as a base for its services. + +For a complete rundown on all of the services available, see the +[aurweb Docker wiki page](https://gitlab.archlinux.org/archlinux/aurweb/-/wikis/Docker). + +As a bit of a guide to the guide, I'd like to help you navigate around +a bit: + +1. Read [User Experience](#user-experience) +2. Read [Edge Cases](#edge-cases) +3. Read [Getting Started](#getting-started) + - Follow the link to [Development Servers](#development-servers) at the end +4. Go back and focus on [User Experience](#user-experience) or any of the + other needs specified in [What We Need Tested](#what-we-need-tested) and [What Else?](#what-else) + +## What We Need Tested + +- [ ] [User Experience](#user-experience) - Highest Priority +- [ ] [Edge Cases](#edge-cases) - Medium Priority + +## What Else? + +- [ ] [Benchmarks](#benchmarks) - Medium Priority +- [ ] [Code Review](#code-review) - High Priority + +## Getting Started + +First, checkout to and pull the latest `pu` branch revision. This branch +contains new code not located in `live` or `master`. + + $ git remote add upstream ssh://git@gitlab.archlinux.org:222/archlinux/aurweb.git + $ git checkout pu + $ git pull upstream pu + +Build the `aurweb:latest` Docker image: + + $ docker build -t aurweb:latest . + +At this point, we have two choices: + +1. Run a test command + - `docker-compose run sharness` + - `docker-compose run pytest-mysql` + - `docker-compose run pytest-sqlite` + - `docker-compose run test` +2. Run the development servers (FastAPI and PHP, side-by-side) + - `docker-compose up -d nginx` (see [Development Servers](#development-servers)) + - See [Generating Dummy Data](#generating-dummy-data) + +## Development Servers + +When a user runs `docker-compose up -d nginx`, a few things happen: + +1. The `ca` service starts +2. The `mariadb` service starts +3. The `git` service starts +4. The `fastapi` service starts +5. The `php-fpm` service starts +6. The `nginx` service starts + - This last service depends on various features of the services + it depends on. + +#### Certificate Authority + +The `ca` service will produce a `cache/ca.root.pem` file, which is used to +sign the `cache/localhost.cert.pem` certificate. Users can import our +`ca.root.pem` as a Certificate Authority into browsers or ca-certificates. + +#### mariadb + +The `mariadb` service will bind to `localhost:13306` on the host machine. This +allows users to inspect the database used by the fastapi and php-fpm services: + + $ mysql -h127.0.0.1 -P13306 -uaur -paur aurweb \ + -e "SELECT * FROM Packages" + +**NOTE**: On my personal system, specifying `-h127.0.0.1` is important, +as the mysql client does something other than reach the mariadb server with +`localhost` (assumed some type of confusion with localhost, didn't look much +further). + +###### Generating Dummy Data + +**NOTE**: This step requires Python dependencies to be accessible from +your shell's python3. See +[pyproject.toml](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu/pyproject.toml) +for a quite rudimentary +[poetry](https://python-poetry.org/) configuration. + +Users can generate configurable amounts of dummy data with +[schema/gendummydata.py](https://gitlab.archlinux.org/archlinux/aurweb): + + $ export MAX_USERS=5000 + $ export MAX_PKGS=10000 + + # With python3 + $ python3 schema/gendummydata.py dummy.sql + + # With poetry + $ poetry run python3 schema/gendummydata.py dummy.sql + +Configurable env variables: + +- `MAX_USERS`: The maximum number of users to generate (default: 38000) +- `MAX_PKGS`: The maximum number of packages to generate (default: 32000) +- `OPEN_PROPOSALS`: Number of open proposals to generate (default: 15) +- `CLOSE_PROPOSALS`: Number of close proposals to generate (default: 50) +- `FORTUNE_FILE`: Path to fortune cookie file (default: '/usr/share/fortune/cookie') + +Every user generated by the dummy file will have a password which matches +its username (i.e. username: `kevin`, password: `kevin`). + +#### nginx + +The `nginx` service will host two web servers (denoted below), both signed +by the Root CA certificate `ca.root.pem`. + +| Backend | URL | +|---------|------------------------| +| PHP | https://localhost:8443 | +| FastAPI | https://localhost:8444 | + +## User Experience + +TBA + +## Edge Cases + +TBA + +## Benchmarks + +TBA + +## Code Review + +TBA + +## Communication + +We are commonly available in the **#archlinux-aurweb** channel on +the Libera.chat network. + +You can also reach us via the +[aur-general](https://lists.archlinux.org/listinfo/aur-general) and +[aur-dev](https://lists.archlinux.org/listinfo/aur-dev) mailing lists, as +long as the inquiry is topical. If you wish to speak to +[kevr](https://aur.archlinux.org/account/kevr) +(main developer of the FastAPI port), you can send him through +email at kevr@0cost.org for any reason. + +Patches are also welcome via the +[aur-dev](https://lists.archlinux.org/listinfo/aur-dev) list with +`git send-email`.