Improve code example in marbles.core.TestCase docstring

[thejunglejane]

Description

The put function in the code example provided in marbles.core.TestCase is indented strangely.

import requests
import marbles.core


    def put(cls, endpoint, data=None):
        return Response(status_code=409,
                        reason=('The request could not be completed '
                                'due to a conflict with the current '
                                'state of the target resource.'))


class ResponseTestCase(marbles.core.TestCase):

    def test_create_resource(self):
        endpoint = 'http://example.com/api/v1/resource'
        data = {'id': 1, 'name': 'Little Bobby Tables'}

        res = requests.put(endpoint, data=data)
        self.assertEqual(
            res.status_code,
            201,
            note=res.reason

Intended audience

Users

Additional context

A better-motivated example would be appropriate here:

1. tests shouldn't be hitting external services
2. this example doesn't demonstrate the advantage of capturing more information about the test author's intent

[joshhn]

Hi @thejunglejane, I want to work on this issue. Can you assign me the issue? I have created a PR #142 to fix this issue. Can you help me review it? Thank you.

[joshhn]

@leifwalsh Thanks for merging my PR. I think this issue is resolved and should be closed.

[leifwalsh]

The indentation thing is fixed but the spirit of this issue was actually to find an example that demonstrates marbles better, so I'm going to leave it open until we do that.

[joshhn]

@leifwalsh I mentioned some ideas in #142. Do you think they could be better ones?

[leifwalsh]

@joshhn not really, those are more like canonical examples for unit tests.

The idea here in marbles is roughly that it's most useful outside the context of normal software unit tests (where a test should only fail because the code is wrong - and therefore your tests are generally very isolated). The context where marbles's notes are most useful is when you're testing something external to the code, and you sort of expect it to fail suddenly at some point because something outside the code (e.g. input data) changed - in this moment, since you didn't just introduce a code change (which you could attribute the failure to), you probably need to remind yourself about the mental context you had when you wrote the test.

So actually, making a network request in a test like that is mostly ok, but the example we have right now doesn't do a good job of conveying the "reminder" nature that notes are supposed to provide.

I think we can come up with a better example if we just sit down and do it, but it's not super high priority.