Updated test suites to support a placeholder for the namespaces

- modified conftest setup for putting the placeholders in place
- modified the cassettes to replace explicit namespaces call with placeholders
- updated README with usage of the test suites

Author: guyzmo

README.md

@@ -133,6 +133,36 @@ and then you'll have the executable in `bin`:
 
     % bin/git-repo --help
 
+To run the tests:
+
+    % bin/py.test
+
+You can use the following options for py.test to help you debug when tests fail:
+
+* `-v` will show more details upon errors
+* `-x` will stop upon the first failure
+* `--pdb` will launch the debugger where an exception has been launched
+
+
+The tests use recordings of exchanged HTTP data, so that we don't need real credentials
+and a real connection, when testing the API on minor changes. Those recordings are
+called cassettes, thanks to the [betamax](https://github.com/sigmavirus24/betamax) framework
+being in use in the test suites.
+
+When running existing tests, based on the provided cassettes, you don't need any 
+setting. Also, if you've got a configuration in `~/.gitconfig`, the tests will use
+them. Anyway, you can use environment variables for those settings (environment
+variables will have precedence over the configuration settings):
+
+To use your own credentials, you can setup the following environment variables:
+
+* `GITHUB_NAMESPACE` (which defaults to `not_configured`) is the name of the account to use on github
+* `GITLAB_NAMESPACE` (which defaults to `not_configured`) is the name of the account to use on gitlab 
+* `BITBUCKET_NAMESPACE` (which defaults to `not_configured`) is the name of the account to use on bitbucket
+* `PRIVATE_KEY_GITHUB` your private token you've setup on github for your account
+* `PRIVATE_KEY_GITLAB` your private token you've setup on gitlab for your account
+* `PRIVATE_KEY_BITBUCKET` your private token you've setup on bitbucket for your account
+
 ### TODO
 
 * [x] make a `git-repo fork` action
@@ -148,6 +178,8 @@ and then you'll have the executable in `bin`:
   * [ ] fetch them as local branches
 * [ ] add OAuth support for bitbucket
 * [ ] show a nice progress bar, while it's fetching
+  * partly implemented: the issue looks like that gitpython expects output from git
+    on stderr, whereas it's outputing on stdout.
 * for more features, write an issue or, even better, a PR!
 
 ### License

tests/conftest.py

@@ -1,23 +1,45 @@
 #!/usr/bin/env python
 
+import os
+
 import betamax
 from betamax_serializers import pretty_json
 
-# tests/conftest.py
-import os
-
-api_token_github = os.environ.get('PRIVATE_KEY_GITHUB', 'not_configured')
-api_token_gitlab = os.environ.get('PRIVATE_KEY_GITLAB', 'not_configured')
-api_token_bitbucket = os.environ.get('PRIVATE_KEY_BITBUCKET', 'not_configured')
+record_mode = 'never' if os.environ.get('TRAVIS_GH3') else 'once'
+
+# create default bogus values for tokens and namespaces if missing for pytest
+# to run without environment values
+# also if an environment variable is not set, then we don't want to record cassettes
+for service_name in ('github', 'gitlab', 'bitbucket'):
+    token_name = 'PRIVATE_KEY_{}'.format(service_name.upper())
+    namespace_name = '{}_NAMESPACE'.format(service_name.upper())
+    if token_name not in os.environ:
+        os.environ[token_name] = 'not_configured:test' # using a : for bitbucket's case
+        record_mode = 'never'
+    if namespace_name not in os.environ:
+        os.environ[namespace_name] = 'not_configured'
+        record_mode = 'never'
+
+api_token_github = os.environ['PRIVATE_KEY_GITHUB']
+api_token_gitlab = os.environ['PRIVATE_KEY_GITLAB']
+api_token_bitbucket = os.environ['PRIVATE_KEY_BITBUCKET']
+
+github_namespace = os.environ['GITHUB_NAMESPACE']
+gitlab_namespace = os.environ['GITLAB_NAMESPACE']
+bitbucket_namespace = os.environ['BITBUCKET_NAMESPACE']
 
 betamax.Betamax.register_serializer(pretty_json.PrettyJSONSerializer)
 
 with betamax.Betamax.configure() as config:
+    config.default_cassette_options['record_mode'] = record_mode
     config.cassette_library_dir = 'tests/integration/cassettes'
     config.default_cassette_options['serialize_with'] = 'prettyjson'
     config.define_cassette_placeholder('<PRIVATE_KEY_GITHUB>', api_token_github)
     config.define_cassette_placeholder('<PRIVATE_KEY_GITLAB>', api_token_gitlab)
     config.define_cassette_placeholder('<PRIVATE_KEY_BITBUCKET>', api_token_bitbucket)
+    config.define_cassette_placeholder('<GITHUB_NAMESPACE>', github_namespace)
+    config.define_cassette_placeholder('<GITLAB_NAMESPACE>', gitlab_namespace)
+    config.define_cassette_placeholder('<BITBUCKET_NAMESPACE>', bitbucket_namespace)