diff --git a/Testing-Guide.md b/Testing-Guide.md index 35a2f1f..10d9972 100644 --- a/Testing-Guide.md +++ b/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 -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. - -###### Add Users +**Note**: To use the script, you'll need a valid AUR_CONFIG to the +target database and aurweb Python dependencies (see [poetry](#poetry-python-dependencies)). 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 -**NOTE**: This step requires Python dependencies to be accessible from +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. @@ -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