diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -27,27 +27,22 @@ * use of [es6](http://es6-features.org) syntax and advanced javascript feature like [async/await](https://javascript.info/async-await) or [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) thanks to [babel](https://babeljs.io/) (es6 to es5 transpiler and polyfills provider) * assets minification (using [terser](https://github.com/terser-js/terser) and [cssnano](http://cssnano.co/)) but also dead code elimination for production use -## How to build and run +## How to build, run and test -### Requirements +### Backend requirements First you will need [Python 3](https://www.python.org) and a complete [swh development environment](https://forge.softwareheritage.org/source/swh-environment/) installed. -To run the backend, you need to have the following Python 3 modules installed: -* beautifulsoup4 -* django >= 1.11.0 -* djangorestframework >= 3.4.0 -* django_webpack_loader -* django_js_reverse -* docutils -* file_magic >= 0.3.0 -* htmlmin -* lxml -* pygments -* pypandoc -* python-dateutil -* pyyaml -* requests +To run the backend, you need to have the following [Python 3 modules](requirements.txt) installed. + +To run the backend tests, the following [Python 3 modules](requirements-test.txt) are also required to be installed. + +One easy way to install them is to use the `pip` tool: +``` +$ pip install -r requirements.txt -r requirements-test.txt +``` + +### Frontend requirements To compile the frontend assets, you need to have [nodejs](https://nodejs.org/en/) >= 8.x and [yarn](https://yarnpkg.com/en/) installed. If you are on Debian stretch, you can easily install an up to date nodejs from the [stretch-backports](https://backports.debian.org/Instructions/) repository. @@ -56,7 +51,7 @@ Please note that the static assets bundles generated by webpack are not stored in the git repository. Follow the instructions below in order to generate them in order to be able to run the frontend part of the web applications. -### Make targets +### Make targets to execute the applications Below is the list of available make targets that can be executed from the root directory of swh-web in order to build and/or execute the web applications under various configurations: @@ -74,6 +69,26 @@ Once one of these targets executed, the web applications can be executed by pointing your browser to http://localhost:5004. +### Make targets to test the applications + +Some make targets are also available to easily execute the backend and frontend tests of the Software Heritage web applications. + +The backend tests are powered by the [pytest](https://docs.pytest.org/en/latest/) and [hypothesis](https://hypothesis.readthedocs.io/en/latest/) frameworks while the frontend ones rely on the use of the [cypress](https://www.cypress.io/) tool. + +Below is the exhaustive list of those targets: + +* **test**: execute the backend tests using a fast hypothesis profile (only one input example will be provided for each test) + +* **test-full**: execute the backend tests using a slower hypothesis profile (one hundred of input examples will be provided for each test which helps spotting possible bugs) + +* **test-frontend**: execute the frontend tests using cypress in headless mode but with some slow test suites disabled + +* **test-frontend-full**: execute the frontend tests using cypress in headless mode with all test suites enabled + +* **test-frontend-ui**: execute the frontend tests using the cypress GUI but with some slow test suites disabled + +* **test-frontend-full-ui**: execute the frontend tests using the cypress GUI with all test suites enabled + ### Yarn targets Below is a list of available yarn targets in order to only execute the frontend static assets compilation (no web server will be executed):