Development
Setup
The requirements necessary to use this project on a development machine are:
sudo apt-get install git python3 python3-venv postgresql postgresql-contrib
Python environment
Create Python virtual environment:
python3 -m venv frontend
Set an environment variable upon activation:
# at the end of the file
export DJANGO_SETTINGS_MODULE=asastats.settings.development
Activate Python environment:
source frontend/bin/activate
Adding an alias can be useful:
alias 'front'='cd /home/username/dev/frontend/asastats;source /home/username/dev/venvs/frontend/bin/activate'
Initial packages installation:
(frontend) debian:~/dev/frontend/asastats$ pip install -r requirements/development.txt
Linting
To maintain code quality and consistent formatting, use isort and black. First, navigate to the asastats directory:
cd asastats/
Sort the Python imports alphabetically:
isort .
Run black for code formatting, making sure to explicitly exclude the submodules:
black . --extend-exclude="widgets/" --extend-exclude="permissiondapp/"
Submodules
This project utilizes submodules for isolated feature sets. The widgets submodule is an obligatory requirement, while the permissiondapp submodule is an optional addition used by the ASA Stats website.
To fetch the absolute latest version of the obligatory widgets submodule:
git submodule update --remote asastats/widgets
To fetch the absolute latest version of the optional permissiondapp submodule:
git submodule update --remote asastats/permissiondapp
In case of changed code, or if you need to throw away local changes, you can revert the submodules to the exact versions the frontend repository expects:
# reset to the version frontend has
git submodule update --init --recursive --force
Run development server
python manage.py runserver
WalletConnect & xChain Requirements
To support mobile EVM wallets, set your public Reown project ID in your .env.
If left empty, only browser extensions will work.
# Create at https://dashboard.reown.com
WALLETCONNECT_PROJECT_ID=your_project_id_here
xChain Note: Account logins require the Algod /v2/teal/compile endpoint enabled on algod_instance().
PostgreSQL
PostgreSQL setup in development
Database creation on development machine:
root@debian:~# su - postgres
postgres@debian:~# createdb frontend_db
Database user setup on development machine (CREATEDB is needed for running tests, while pg_trgm extension is used for determining the similarity of text based on trigram matching):
postgres@debian:~# psql
postgres=# CREATE USER frontend_user WITH ENCRYPTED PASSWORD 'mypassword';
postgres=# ALTER USER frontend_user CREATEDB;
postgres=# ALTER DATABASE frontend_db OWNER TO frontend_user;
postgres=# \connect frontend_db
postgres=# CREATE EXTENSION IF NOT EXISTS pg_trgm;
Finally, under frontend web Python environemnt:
python manage.py makemigrations
python manage.py migrate
Tests
Python
Run all tests:
cd /home/username/dev/frontend
source /home/username/dev/venvs/frontend/bin/activate
python -m pytest -v # or just pytest -v, pytest -vvv for more verbose output
Run tests and show coverage report in terminal:
pytest --cov=. --cov-report=term-missing
Run tests matching pattern:
pytest -v -k test_profile_model_check_votes_and_permission_updates
pytest -v -k "not integration_tests"
Run project’s functional tests:
python -m pytest asastats/functional_tests/ -v
Run widgets submodule unit tests:
The widgets submodule is an integral part of the project and depends heavily on the frontend repository. Therefore, testing widgets directly from within the frontend is an expected behavior for developers.
PYTHONPATH=asastats pytest -v asastats/widgets -c asastats/widgets/pytest.ini
Typescript
Install dependencies:
cd /home/username/dev/frontend/frontend
npm install
npm run build
Run tests:
cd /home/username/dev/frontend/asastats
npm run test # npm run test:coverage
Javascript
Install dependencies:
npm install
Run tests:
cd /home/username/dev/frontend/asastats
npm run test # npm run test:coverage