From 8312a1d7d029b1860a541345f25f7c6817314248 Mon Sep 17 00:00:00 2001 From: Eli Chadwick Date: Fri, 1 Dec 2023 17:15:25 +0000 Subject: [PATCH 1/2] extra a11y testing notes --- README.md | 101 +++++++++++++++++----------------- docs/accessibility_testing.md | 10 ++++ 2 files changed, 60 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index dab8360dc..c5d36c76c 100644 --- a/README.md +++ b/README.md @@ -14,40 +14,40 @@ who's teaching what, and so on. AMY is built using [Django][django] with Python 3, with a bit of Javascript and other things thrown in. If you would like to help, please read: -* the setup instructions below, +* the setup instructions below, -* the [contributor guidelines](.github/CONTRIBUTING.md), and +* the [contributor guidelines](.github/CONTRIBUTING.md), and -* our [contributor code of conduct](.github/CODE_OF_CONDUCT.md). +* our [contributor code of conduct](.github/CODE_OF_CONDUCT.md). Please [check with us][contact-address] or open an [issue][issues] before starting work on new features. ## Getting Started -1. Clone the repository: +1. Clone the repository: ~~~ - $ git clone https://github.com/carpentries/amy.git - $ cd amy + git clone https://github.com/carpentries/amy.git + cd amy ~~~ -1. Configure git to automatically ignore revisions in the `.git-blame-ignore-revs`: +1. Configure git to automatically ignore revisions in the `.git-blame-ignore-revs`: ~~~ - $ git config blame.ignoreRevsFile .git-blame-ignore-revs + git config blame.ignoreRevsFile .git-blame-ignore-revs ~~~ -1. Install [Pipenv](https://pipenv.pypa.io/en/latest/): +1. Install [Pipenv](https://pipenv.pypa.io/en/latest/): ~~~ - $ python -m pip install --user pipenv + python -m pip install --user pipenv ~~~ -1. Install Python dependencies: +1. Install Python dependencies: ~~~ - $ pipenv sync --dev + pipenv sync --dev ~~~ **Note:** @@ -55,49 +55,48 @@ before starting work on new features. have to create one yourself. The `--dev` flag installs development dependencies, required e.g. for testing. -1. Install [node][nodejs] for front-end packages management. +1. Install [node][nodejs] for front-end packages management. -1. Install CSS, JS dependencies with (`npm` was installed in previous step when you +1. Install CSS, JS dependencies with (`npm` was installed in previous step when you installed `node`): ~~~ - $ npm install + npm install ~~~ -1. Start running a local instance of Postgres and Redis. This requires Docker to be installed locally. Redis is required to have certain features (like creating a new person and viewing a workshop request) work correctly. +1. Start running a local instance of Postgres and Redis. This requires Docker to be installed locally. Redis is required to have certain features (like creating a new person and viewing a workshop request) work correctly. ~~~ - $ docker compose -f docker/docker-compose.yml -p amy up -d database redis + docker compose -f docker/docker-compose.yml -p amy up -d database redis ~~~ -1. Set up your local database with fake (development-ready) data. This will create a superuser with "admin" as both the username and password. +1. Set up your local database with fake (development-ready) data. This will create a superuser with "admin" as both the username and password. ~~~ - $ pipenv run make dev_database + pipenv run make dev_database ~~~ -1. Start a local Django development server by running: +1. Start a local Django development server by running: ~~~ - $ pipenv run make serve + pipenv run make serve ~~~ **Note**: this also installs front-end dependencies for AMY, including [jQuery][jquery] and [Bootstrap][bootstrap] ([full list here](https://github.com/carpentries/amy/blob/develop/package.json)). -1. Open in your browser and start clicking. Use the default "admin" as username and password. - +1. Open in your browser and start clicking. Use the default "admin" as username and password. 1. Shut down the local server by typing `Ctrl-C`. Shut down the Docker Redis instance with: ~~~ - $ docker compose -f docker/docker-compose.yml -p amy down + docker compose -f docker/docker-compose.yml -p amy down ~~~ ## How to build the docker image? ```shell -$ LAST_COMMIT=`git rev-parse --short HEAD` -$ docker build -t amy:latest -t amy:${LAST_COMMIT} --label commit=${LAST_COMMIT} -f docker/Dockerfile . +LAST_COMMIT=`git rev-parse --short HEAD` +docker build -t amy:latest -t amy:${LAST_COMMIT} --label commit=${LAST_COMMIT} -f docker/Dockerfile . ``` First command sets `LAST_COMMIT` environment variable to short commit hash of the @@ -108,53 +107,52 @@ directory) with tags `amy:latest` and `amy:LAST_COMMIT`. ## Upgrading -1. Update the code: +1. Update the code: - 1. Get the list of changes: + 1. Get the list of changes: ~~~ - $ git fetch + git fetch ~~~ - 1. Look for the newest tag: + 1. Look for the newest tag: ~~~~ - $ git tag -n + git tag -n ~~~~ - 1. Get the code from the newest tag: + 1. Get the code from the newest tag: ~~~~ - $ git checkout tags/ + git checkout tags/ ~~~~ -1. Update dependencies front-end and back-end dependencies: +1. Update dependencies front-end and back-end dependencies: ~~~ - $ pipenv run make upgrade + pipenv run make upgrade ~~~ -1. (Optional) make fresh development-ready database: +1. (Optional) make fresh development-ready database: ~~~ - $ pipenv run make dev_database + pipenv run make dev_database ~~~ **Note**: this command requires removing (by hand) the old database file. -1. Run database migrations: +1. Run database migrations: ~~~~ - $ pipenv run python manage.py migrate + pipenv run python manage.py migrate ~~~~ -1. Enjoy your new version of AMY: +1. Enjoy your new version of AMY: ~~~ - $ pipenv run make serve + pipenv run make serve ~~~ - ## Start hacking on email automation 1. Make sure you have Redis running. See instructions above. @@ -162,25 +160,26 @@ directory) with tags `amy:latest` and `amy:LAST_COMMIT`. 1. Create dev database (it will add a super user and predefined database entries, too!): ```shell - $ pipenv run make dev_database + pipenv run make dev_database ``` 1. Run the server: ```shell - $ pipenv run python manage.py runserver + pipenv run python manage.py runserver ``` 1. Run the RQ worker and scheduler (use separate terminals or processes for each command): ```shell - $ pipenv run python manage.py rqworker - $ pipenv run python manage.py rqscheduler + pipenv run python manage.py rqworker + pipenv run python manage.py rqscheduler ``` + ## Run accessibility tests locally -Accessibility tests are run with [Google Lighthouse](https://github.com/GoogleChrome/lighthouse) and [Pa11y](https://pa11y.org) as part of the CI process. It's sometimes helpful to run these programs locally to debug or test changes. For more information on the tests, see the [accessibility tests documentation](docs/accessibility_testing.md) +Accessibility tests are run with [Pa11y](https://pa11y.org) and optionally [Google Lighthouse](https://github.com/GoogleChrome/lighthouse) as part of the CI process. It's sometimes helpful to run these programs locally to debug or test changes. For more information on the tests, see the [accessibility tests documentation](docs/accessibility_testing.md) For both Lighthouse and pa11y tests, Google Chrome or Chromium must be installed. On Ubuntu: @@ -217,14 +216,16 @@ Pa11y will exit with a failure code if accessibility failures are found. Reports ## Edit the CSS theme -The AMY theme is primarily based on Bootstrap 4. +The AMY theme is primarily based on Bootstrap 4. To update the custom CSS that sits on top of the Bootstrap theme, edit `amy/static/css/amy.css`. To override Bootstrap 4 defaults such as colors, edit the [Sass](https://sass-lang.com/) file `amy/static/scss/custom_bootstrap.scss` as required, then compile it to CSS: + ```shell -$ npx sass amy/static/scss/custom_bootstrap.scss amy/static/css/custom_bootstrap.min.css --style compressed +npx sass amy/static/scss/custom_bootstrap.scss amy/static/css/custom_bootstrap.min.css --style compressed ``` + See the [Bootstrap documentation](https://getbootstrap.com/docs/4.0/getting-started/theming/) for more guidance on overriding Bootstrap defaults. [bootstrap]: https://getbootstrap.com/ @@ -233,6 +234,4 @@ See the [Bootstrap documentation](https://getbootstrap.com/docs/4.0/getting-star [jquery]: https://jquery.com/ [issues]: https://github.com/carpentries/amy/issues [tc]: https://carpentries.org/ -[virtualenv]: https://virtualenv.pypa.io/en/latest/userguide.html -[venv]: https://docs.python.org/3/library/venv.html [nodejs]: https://nodejs.org/en/ diff --git a/docs/accessibility_testing.md b/docs/accessibility_testing.md index 4280c13bb..674b91ecb 100644 --- a/docs/accessibility_testing.md +++ b/docs/accessibility_testing.md @@ -4,6 +4,16 @@ The automated tests aim to test one page corresponding to each template in `amy/templates` (including base templates and the `includes` subfolder). +### Workflow + +The [GitHub Actions workflow](https://github.com/carpentries/amy/blob/develop/.github/workflows/accessibility.yml) includes options for testing with both [pa11y](https://pa11y.org/) and [Google Lighthouse](https://github.com/GoogleChrome/lighthouse). In both cases, the report can be found in the artifacts attached to the workflow run. The report contains one HTML file for each page covered by the tests, plus a summary file (something like `index.html`). + +### Local testing + +See the [AMY README](https://github.com/carpentries/amy#run-accessibility-tests-locally) for instructions on running the tests on your own machine. + +### Limitations + The following pages cannot be effectively tested automatically at the moment. Problems include: * page inaccessible to logged-in admin (`/terms/action_required``) From 570cb96fa047e67a1a13be67306739e25e404ff5 Mon Sep 17 00:00:00 2001 From: Eli Chadwick Date: Fri, 1 Dec 2023 17:21:32 +0000 Subject: [PATCH 2/2] note about which templates are tested --- docs/accessibility_testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/accessibility_testing.md b/docs/accessibility_testing.md index 674b91ecb..ba342f179 100644 --- a/docs/accessibility_testing.md +++ b/docs/accessibility_testing.md @@ -2,7 +2,7 @@ ## Automated Testing -The automated tests aim to test one page corresponding to each template in `amy/templates` (including base templates and the `includes` subfolder). +The automated tests aim to test one page corresponding to each template in `amy/templates` (including base templates and the `includes` subfolder). New templates should have a corresponding URL added to the [`.pa11yci`](https://github.com/carpentries/amy/blob/develop/.pa11yci) config file. As such, templates added since the last update to `.pa11yci` are not tested. ### Workflow