mirror of
https://gitlab.archlinux.org/archlinux/aurweb.git
synced 2025-02-03 10:43:03 +01:00
Update Testing Guide
Kevin Morris
parent
af24219f4e
commit
91449c13d9
1 changed files with 159 additions and 39 deletions
198
Testing-Guide.md
198
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
|
||||
<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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue