From 4934d1907c9963678ee3985c798b7079b55dae64 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Tue, 23 Dec 2014 12:39:36 -0600 Subject: [PATCH 1/2] Issue #397 - Editorial changes in Running tests section --- CONTRIBUTING.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29a7b674d..c3ac3e167 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -288,7 +288,9 @@ make build ## Running Tests -You can run tests from the project root with the `nosetests` command. +You can run the Python unit tests from the project root with the `nosetests` command. + +Running functional tests is a bit more involved (see the next section). ### Functional Tests @@ -318,13 +320,21 @@ In a separate terminal window or tab, start the application servers: source env/bin/activate && python run.py ``` -In another separate terminal window or tab, run the tests. Many tests require the ability to log in with GitHub OAuth. This is achieved by passing in a valid GitHub username: `user` and password: `pw` as command-line arguments: +In another separate terminal window or tab, run the tests: + +``` bash +node_modules/.bin/intern-runner config=tests/intern +``` + +Shortly after running this command, you should see the browser open and various pages appear and disappear automatically for a minute or two. The tests are complete when the browser window closes and you see a report of how many passed or failed in the terminal window that you ran the `intern-runner` command in. + +Many tests require the ability to log in with GitHub OAuth. This can be achieved by passing in a valid GitHub username: `user` and password: `pw` as command-line arguments: ``` bash node_modules/.bin/intern-runner config=tests/intern user=testusername pw=testpassword ``` -Shortly after running this command, you should see the browser open and various pages appear and disappear automatically for a minute or two. The tests are complete when the browser window closes and you see a report of how many passed or failed in the terminal window. +**Note** Be aware that this will add the `testusername` and `testpassword` to your bash history. It is possible to run the tests without using a GitHub username and password as command-line arguments. In that case, the automatic login will fail and you then have 10 seconds to manually enter a username and password in the GitHub login screen that appears. **Note**: It's possible to run the tests without using a GitHub username and password as command-line arguments. In that case, the automatic login will fail and you then have 10 seconds to manually enter a username and password in the GitHub login screen that appears. From 2bea4e1b7b71258d7a3def943195addcbddbfacd Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Tue, 23 Dec 2014 13:00:22 -0600 Subject: [PATCH 2/2] Issue #392 - Add section for writing unit and functional tests --- CONTRIBUTING.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3ac3e167..a315474b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,9 @@ You are welcome to contribute to this project. Here are the guidelines we try to * [Coding](#coding) * [Running Tests](#running-tests) * [Functional Tests](#functional-tests) +* [Writing Tests](#writing-tests) + * [Python Unit Tests](#python-unit-tests) + * [JS Functional Tests](#js-functional-tests) * [Production Server Setup](#production-server-setup) * [Acknowledgements](#acknowledgements) @@ -336,7 +339,31 @@ node_modules/.bin/intern-runner config=tests/intern user=testusername pw=testpas **Note** Be aware that this will add the `testusername` and `testpassword` to your bash history. It is possible to run the tests without using a GitHub username and password as command-line arguments. In that case, the automatic login will fail and you then have 10 seconds to manually enter a username and password in the GitHub login screen that appears. -**Note**: It's possible to run the tests without using a GitHub username and password as command-line arguments. In that case, the automatic login will fail and you then have 10 seconds to manually enter a username and password in the GitHub login screen that appears. +## Writing Tests + +Contributions that add or modify major functionality to the project should typically come with tests to ensure we're not breaking things (or won't in the future!). There's always room for more testing, so general contributions in this form are always welcome. + +### Python Unit Tests + +Our Python unit tests are vanilla flavored [`unittest`](https://docs.python.org/2/library/unittest.html) tests. Unit tests placed in the `tests` directory will be automatically detected by nose—no manual registration is necessary. + +Unit tests are preferred for features or functionality that are independent of the browser front-end, i.e., API responses, application routes, etc. + +Important documentation links: +* [Writing nose tests](https://nose.readthedocs.org/en/latest/writing_tests.html) +* [`unittest`](https://docs.python.org/2/library/unittest.html) +* [Testing Flask](http://flask.pocoo.org/docs/0.10/testing/) + +### JS Functional Tests + +Functional tests are written in JavaScript, using [Intern](http://theintern.io/). There's a nice [guide on the Intern wiki](https://github.com/theintern/intern/wiki/Writing-Tests-with-Intern#functional-testing) that should explain enough to get you started. + +Important documentation links: +* [Leadfoot](https://theintern.github.io/leadfoot/): the library that drives the browser (via Selenium). +* [ChaiJS](http://chaijs.com/api/assert/): the library used for assertions. +* [Intern wiki](https://github.com/theintern/intern/wiki): contains useful examples. + +It's also recommended to look at the other test files in the `tests/functional` directory to see how things are commonly done. ## Production Server Setup