update test plan with TOC + autoformatting changes from pandoc

This commit was the result of running a pandocs command
to clean up the formatting and generate a table of contents
for the markdown document.

quality/Readme.md

@@ -0,0 +1,181 @@
+# Centillion Quality Engineering Plan
+
+Table of Contents
+-------
+
+*   [Centillion Quality Engineering Plan](#centillion-quality-engineering-plan)
+    *   [Summary](#summary)
+    *   [Tracking Bugs and Issues](#tracking-bugs-and-issues)
+    *   [Branches, Versioning, and Git Workflow](#branches-versioning-and-git-workflow)
+    *   [Communication and Mailing Lists](#communication-and-mailing-lists)
+    *   [Checklists](#checklists)
+    *   [Documentation](#documentation)
+    *   [Configuration Management Tools](#configuration-management-tools)
+    *   [Tests](#tests)
+    *   [Code Reviews](#code-reviews)
+    *   [Formal Release Process](#formal-release-process)
+    *   [Continual Process Improvement](#continual-process-improvement)
+
+Summary
+-------
+
+This document contains a quality engineering plan for centillion, the
+Data Commons search engine.
+
+Tracking Bugs and Issues
+------------------------
+
+We utilize the [issues
+section](https://github.com/dcppc/centillion/issues) of the centillion
+repository to keep track of bugs and feature requests.
+
+Branches, Versioning, and Git Workflow
+--------------------------------------
+
+All code is kept under version control in the
+[dcppc/centillion](https://github.com/dcppc/centillion) Github
+repository.
+
+**Primary Git Branches:**
+
+We utillize a git branch pattern that has two primary branches: a
+development branch and a stable branch.
+
+-   The primary **development branch** is `dcppc` and is actively
+    developed and deployed to <https://betasearch.nihdatacommons.us>.
+
+-   The primary **stable branch** is `releases/v1` and is stable and
+    deployed to <https://search.nihdatacommons.us>.
+
+All tagged versions of Centillion exist on the stable branch. Only
+tagged versions of centillion are run on
+<https://search.nihdatacommons.us>.
+
+**Other Branches:**
+
+Features are developed by creating a new branch from `dcppc`, working on
+the feature, and opening a pull request. When the pull request is
+approved, it can be merged into the `dcppc` branch.
+
+When features have accumulated and a new version is ready, a new
+pre-release branch will be made to prepare for a new release. When the
+pre-release branch is ready, it is merged into the stable branch in a
+single merge commit and a new version of centillion is tagged. The new
+version is deployed on <https://search.nihdatacommons.us>.
+
+Commits to fix bugs (hotfixes) may need to be applied to both the stable
+and development branches. In this case, a hotfix branch should be
+created from the head commit of the stable branch, and the appropriate
+changes should be made on the branch. A pull request should be opened to
+merge the hotfix into the release branch. A second pull request should
+be opened to merge the hotfix into the development branch. Once the
+hotfix is merged into the stable branch, a new version should be tagged.
+
+Communication and Mailing Lists
+-------------------------------
+
+-   No mailing list currently exists for centillion.
+
+-   Github issues are the primary form of communication about
+    development of centillion. This is the best method for communicating
+    bug reports or detailed information.
+
+-   The Send Feedback button on the centillion page is the primary way
+    of getting quick feedback from users about the search engine.
+
+-   The [\#centillion](https://nih-dcppc.slack.com/messages/CCD64QD6G)
+    Slack channel in the DCPPC slack workspace is the best place for
+    conversations about centillion (providing feedback, answering quick
+    questions, etc.)
+
+Checklists
+----------
+
+We plan to utilize the Wiki feature of the Github repository to develop
+checlists:
+
+-   Checklist for releases
+-   Checklist for deployment of https://search.nihdatacommons.us nginx
+    etc.
+
+Documentation
+-------------
+
+The documentation is a pile of markdown documents, turned into a static
+site using mkdocs.
+
+Configuration Management Tools
+------------------------------
+
+We do not currently utilize any configuration management software,
+because centillion is not packaged as an importable Python module.
+
+Packaging centillion is a future goal that is closely related to the
+need to improve and modularize the internal search schema/document type
+abstraction. These improvements would allow the types of collections
+being indexed to be separated from "core centillion", and core
+centillion would be packaged.
+
+Tests
+-----
+
+See (ref) for a full test plan with more detail.
+
+Summary of test plan:
+
+-   Implement tests for the four major pages/components
+    -   Login/authentication
+    -   Search
+    -   Master List
+    -   Control Panel
+-   Test authentication with two bot accounts (yammasnake and florence
+    python)
+
+-   Separate frontend and backend tests
+
+-   Add a test flag in the flask config file to change the backend
+    behavior of the server
+
+Code Reviews
+------------
+
+CI tests will be implemented for all pull requests.
+
+Pull requests to the **stable branch** have the following checks in
+place:
+
+-   PRs to the stable branch require at least 1 PR review
+-   PRs to the stable branch must pass CI tests
+
+Pull requests to the **development branch** have the following checks in
+place:
+
+-   PRs to the development branch must pass CI tests
+
+Formal Release Process
+----------------------
+
+In order to ensure a stable, consistent product, we utilize the
+branching pattern described above to implement new features in the
+development branch and test them out on
+<https://betasearch.nihdatacommons.us>.
+
+Once features and bug fixes have been tested and reviewed internally,
+they are ready to be deployed. A new pre-release branch is created from
+the development branch. The pre-release branch has a feature freeze in
+place. Changes are made to the pre-release branch to prepare it for the
+next major version release.
+
+When the pre-release branch is finished, it is merged into the stable
+branch. The head commit of the stable version is tagged with the lastest
+release number.
+
+Finally, the new version is deployed on
+<https://search.nihdatacommons.us>.
+
+Continual Process Improvement
+-----------------------------
+
+We will utilize the centillion wiki on Github to keep track of repeated
+processes and opportunities for improvement. Feedback and ideas for
+process improvement can also be submitted via Github issues.

tests/Readme.md

@@ -0,0 +1,196 @@
+Centillion Tests
+================
+
+Table of Contents
+------------------
+
+*   [Centillion Tests](#centillion-tests)
+    *   [Test Plan](#test-plan)
+        *   [Local Tests](#local-tests)
+        *   [Short Tests](#short-tests)
+        *   [Long Tests](#long-tests)
+    *   [Credentials](#credentials)
+    *   [Detailed Description of Tests](#detailed-description-of-tests)
+        *   [Authentication Layer Tests](#authentication-layer-tests)
+        *   [Search Function Tests](#search-function-tests)
+        *   [Master List Endpoint Tests](#master-list-endpoint-tests)
+        *   [Control Panel Endpoint Tests](#control-panel-endpoint-tests)
+        *   [Continuous Integration Plan](#continuous-integration-plan)
+    *   [Procedure/Checklist](#procedurechecklist)
+
+
+Test Plan
+---------
+
+Related: <https://github.com/dcppc/centillion/issues/82>
+
+The test suite for centillion needs to check each of the major
+components of centillion, as well as check the authentication mechanism
+using multiple login credentials.
+
+We implement the following checks:
+
+1.  Check authentication mechanism(s) (yamasnake and florence python)
+
+2.  Check search function
+
+3.  Check master list endpoint
+
+4.  Check control panel endpoint
+
+5.  Check update search index endpoints
+
+The tests are written such that the back end and front end are tested
+separately.
+
+We need also need different tiers of tests, so we don't max out API
+calls by making lots of commits to multiple PRs.
+
+We have three tiers of tests: \* Local tests - quick tests for CI, no
+API calls \* Short tests - tests using dummy API accounts \* Long tests
+- tests using DCPPC API accounts
+
+### Local Tests
+
+Local tests can be run locally without any interaction with APIs. These
+will still utilize centillion's search schema, but will load the search
+index with fake documents rather than fetching them from an API.
+
+Uncle Archie, which runs CI tests, runs local tests only (unless you
+request it to run short test or long test.)
+
+### Short Tests
+
+Short tests utilize credentials for bot accounts that have intentionally
+been set up to have a "known" corpus of test documents. These would
+provide unit-style tests for centillion - are the mechanics of indexing
+a particular type of document from a particular API working?
+
+### Long Tests
+
+Long tests are indexing the real deal, utilizing the credentials used in
+the final production centillion. This test takes longer but is more
+likely to catch corner cases specific to the DCPPC documents.
+
+Credentials
+-----------
+
+Running tests on centillion requires multiple sets of credentials. Let's
+lay out what is needed:
+
+-   The Flask app requires a token/secret token API key pair to allow
+    users to authenticate through Github and confirm they are members of
+    the DCPPC organization. This OAuth application is owned by Charles
+    Reid (@charlesreid1).
+
+-   The search index needs a Github access token so that it can
+    interface with the Github API to index files and issues. This access
+    token is specified (along with other secrets) in the Flask
+    configuration file. The access key comes from Florence Python
+    (@fp9695253).
+
+-   The search index also requires a Google Drive API access token. This
+    must be an access token for a user who has authenticated with the
+    Centillion Google Drive OAuth application. This access token comes
+    from <mailroom@nihdatacommons.com>.
+
+-   The search index requires API credentials for any other APIs
+    associated with other document collections (Groups.io, Hypothesis,
+    Disqus).
+
+-   The backend test requires the credentials provided to Flask.
+
+-   The frontend test (Selenium) needs two Github username/passwords:
+    one for Florence Python (@fp9695253) and one for Yamma Snake
+    (@yammasnake). These are required to simulate the user
+    authenticating with Github through the browser.
+    -   The frontend test credentials are a special case.
+    -   The frontend tests expect credentials to come from environment
+        variables.
+    -   These environment variables get passed in at test time.
+    -   Tests are all run on [Uncle
+        Archie](https://github.com/dcppc/uncle-archie).
+    -   Uncle Archie already has to protect a confidential config file
+        containing Github credentials, so add additional credentials for
+        frontend tests there.
+    -   Logical separation: these credentials are not needed to
+        *operate* centillion, these credentials are needed to *test*
+        centillion
+    -   Uncle Archie already requires github credentials, already
+        protects sensitive info.
+    -   Google Drive requiring its own credentials file on disk is a
+        pain.
+
+In summary: tests use the `config_flask.py` and `config_centillion.py`
+files to provide it with the API keys it needs and to instruct it on
+what to index. The credentials and config files will control what the
+search index will actually index. The Uncle Archie CI tester config file
+contains the credentials needed to run frontend tests (check the
+login/authentication layer).
+
+Detailed Description of Tests
+-----------------------------
+
+### Authentication Layer Tests
+
+Frontend tests run as Florence Python:
+
+-   Can we log in via github and reach centillion
+-   Can we reach the control panel
+
+Frontend tests run as Yamma Snake (DCPPC member):
+
+-   Can we log in via github and reach centillion
+-   Can we reach the control panel
+
+### Search Function Tests
+
+Frontend tests:
+
+-   Can we enter something into search box and submit
+-   Can we sort the results
+-   Do the results look okay
+
+Backend tests:
+
+-   Load the search index and run a query using whoosh API
+
+### Master List Endpoint Tests
+
+Frontend tests:
+
+-   Can we get to the master list page
+-   Can we sort the results
+-   Do the results look okay
+
+Backend tests:
+
+-   Check the output of the `/list` API endpoint
+
+### Control Panel Endpoint Tests
+
+Frontend tests:
+
+-   Can we get to the control panel page
+-   Can we click the button to trigger an indexing event
+
+Backend tests:
+
+-   Trigger a re-index of the search index from the backend.
+
+### Continuous Integration Plan
+
+Tests are automatically run using Uncle Archie for continuous
+integration and deployment.
+
+Procedure/Checklist
+-------------------
+
+Pre-release procedure:
+
+-   prepare to run all test
+
+-   run short tests
+-   deploy to beta
+-   run long tests
+-   test out