{"id":13416049,"url":"https://github.com/revsys/django-test-plus","last_synced_at":"2025-05-15T09:05:57.074Z","repository":{"id":32548746,"uuid":"36131033","full_name":"revsys/django-test-plus","owner":"revsys","description":"Useful additions to Django's default TestCase","archived":false,"fork":false,"pushed_at":"2024-08-11T12:15:04.000Z","size":500,"stargazers_count":623,"open_issues_count":7,"forks_count":63,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-10T18:45:07.473Z","etag":null,"topics":["django","testing"],"latest_commit_sha":null,"homepage":"https://django-test-plus.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/revsys.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-05-23T16:08:52.000Z","updated_at":"2025-05-10T00:20:19.000Z","dependencies_parsed_at":"2025-04-14T14:49:55.153Z","dependency_job_id":"adaf2231-4ca5-4dd4-988e-2d4f321c7ae7","html_url":"https://github.com/revsys/django-test-plus","commit_stats":{"total_commits":360,"total_committers":34,"mean_commits":"10.588235294117647","dds":0.6611111111111111,"last_synced_commit":"a7ffebed8fdbc997574f6a4c6fe8595fcf7fc982"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revsys%2Fdjango-test-plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revsys%2Fdjango-test-plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revsys%2Fdjango-test-plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revsys%2Fdjango-test-plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/revsys","download_url":"https://codeload.github.com/revsys/django-test-plus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754218,"owners_count":21958841,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","testing"],"created_at":"2024-07-30T21:00:53.903Z","updated_at":"2025-05-15T09:05:57.028Z","avatar_url":"https://github.com/revsys.png","language":"Python","funding_links":[],"categories":["Third-Party Packages","Testing","Python","Web Testing","测试"],"sub_categories":["Testing"],"readme":"# django-test-plus\n\nUseful additions to Django's default TestCase from [REVSYS](https://www.revsys.com/)\n\n[![pypi](https://img.shields.io/pypi/v/django-test-plus.svg)](https://pypi.org/project/django-test-plus/)\n[![build matrix demo](https://github.com/revsys/django-test-plus/actions/workflows/actions.yml/badge.svg)](https://github.com/revsys/django-test-plus/actions/workflows/actions.yml)\n\n## Rationale\n\nLet's face it, writing tests isn't always fun. Part of the reason for\nthat is all of the boilerplate you end up writing. django-test-plus is\nan attempt to cut down on some of that when writing Django tests. We\nguarantee it will increase the time before you get carpal tunnel by at\nleast 3 weeks!\n\nIf you would like to get started testing your Django apps or improve how your\nteam is testing we offer [TestStart](https://www.revsys.com/teststart/)\nto help your team dramatically improve your productivity.\n\n## Support\n\nSupports: Python 3.8, 3.9, 3.10, 3.11, and 3.12.\n\nSupports Django Versions: 3.2, 4.2, 5.0, and 5.1.\n\n## Documentation\n\nFull documentation is available at http://django-test-plus.readthedocs.org\n\n## Installation\n\n```shell\n$ pip install django-test-plus\n```\n\n## Usage\n\nTo use django-test-plus, have your tests inherit from test_plus.test.TestCase rather than the normal django.test.TestCase::\n\n```python\nfrom test_plus.test import TestCase\n\nclass MyViewTests(TestCase):\n    ...\n```\n\nThis is sufficient to get things rolling, but you are encouraged to\ncreate *your own* sub-classes for your projects. This will allow you\nto add your own project-specific helper methods.\n\nFor example, if you have a django project named 'myproject', you might\ncreate the following in `myproject/test.py`:\n\n```python\nfrom test_plus.test import TestCase as PlusTestCase\n\nclass TestCase(PlusTestCase):\n    pass\n```\n\nAnd then in your tests use:\n\n```python\nfrom myproject.test import TestCase\n\nclass MyViewTests(TestCase):\n    ...\n```\n\nThis import, which is similar to the way you would import Django's TestCase,\nis also valid:\n\n```python\nfrom test_plus import TestCase\n```\n\n## pytest Usage\n\nYou can get a TestCase like object as a pytest fixture now by asking for `tp`. All of the methods below would then work in pytest functions. For\nexample:\n\n```python\ndef test_url_reverse(tp):\n    expected_url = '/api/'\n    reversed_url = tp.reverse('api')\n    assert expected_url == reversed_url\n```\n\nThe `tp_api` fixture will provide a `TestCase` that uses django-rest-framework's `APIClient()`:\n\n```python\ndef test_url_reverse(tp_api):\n    response = tp_api.client.post(\"myapi\", format=\"json\")\n    assert response.status_code == 200\n```\n\n## Methods\n\n### `reverse(url_name, *args, **kwargs)`\n\nWhen testing views you often find yourself needing to reverse the URL's name. With django-test-plus there is no need for the `from django.core.urlresolvers import reverse` boilerplate. Instead, use:\n\n```python\ndef test_something(self):\n    url = self.reverse('my-url-name')\n    slug_url = self.reverse('name-takes-a-slug', slug='my-slug')\n    pk_url = self.reverse('name-takes-a-pk', pk=12)\n```\n\nAs you can see our reverse also passes along any args or kwargs you need\nto pass in.\n\n## `get(url_name, follow=True, *args, **kwargs)`\n\nAnother thing you do often is HTTP get urls. Our `get()` method\nassumes you are passing in a named URL with any args or kwargs necessary\nto reverse the url_name.\nIf needed, place kwargs for `TestClient.get()` in an 'extra' dictionary.:\n\n```python\ndef test_get_named_url(self):\n    response = self.get('my-url-name')\n    # Get XML data via AJAX request\n    xml_response = self.get(\n        'my-url-name',\n        extra={'HTTP_X_REQUESTED_WITH': 'XMLHttpRequest'})\n```\n\nWhen using this get method two other things happen for you: we store the\nlast response in `self.last_response` and the response's Context in `self.context`.\n\nSo instead of:\n\n```python\ndef test_default_django(self):\n    response = self.client.get(reverse('my-url-name'))\n    self.assertTrue('foo' in response.context)\n    self.assertEqual(response.context['foo'], 12)\n```\n\nYou can write:\n\n```python\ndef test_testplus_get(self):\n    self.get('my-url-name')\n    self.assertInContext('foo')\n    self.assertEqual(self.context['foo'], 12)\n```\n\nIt's also smart about already reversed URLs, so you can be lazy and do:\n\n```python\ndef test_testplus_get(self):\n    url = self.reverse('my-url-name')\n    self.get(url)\n    self.response_200()\n```\n\nIf you need to pass query string parameters to your url name, you can do so like this. Assuming the name 'search' maps to '/search/' then:\n\n```python\ndef test_testplus_get_query(self):\n    self.get('search', data={'query': 'testing'})\n```\n\nWould GET `/search/?query=testing`.\n\n## `post(url_name, data, follow=True, *args, **kwargs)`\n\nOur `post()` method takes a named URL, an optional dictionary of data you wish\nto post and any args or kwargs necessary to reverse the url_name.\nIf needed, place kwargs for `TestClient.post()` in an 'extra' dictionary.:\n\n```python\ndef test_post_named_url(self):\n    response = self.post('my-url-name', data={'coolness-factor': 11.0},\n                         extra={'HTTP_X_REQUESTED_WITH': 'XMLHttpRequest'})\n```\n\n*NOTE* Along with the frequently used get and post, we support all of the HTTP verbs such as put, patch, head, trace, options, and delete in the same fashion.\n\n## `get_context(key)`\n\nOften you need to get things out of the template context:\n\n```python\ndef test_context_data(self):\n    self.get('my-view-with-some-context')\n    slug = self.get_context('slug')\n```\n\n## `assertInContext(key)`\n\nYou can ensure a specific key exists in the last response's context by\nusing:\n\n```python\ndef test_in_context(self):\n    self.get('my-view-with-some-context')\n    self.assertInContext('some-key')\n```\n\n## `assertContext(key, value)`\n\nWe can get context values and ensure they exist, but we can also test\nequality while we're at it. This asserts that key == value:\n\n```python\ndef test_in_context(self):\n    self.get('my-view-with-some-context')\n    self.assertContext('some-key', 'expected value')\n```\n\n## `assert_http_###_\u003cstatus_name\u003e(response, msg=None)` - status code checking\n\nAnother test you often need to do is check that a response has a certain\nHTTP status code. With Django's default TestCase you would write:\n\n```python\nfrom django.core.urlresolvers import reverse\n\ndef test_status(self):\n    response = self.client.get(reverse('my-url-name'))\n    self.assertEqual(response.status_code, 200)\n```\n\nWith django-test-plus you can shorten that to be:\n\n```python\ndef test_better_status(self):\n    response = self.get('my-url-name')\n    self.assert_http_200_ok(response)\n```\n\nDjango-test-plus provides a majority of the status codes assertions for you. The status assertions\ncan be found in their own [mixin](https://github.com/revsys/django-test-plus/blob/main/test_plus/status_codes.py)\nand should be searchable if you're using an IDE like pycharm. It should be noted that in previous\nversions, django-test-plus had assertion methods in the pattern of `response_###()`, which are still\navailable but have since been deprecated. See below for a list of those methods.\n\nEach of the assertion methods takes an optional Django test client `response` and a string `msg` argument\nthat, if specified, is used as the error message when a failure occurs. The methods,\n`assert_http_301_moved_permanently` and `assert_http_302_found` also take an optional `url` argument that\nif passed, will check to make sure the `response.url` matches.\n\nIf it's available, the `assert_http_###_\u003cstatus_name\u003e` methods will use the last response. So you\ncan do:\n\n```python\ndef test_status(self):\n    self.get('my-url-name')\n    self.assert_http_200_ok()\n```\n\nWhich is a bit shorter.\n\nThe `response_###()` methods that are deprecated, but still available for use, include:\n\n- `response_200()`\n- `response_201()`\n- `response_204()`\n- `response_301()`\n- `response_302()`\n- `response_400()`\n- `response_401()`\n- `response_403()`\n- `response_404()`\n- `response_405()`\n- `response_409()`\n- `response_410()`\n\nAll of which take an optional Django test client response and a str msg argument that, if specified, is used as the error message when a failure occurs. Just like the `assert_http_###_\u003cstatus_name\u003e()` methods, these methods will use the last response if it's available.\n\n## `get_check_200(url_name, *args, **kwargs)`\n\nGETing and checking views return status 200 is a common test. This method makes it more convenient::\n\n```python\ndef test_even_better_status(self):\n    response = self.get_check_200('my-url-name')\n```\n\n## make_user(username='testuser', password='password', perms=None)\n\nWhen testing out views you often need to create various users to ensure\nall of your logic is safe and sound. To make this process easier, this\nmethod will create a user for you:\n\n```python\ndef test_user_stuff(self)\n    user1 = self.make_user('u1')\n    user2 = self.make_user('u2')\n```\n\nIf creating a User in your project is more complicated, say for example\nyou removed the `username` field from the default Django Auth model,\nyou can provide a [Factory\nBoy](https://factoryboy.readthedocs.org/en/latest/) factory to create\nit or override this method on your own sub-class.\n\nTo use a Factory Boy factory, create your class like this::\n\n```python\nfrom test_plus.test import TestCase\nfrom .factories import UserFactory\n\n\nclass MySpecialTest(TestCase):\n    user_factory = UserFactory\n\n    def test_special_creation(self):\n        user1 = self.make_user('u1')\n```\n\n**NOTE:** Users created by this method will have their password\nset to the string 'password' by default, in order to ease testing.\nIf you need a specific password, override the `password` parameter.\n\nYou can also pass in user permissions by passing in a string of\n'`\u003capp_name\u003e.\u003cperm name\u003e`' or '`\u003capp_name\u003e.*`'.  For example:\n\n```python\nuser2 = self.make_user(perms=['myapp.create_widget', 'otherapp.*'])\n```\n\n## `print_form_errors(response_or_form=None)`\n\nWhen debugging a failing test for a view with a form, this method helps you\nquickly look at any form errors.\n\nExample usage:\n\n```python\nclass MyFormTest(TestCase):\n\n    self.post('my-url-name', data={})\n    self.print_form_errors()\n\n    # or\n\n    resp = self.post('my-url-name', data={})\n    self.print_form_errors(resp)\n\n    # or\n\n    form = MyForm(data={})\n    self.print_form_errors(form)\n```\n\n## Authentication Helpers\n\n### `assertLoginRequired(url_name, *args, **kwargs)`\n\nThis method helps you test that a given named URL requires authorization:\n\n```python\ndef test_auth(self):\n    self.assertLoginRequired('my-restricted-url')\n    self.assertLoginRequired('my-restricted-object', pk=12)\n    self.assertLoginRequired('my-restricted-object', slug='something')\n```\n\n### `login()` context\n\nAlong with ensuring a view requires login and creating users, the next\nthing you end up doing is logging in as various users to test your\nrestriction logic:\n\n```python\ndef test_restrictions(self):\n    user1 = self.make_user('u1')\n    user2 = self.make_user('u2')\n\n    self.assertLoginRequired('my-protected-view')\n\n    with self.login(username=user1.username, password='password'):\n        response = self.get('my-protected-view')\n        # Test user1 sees what they should be seeing\n\n    with self.login(username=user2.username, password='password'):\n        response = self.get('my-protected-view')\n        # Test user2 see what they should be seeing\n```\n\nSince we're likely creating our users using `make_user()` from above,\nthe login context assumes the password is 'password' unless specified\notherwise. Therefore you you can do:\n\n```python\ndef test_restrictions(self):\n    user1 = self.make_user('u1')\n\n    with self.login(username=user1.username):\n        response = self.get('my-protected-view')\n```\n\nWe can also derive the username if we're using `make_user()` so we can\nshorten that up even further like this:\n\n```python\ndef test_restrictions(self):\n    user1 = self.make_user('u1')\n\n    with self.login(user1):\n        response = self.get('my-protected-view')\n```\n\n## Ensuring low query counts\n\n### `assertNumQueriesLessThan(number)` - context\n\nDjango provides\n[`assertNumQueries`](https://docs.djangoproject.com/en/1.8/topics/testing/tools/#django.test.TransactionTestCase.assertNumQueries)\nwhich is great when your code generates a specific number of\nqueries. However, if this number varies due to the nature of your data, with\nthis method you can still test to ensure the code doesn't start producing a ton\nmore queries than you expect:\n\n```python\ndef test_something_out(self):\n\n    with self.assertNumQueriesLessThan(7):\n        self.get('some-view-with-6-queries')\n```\n\n### `assertGoodView(url_name, *args, **kwargs)`\n\nThis method does a few things for you. It:\n\n- Retrieves the name URL\n- Ensures the view does not generate more than 50 queries\n- Ensures the response has status code 200\n- Returns the response\n\nOften a wide, sweeping test like this is better than no test at all. You\ncan use it like this:\n\n```python\ndef test_better_than_nothing(self):\n    response = self.assertGoodView('my-url-name')\n```\n\n## Testing DRF views\n\nTo take advantage of the convenience of DRF's test client, you can create a subclass of `TestCase` and set the `client_class` property:\n\n```python\nfrom test_plus import TestCase\nfrom rest_framework.test import APIClient\n\n\nclass APITestCase(TestCase):\n    client_class = APIClient\n```\n\nFor convenience, `test_plus` ships with `APITestCase`, which does just that:\n\n```python\nfrom test_plus import APITestCase\n\n\nclass MyAPITestCase(APITestCase):\n\n    def test_post(self):\n        data = {'testing': {'prop': 'value'}}\n        self.post('view-json', data=data, extra={'format': 'json'})\n        self.assert_http_200_ok()\n```\n\nNote that using `APITestCase` requires Django \u003e= 1.8 and having installed `django-rest-framework`.\n\n## Testing class-based \"generic\" views\n\nThe TestCase methods `get()` and `post()` work for both function-based\nand class-based views. However, in doing so they invoke Django's\nURL resolution, middleware, template processing, and decorator systems.\nFor integration testing this is desirable, as you want to ensure your\nURLs resolve properly, view permissions are enforced, etc.\nFor unit testing this is costly because all these Django request/response\nsystems are invoked in addition to your method, and they typically do not\naffect the end result.\n\nClass-based views (derived from Django's `generic.models.View` class)\ncontain methods and mixins which makes granular unit testing (more) feasible.\nQuite often your usage of a generic view class comprises an override\nof an existing method. Invoking the entire view and the Django request/response\nstack is a waste of time when you really want to call the overridden\nmethod directly and test the result.\n\nCBVTestCase to the rescue!\n\nAs with TestCase above, have your tests inherit\nfrom test_plus.test.CBVTestCase rather than TestCase like so:\n\n```python\nfrom test_plus.test import CBVTestCase\n\nclass MyViewTests(CBVTestCase):\n```\n\n## Methods\n\n### `get_instance(cls, initkwargs=None, request=None, *args, **kwargs)`\n\nThis core method simplifies the instantiation of your class, giving you\na way to invoke class methods directly.\n\nReturns an instance of `cls`, initialized with `initkwargs`.\nSets `request`, `args`, and `kwargs` attributes on the class instance.\n`args` and `kwargs` are the same values you would pass to `reverse()`.\n\nSample usage:\n\n```python\nfrom django.views import generic\nfrom test_plus.test import CBVTestCase\n\nclass MyClass(generic.DetailView)\n\n    def get_context_data(self, **kwargs):\n        kwargs['answer'] = 42\n        return kwargs\n\nclass MyTests(CBVTestCase):\n\n    def test_context_data(self):\n        my_view = self.get_instance(MyClass, {'object': some_object})\n        context = my_view.get_context_data()\n        self.assertEqual(context['answer'], 42)\n```\n\n### `get(cls, initkwargs=None, *args, **kwargs)`\n\nInvokes `cls.get()` and returns the response, rendering template if possible.\nBuilds on the `CBVTestCase.get_instance()` foundation.\n\nAll test_plus.test.TestCase methods are valid, so the following works:\n\n```python\nresponse = self.get(MyClass)\nself.assertContext('my_key', expected_value)\n```\n\nAll test_plus TestCase side-effects are honored and all test_plus\nTestCase assertion methods work with `CBVTestCase.get()`.\n\n**NOTE:** This method bypasses Django's middleware, and therefore context\nvariables created by middleware are not available. If this affects your\ntemplate/context testing, you should use TestCase instead of CBVTestCase.\n\n### `post(cls, data=None, initkwargs=None, *args, **kwargs)`\n\nInvokes `cls.post()` and returns the response, rendering template if possible.\nBuilds on the `CBVTestCase.get_instance()` foundation.\n\nExample:\n\n```python\nresponse = self.post(MyClass, data={'search_term': 'revsys'})\nself.response_200(response)\nself.assertContext('company_name', 'RevSys')\n```\n\nAll test_plus TestCase side-effects are honored and all test_plus\nTestCase assertion methods work with `CBVTestCase.post()`.\n\n**NOTE:** This method bypasses Django's middleware, and therefore context\nvariables created by middleware are not available. If this affects your\ntemplate/context testing you should use TestCase instead of CBVTestCase.\n\n### `get_check_200(cls, initkwargs=None, *args, **kwargs)`\n\nWorks just like `TestCase.get_check_200()`.\nCaller must provide a view class instead of a URL name or path parameter.\n\nAll test_plus TestCase side-effects are honored and all test_plus\nTestCase assertion methods work with `CBVTestCase.post()`.\n\n### `assertGoodView(cls, initkwargs=None, *args, **kwargs)`\n\nWorks just like `TestCase.assertGoodView()`.\nCaller must provide a view class instead of a URL name or path parameter.\n\nAll test_plus TestCase side-effects are honored and all test_plus\nTestCase assertion methods work with `CBVTestCase.post()`.\n\n## Development\n\nTo work on django-test-plus itself, clone this repository and run the following command:\n\n```shell\n$ pip install -e .\n$ pip install -e .[test]\n```\n\n## To run all tests:\n\n```shell\n$ nox\n```\n\n**NOTE**: You will also need to ensure that the `test_project` directory, located\nat the root of this repo, is in your virtualenv's path.\n\n## Keep in touch!\n\nIf you have a question about this project, please open a GitHub issue. If you love us and want to keep track of our goings-on, here's where you can find us online:\n\n\u003ca href=\"https://revsys.com?utm_medium=github\u0026utm_source=django-test-plus\"\u003e\u003cimg src=\"https://pbs.twimg.com/profile_images/915928618840285185/sUdRGIn1_400x400.jpg\" height=\"50\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://twitter.com/revsys\"\u003e\u003cimg src=\"https://cdn1.iconfinder.com/data/icons/new_twitter_icon/256/bird_twitter_new_simple.png\" height=\"43\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.facebook.com/revsysllc/\"\u003e\u003cimg src=\"https://cdn3.iconfinder.com/data/icons/picons-social/57/06-facebook-512.png\" height=\"50\" /\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevsys%2Fdjango-test-plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frevsys%2Fdjango-test-plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevsys%2Fdjango-test-plus/lists"}