Document automated testing in VMS

aut_docs/Design_Document.md

@@ -47,3 +47,34 @@ The QA process is divided as follows:
 
 - To follow up changes in UI with changes in tests, the modifications need to be made only
   in the relevant locators/urls/page file.
+
+- Addition of any new view implies that a pom `page` and `locator` need to be created.
+
+- Similarly, modifying any view implies that the corresponding `page` and `locator` will
+  also need to be modified.
+
+## Important points regarding creation of new Test Class:
+
+- As mentioned earlier, each test class corresponds to a view which has a corresponding
+  pom page and locator.
+
+- When creating a new test class, first identify the view the class is being created for,
+  and create corresponding pom page and locator.
+
+- Similarly, if you are modifying the existing templates make sure you update the corresponding
+  pom page and locators.
+
+- Each Test Class has `setUpClass` and `tearDownClass` class methods which should initiate and
+  quit the WebDriver objects respectively.
+
+- POM page should be linked to the Test Class in the `setUpClass` method itself and WebDriverWait
+  if needed in the tests should also be initiated in this method only.
+
+- If in the tests you are logging in as admin or volunteer make sure to `logout` in the `tearDown`
+  method of the Test Class.
+
+- Use of implicit waits should always be avoided unless needed in an extreme case and has the
+  approval of a maintainer. If wait is needed use explicit waits instead.
+
+- Tests in normal mode might fail if all are executed at once, but if a test is fails in
+  `HEADLESS` mode then the test is wrong and should be corrected accordingly.

aut_docs/Documented_Failures.md

@@ -0,0 +1,18 @@
+There are a few tests which have been commented out currently to avoid Travis CI build failure:
+
+| File                         | App/Model         | Test name                                                           | Reason/Related issue                              |
+|:----------------------------:|:-----------------:|:-------------------------------------------------------------------:|:-------------------------------------------------:|
+| test_settings.py             | Administrator     | test_duplicate_event                                                | Logic not yet implemented                         |
+| test_settings.py             | Administrator     | test_duplicate_job                                                  | Logic not yet implemented                         |
+| test_formFields.py           | Administrator     | test_field_value_retention_for_event                                | [#742](https://github.com/systers/vms/issues/742) |
+| test_formFields.py           | Administrator     | test_field_value_retention_for_job                                  | [#742](https://github.com/systers/vms/issues/742) |
+| test_formFields.py           | Administrator     | test_field_value_retention_for_shift                                | [#742](https://github.com/systers/vms/issues/742) |
+| test_report.py               | Administrator     | test_check_intersection_of_fields                                   | Test is giving inconsistent results, probably issue in logic|
+| test_volunteerProfile.py     | Volunteer         | test_valid_upload_resume                                            | [#776](https://github.com/systers/vms/issues/776)|
+| test_volunteerProfile.py     | Volunteer         | test_corrupt_resume_uploaded                                        | [#776](https://github.com/systers/vms/issues/776)|
+| test_functional_admin.py     | Registration      | test_field_value_retention_in_first_name_state_phone_organization   | [#763](https://github.com/systers/vms/issues/763)|
+| test_functional_admin.py     | Registration      | test_field_value_retention_in_last_name_address_city_country        | [#763](https://github.com/systers/vms/issues/763)|
+| test_functional_volunteer.py | Registration      | test_field_value_retention_in_first_name_state_phone_organization   | [#763](https://github.com/systers/vms/issues/763)|
+| test_functional_volunteer.py | Registration      | test_field_value_retention_in_last_name_address_city_country        | [#763](https://github.com/systers/vms/issues/763)|
+| test_unit.py                 | Shift             | test_invalid_model_create                                           | [#743](https://github.com/systers/vms/issues/743)|
+| test_unit.py                 | VolunteerShift    | test_invalid_model_create                                           | [#743](https://github.com/systers/vms/issues/743)|

aut_docs/Installation_Setup.md

@@ -0,0 +1,95 @@
+## Steps to run tests:
+
+A one-time setup requires the following four steps:
+
+- Install python,
+    ```bash
+      sudo apt-get install python3.6
+    ```
+
+- Install virtual environment
+    ```bash
+      sudo apt-get install virtualenv
+    ```
+
+- Clone the VMS project
+    ```bash
+      git clone https://github.com/systers/vms.git
+    ```
+
+- Create python3.6 virtual environment
+    ```bash
+      virtualenv -p python3.6 venv
+    ```
+
+Following points are needed to start a testing session:
+
+- Activate virtual environment
+    ```bash
+      source venv/bin/activate
+    ```
+- Install all python dependencies
+    ```bash
+      pip install -r requirements.txt
+    ```
+
+  :Note: If you face any errors, do not open a new issue and ask for help on slack with full error logs.
+
+- Change directory to VMS code
+    ```bash
+      cd vms/
+    ```
+
+- Create migrations for database
+    ```bash
+      python manage.py makemigrations auth volunteer administrator organization event job shift registration
+    ```
+
+- Apply migrations to database
+    ```bash
+      python manage.py migrate --noinput --traceback --settings=vms.settings
+    ```
+
+- Check that the project is running correctly by browsing to
+    ```
+      http://127.0.0.1:8000
+    ```
+    after running the command
+    ```bash
+      python manage.py runserver
+    ```
+
+- Automated tests in VMS require you to setup geckodriver in your path. For that, either run this command in root of project:
+    ```bash
+      bash setup-geckodriver.sh
+    ```
+    OR run these commands:
+    ```bash
+      wget https://github.com/mozilla/geckodriver/releases/download/v0.20.1/geckodriver-v0.20.1-linux64.tar.gz
+      tar -xzvf geckodriver-v0.20.1-linux64.tar.gz
+      sudo mv geckodriver /usr/local/bin
+    ```
+  :Note: If you are using Windows then see this link to configure geckodriver in your environment https://stackoverflow.com/a/40208762
+
+- To execute all tests VMS, use this command:
+    ```bash
+      python manage.py test -v 2
+    ```
+
+- To execute tests in a particular file use:
+    ```bash
+      python manage.py test <app_name> -v 2 
+    ```
+
+- To execute a test file inside a app use:
+    ```bash
+      python manage.py test <app_name>.tests.<test_file_name> -v 2
+    ```
+
+- For the automated tests, f geckodriver has been configured correctly then during simulation of tests the firefox browser will automatically open up and perform the actions and close at the end of the test.
+
+- If all tests pass, `OK` will be received at the end.
+
+- For automated tests, if any of the tests fail its not necessary that there is something wrong. To confirm if the the test is actually wrong you have to test it in headless mode.
+
+:Note: For automated testing, currently VMS uses the Firefox version 60, selenium version 3.4.0 and geckodriver version 0.20.1