Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve code example in marbles.core.TestCase docstring #117

Open
thejunglejane opened this issue Nov 18, 2019 · 5 comments
Open

Improve code example in marbles.core.TestCase docstring #117

thejunglejane opened this issue Nov 18, 2019 · 5 comments
Labels
docs good first issue Good for newcomers

Comments

@thejunglejane
Copy link
Contributor

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
Copy link
Contributor

joshhn commented Dec 20, 2023

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
Copy link
Contributor

joshhn commented Dec 28, 2023

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

@leifwalsh
Copy link
Contributor

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
Copy link
Contributor

joshhn commented Dec 28, 2023

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

@leifwalsh
Copy link
Contributor

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs good first issue Good for newcomers
Projects
None yet
Development

No branches or pull requests

3 participants