|
|
# 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
|
|
|
|
|
|
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.
|
|
|
###### Add User
|
|
|
|
|
|
#### 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
|
|
|
<small>**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)).</small>
|
|
|
|
|
|
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
|
|
|
|
... | ... | |