This part of the documentation covers the module associated with the `Git Data`_

section of the GitHub API.

These classes are meant to expose the entirety of an item returned as a search

In computer programming, unit testing is a method by which individual

units of source code, sets of one or more computer program modules

together with associated control data, usage procedures, and operating

procedures are tested to determine if they are fit for use. Intuitively,

-- `Unit Testing on Wikipedia

In github3.py we use unit tests to make assertions about how the library

behaves without making a request to the internet. For example, one assertion

we might write would check if custom information is sent along in a request to

An existing test like this can be found in

In this test, we check that the library passes on important headers to the API

to ensure the request will work properly. ``self.instance`` is created for us

and is an instance of the ``Release`` class. The test then calls ``delete`` to

make a request to the API. ``self.session`` is a mock object which fakes out a

normal session. It does not allow the request through but allows us to verify

how github3.py makes a request. We can see that github3.py called ``delete``

on the session. We assert that it was only called once and that the only

In object-oriented programming, mock objects are simulated objects that

mimic the behavior of real objects in controlled ways. A programmer

typically creates a mock object to test the behavior of some other object,

in much the same way that a car designer uses a crash test dummy to

We use mocks in github3.py to prevent the library from talking directly with

GitHub. The mocks we use intercept requests the library makes so we can verify

the parameters we use. In the example above, we were able to check that

certain parameters were the only ones sent to a session method because we

You may have noticed in the example above that we did not have to set up the

mock object. There is a convenient helper written in ``tests/unit/helper.py``

Here's a full example of how we test the ``Release`` object in

Our first step is to import the ``UnitHelper`` class from

``tests/unit/helper.py`` and the ``Release`` object from

Then we construct our test class and indicate which class we will be testing

We can then use the `GitHub API documentation about Releases

<http://developer.github.com/v3/repos/releases/>`_ to retrieve example release

The above code now will handle making clean and brand new instances of the

``Release`` object with the example data and a faked out session. We can now

Integration testing is the phase in software testing in which individual

The purpose of integration testing is to verify functional, performance,

-- `Integration tests on Wikipedia

In github3.py we use integration tests to ensure that when we make what should

be a valid request to GitHub, it is in fact valid. For example, if we were

testing how github3.py requests a user's information, we would expect a

request for a real user's data to be valid. If the test fails we know either

An existing test that demonstrates integration testing can be found in

In this test we use ``self.recorder`` to record our interaction with GitHub.

We then proceed to make the request to GitHub that will exercise the code we

wish to test. First we request a ``Repository`` object from GitHub and then

using that we request a ``Release`` object. After receiving that release, we

exercise the code that lists the assets of a ``Release``. We verify that each

asset is an instance of the ``Asset`` class and that at the end the ``asset``

variable is not ``None``. If ``asset`` was ``None``, that would indicate that

GitHub did not return any data and it did not exercise the code we are trying

Betamax_ is the library that we use to create the recorder above. It sets up

the session object to intercept every request and corresponding response and

save them to what it calls cassettes_. After you record the interaction it

In github3.py there is a helper class (much like ``UnitHelper``) in

Here's an example of how we write an integration test for github3.py. The

Every test has access to ``self.gh`` which is an instance of ``GitHub``.

``IntegrationHelper`` provides a lot of methods that allow you to focus on

what we are testing instead of setting up for the test. The first of those

methods we see in use is ``self.token_login`` which handles authenticating

with a token. It's sister method is ``self.basic_login`` which handles

authentication with basic credentials. Both of these methods will set up the

authentication for you on ``self.gh``.

The next convenience method we see is ``self.cassette_name``. It constructs a

cassette name for you based on the test class name and the string you provide

Every test also has access to ``self.recorder``. This is the Betamax recorder

that has been set up for you to record your interactions. The recorder is

Everything that talks to GitHub should be written inside of the context

created by the context manager there. No requests to GitHub should be made

In that context, we then retrieve a repository and create a release for it. We

want to be sure that we will be deleting something that exists so we assert

that what we received back from GitHub is not ``None``. Finally we call

When you write your new test and record a new cassette, be sure to add the new

The GitHub API does not just provide an API to interact with GitHub's

features. A whole section of the API provides a RESTful API to git operations

One of the really cool (and under used, it seems) parts of the GitHub API

GitHub provides tar files for download via tag objects. You can create one via

For the cases where we do not need an authenticated user, or where we are trying

to demonstrate the differences between the two, I will use ``anon``. ``anon``

could be instantiated like so::

`issue #108 <https://github.com/sigmavirus24/github3.py/issues/108>`_. Just

follow the code there and fill in your username, password (or token), and

comment message. Then run the script and watch as the issue opens in your

Not only can you create new issues, but you can import existing ones. When importing, you preserve the timestamp creation date; you can preserve the timestamp(s) for comment(s) too.