Create Testing Guide - WIP

2025-02-03 10:43:03 +01:00 · 2021-09-20 07:45:06 +00:00 · 2021-09-20 07:45:06 +00:00 · 1f15c28658
commit 1f15c28658
parent 98b810da67
1 changed files with 176 additions and 0 deletions
--- a/Testing-Guide.md
+++ 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) - <small>Highest Priority</small>
+- [ ] [Edge Cases](#edge-cases) - <small>Medium Priority</small>
+
+## What Else?
+
+- [ ] [Benchmarks](#benchmarks) - <small>Medium Priority</small>
+- [ ] [Code Review](#code-review) - <small>High Priority</small>
+
+## 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
+
+<small>**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.</small>
+
+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)
+<small>(main developer of the FastAPI port)</small>, 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`.