Update Testing Guide

Testing-Guide.md

@@ -1,3 +1,5 @@
+# Testing Guide
+
 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.
@@ -16,6 +18,25 @@ described in the [Requirements](#requirements) table.
 | docker-compose   | Other        | https://docs.docker.com/engine/install/ |
 | poetry           | Other        | https://python-poetry.org/docs/         |
 
+## Poetry (Python Dependencies)
+
+Within the `pu` branch, aurweb now uses the `python-poetry` Python
+package manager. See [Requirements](#requirements) above on installation
+methods.
+
+If poetry is configured to create virtualenvs with
+`poetry config virtualenvs.create true --local` (recommended), users can install
+aurweb dependencies and the aurweb project into their poetry virtualenv:
+
+    $ poetry lock  # Ensure that poetry dep resolution is up to date.
+    $ poetry update  # Update/fetch all dependencies in the virtualenv.
+    $ poetry install  # Install project-specific package and scripts.
+
+After installing dependencies (via `update`) and the project (via `install`),
+users can then run commands within the virtualenv:
+
+    $ poetry run pytest test/
+
 ## Introduction
 
 The aurweb project now maintains a
@@ -83,6 +104,7 @@ At this point, we have two choices:
     - `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 [Add User](#add-user) (optional)
     - See [Generating Dummy Data](#generating-dummy-data)
 
 ## Development Servers
@@ -136,49 +158,18 @@ 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).
 
-#### git
+###### Add User
 
-The `git` service runs sshd using the aurweb-git-auth backend and
+<small>**Note**: To use the script, you'll need a valid AUR_CONFIG to the
-aurweb-git-update hook. It is accessible at `ssh://aur@localhost:2222` on
+target database and aurweb Python dependencies (see [poetry](#poetry-python-dependencies)).</small>
-the host system. Users can use this local sshd just like a production
-AUR instance for git management.
-
-Note that in order for you to do anything with the sshd, you'll need
-to either login to a dummy user or register an account and setup
-your public SSH key like you would on aur.archlinux.org.
-
-#### redis
-
-The `redis` service is used as the Redis backend for the `fastapi` service.
-You can converse with the service on `localhost:16379`:
-
-    $ redis-cli -p 16379
-    ...
-
-#### fastapi
-
-The `fastapi` service runs the aurweb FastAPI implementation through
-an ASGI server. Users can configure this with the `FASTAPI_BACKEND`
-environment variable: `uvicorn` or `hypercorn`. It enables hot
-reloading of the server for changes in all directories in your tree,
-which automatically reflects on the [nginx](#nginx) service.
-
-###### Add Users
 
 You can create a user account in the database using the
 [util/adduser.py](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu/util/adduser.py) script.
 
-This service is exposed on `localhost:18000`.
-
-#### php-fpm
-
-This service is exposed on `localhost:19000` and majorly depends on
-[./web](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu/web).
-
 ###### Generating Dummy Data
 
 <small>
-**NOTE**: This step requires Python dependencies to be accessible from 
+<b>NOTE</b>: 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>
@@ -206,6 +197,40 @@ Configurable env variables:
 Every user generated by the dummy file will have a password which matches
 its username (i.e. username: `kevin`, password: `kevin`).
 
+#### git
+
+The `git` service runs sshd using the aurweb-git-auth backend and
+aurweb-git-update hook. It is accessible at `ssh://aur@localhost:2222` on
+the host system. Users can use this local sshd just like a production
+AUR instance for git management.
+
+Note that in order for you to do anything with the sshd, you'll need
+to either login to a dummy user or register an account and setup
+your public SSH key like you would on aur.archlinux.org.
+
+#### redis
+
+The `redis` service is used as the Redis backend for the `fastapi` service.
+You can converse with the service on `localhost:16379`:
+
+    $ redis-cli -p 16379
+    ...
+
+#### fastapi
+
+The `fastapi` service runs the aurweb FastAPI implementation through
+an ASGI server. Users can configure this with the `FASTAPI_BACKEND`
+environment variable: `uvicorn` or `hypercorn`. It enables hot
+reloading of the server for changes in all directories in your tree,
+which automatically reflects on the [nginx](#nginx) service.
+
+This service is exposed on `localhost:18000`.
+
+#### php-fpm
+
+This service is exposed on `localhost:19000` and majorly depends on
+[./web](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu/web).
+
 #### nginx
 
 The `nginx` service will host two web servers (denoted below), both signed
@@ -218,19 +243,114 @@ by the Root CA certificate `ca.root.pem`.
 
 ## User Experience
 
-TBA
+Some of the most important testing we could do for aurweb at this
+point would be testing that FastAPI's user experience is
+feature-equivalent to PHP's user experience.
+
+There are some exceptions to that: in some areas, we've
+made improvements to the code-base pre-port-completion. For example:
+in the `pu_requests` branch
+(of [kevr's fork](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu))
+and derivatives, users are now given
+access to the Requests page, accessible via the logged in AUR navbar.
+However, for normal users, only requests which they have made are
+shown, and this is to give the user an opportunity to close their
+request if they've made a mistake. There may be improvements and
+modifications otherwise which change HTML renders and behavior,
+but they should all be noted in the commit which made those changes.
+
+If something seems to be not working as you would expect it should,
+please report these problems in the form of issues at
+https://gitlab.archlinux.org/archlinux/aurweb/-/issues.
+
+Additionally, if you could, please provide some overall thoughts about
+your experience with the FastAPI code in an issue prefixed with `[Feedback]`.
+
+Below, we provide a table of routes that we are really looking for UX
+testing on, and people wishing to contribute with UX testers should
+stay up to date with it:
+
+| Route                                                        | Status       | Description          | Account type |
+|--------------------------------------------------------------|--------------|----------------------|--------------|
+| https://localhost:8444/                                      | Incomplete   | Homepage             | User            |
+| https://localhost:8444/register                              | Incomplete   | Account Registration |                 |
+| https://localhost:8444/login                                 | Incomplete   | User Login           | User            |
+| https://localhost:8444/logout                                | Incomplete   | User Logout          | User            |
+| https://localhost:8444/passreset ([Notes](#passreset-notes)) | Incomplete   | User Password Reset  | Logged out User |
+| https://localhost:8444/account/{username}                    | Incomplete   | Account View         | User            |
+| https://localhost:8444/account/{username}/edit               | Incomplete   | Account Edit         | User            |
+| https://localhost:8444/accounts                              | Incomplete   | Account Search       | Trusted User    |
+| https://localhost:8444/packages/{name}                       | Incomplete   | Package View         | User            |
+| https://localhost:8444/pkgbase/{name}                        | Incomplete   | Package Base View    | User            |
+
+#### Development Branches
+
+| Branch                | Git Fork                                 | Route                           | Description                          |
+|-----------------------|------------------------------------------|---------------------------------|--------------------------------------|
+| `pu_requests`         | https://gitlab.archlinux.org/kevr/aurweb | `/requests`                     | Requests page                        |
+| `pu_requests_create`  | https://gitlab.archlinux.org/kevr/aurweb | `/pkgbase/{name}/request`       | Request creation                     |
+| `pu_requests_close`   | https://gitlab.archlinux.org/kevr/aurweb | `/requests/{id}/close`          | Request closure                      |
+| `pu_packages_actions` | https://gitlab.archlinux.org/kevr/aurweb | `/packages`                     | Package search and search actions    |
+| `pu_comaintainers`    | https://gitlab.archlinux.org/kevr/aurweb | `/pkgbase/{name}/comaintainers` | Package base comaintainer management |
+
+###### passreset Notes
+
+Currently, external mail notifications are not enabled within Docker.
+To utilize the passreset mail, users can get the ResetKey column through
+[mariadb](#mariadb):
+
+    $ mysql -h127.0.0.1 -P13306 -uaur -paur aurweb \
+        -e "SELECT ResetKey FROM Users WHERE Username = 'my_user'"
+
+You can then use that key by navigating to:
+https://localhost:8444/passreset?resetkey=your_reset_key.
 
 ## Edge Cases
 
-TBA
+In short: **try to break the implementation** with user input! Do whatever
+you can to cause the code to fail from a user's perspective. If you find
+any bugs, please produce an issue at
+https://gitlab.archlinux.org/archlinux/aurweb/-/issues
+with a `[FastAPI]` prefix in the subject and a description of the bug.
+
+Please include a `docker-compose logs fastapi` output with the report if
+you do.
+
+This should serve as a long-term goal of contributors over time: attempting
+to harden the project at every opportunity. We like our stuff working,
+and this is how we keep it working.
+
+We very high appreciate **any** help, patches, or points that the community
+can provide us. Thank you!
 
 ## Benchmarks
 
-TBA
+One of our sub-goals of this port is to increase performance and efficiency
+overall across the service. Lower benchmark times indicate that code is
+performing better overall.
+
+To perform benchmarks, the [hyperfine](https://github.com/sharkdp/hyperfine)
+tool can be utilized.
+
+    $ hyperfine --warmup 20 --min-runs 500 'curl https://localhost:8444'
+
+These kinds of benchmarks matter more on particular routes with specific
+behaviors. We are primarily concerned with the performance of database
+query related tasks like package search, package/pkgbase viewing, requests
+viewing, homepage and dashboard, RPC API, and more.
 
 ## Code Review
 
-TBA
+It does not matter how experienced a developer is: another set of eyes
+and different perspective can often reveal issues that a writer did
+not intend. It is pretty much impossible for a developer to be "perfect"
+in every case for the entirety of their life.
+
+That is why it is extremely important that we get multiple unique views
+on a set of code that may be for a feature or fixing a bug.
+
+All reviews of code are welcome and appreciated; regardless of it being
+in a particular branch. Please keep your eyes out for problems!
 
 ## Communication