# Django Mockingbird: the fastest way to write the fastest Django unit tests
## 1. What is Django Mockingbird and why would I need it?
Until now, there were two options for writing tests for a Django application: either create objects in the database for every test or mock the database queries using [Unit test’s Mock](https://docs.python.org/3/library/unittest.mock.html). While the former is slow, the latter is complicated to write and read. Both add a lot of setup code to our tests. Django Mockingbird introduces a new way to write tests for Django, which is fast to run as well as simple to write.
## 2. How does it work?
It works by creating a mock object which behaves exactly like the Django model, but does not execute any queries under the hood. It only takes one line of code to use it in your test. It is not meant to be used in place of frameworks like [Pytest](https://docs.pytest.org/en/6.2.x/), but to complement them.
## 3. How do I use it?
### Installation
```python
pip install djangomockingbird
```
### Usage
```python
from djangomockingbird import mock_model
@mock_model('myapp.myfile.MyModel')
def test_my_test():
some_test_query = MyModel.objects.filter(bar='bar').filter.(foo='foo').first()
#some more code
#assertions here
```
With the mock_model decorator this test will pass no matter how complicated the query and will never touch the database.
### Specifiying mock return data
You can specify the values of specific fields of the model object you are mocking. If you don’t empty strings will be returned. Construct a dictionary with field names as keys and desired returs as values and pass it to the 'specs' argument of make_mocks. If you try to specify a nonexisant field as a key an error will be thrown, but you can specify any kind of value you want.
```python
@mock_model('myapp.myfile.MyModel', specs={'field': 'value'})
```
### Attention! Cases where returns must be specified: Model methods
If your model has custom methods and they are used by the test, you must specify their names and return data to the mock, otherwise your tests won't pass.
```python
model_method_specs = {'to_dict': {'': ''}}
@mock_model('myapp.myfile.MyModel', model_method_specs=model_method_specs)
```
## 4. Is it production ready? Can I help make it better?
This is still a very new project, but is quite stable for the general use case. However, there are advanced use cases that are not yet supported, most notably [custom model managers](https://docs.djangoproject.com/en/3.1/topics/db/managers/#custom-managers). For those test cases you can try supplementing Django Mockingbird with your own code or other libraries. Because this tool is really just one elaborate mock model it is very flexible and plays well with pretty much anything.
We would appreciate you opening issues to bring any defects or oversights to light. Contributions are also kindly accepted - see more on the code arhitecture principles below if you are interested.
## 5. Where can I read more details on the architecture?
Read about the how functional programming principles were used in the library [here](http://www.cmdctrlesc.xyz/post/6) and on metaprogramming features [here](http://www.cmdctrlesc.xyz/post/5).
Raw data
{
"_id": null,
"home_page": "https://github.com/larsvonschaff/Django-mockingbird",
"name": "djangomockingbird",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "django,testing",
"author": "larsvonschaff",
"author_email": "larsvonschaff@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cb/d9/2f35be335ec68d334df47496e6485b33b150da6bde991338e153d072b3ee/djangomockingbird-1.0.9.tar.gz",
"platform": null,
"description": "\n\n# Django Mockingbird: the fastest way to write the fastest Django unit tests\n\n\n\n\n\n\n\n## 1. What is Django Mockingbird and why would I need it?\n\nUntil now, there were two options for writing tests for a Django application: either create objects in the database for every test or mock the database queries using [Unit test\u2019s Mock](https://docs.python.org/3/library/unittest.mock.html). While the former is slow, the latter is complicated to write and read. Both add a lot of setup code to our tests. Django Mockingbird introduces a new way to write tests for Django, which is fast to run as well as simple to write.\n\n## 2. How does it work?\n\nIt works by creating a mock object which behaves exactly like the Django model, but does not execute any queries under the hood. It only takes one line of code to use it in your test. It is not meant to be used in place of frameworks like [Pytest](https://docs.pytest.org/en/6.2.x/), but to complement them.\n\n## 3. How do I use it?\n\n### Installation \n\n```python\npip install djangomockingbird\n```\n\n### Usage\n\n```python\n\nfrom djangomockingbird import mock_model\n\n@mock_model('myapp.myfile.MyModel')\ndef test_my_test():\n some_test_query = MyModel.objects.filter(bar='bar').filter.(foo='foo').first()\n #some more code\n #assertions here\n\n```\nWith the mock_model decorator this test will pass no matter how complicated the query and will never touch the database.\n\n\n### Specifiying mock return data\n\nYou can specify the values of specific fields of the model object you are mocking. If you don\u2019t empty strings will be returned. Construct a dictionary with field names as keys and desired returs as values and pass it to the 'specs' argument of make_mocks. If you try to specify a nonexisant field as a key an error will be thrown, but you can specify any kind of value you want.\n\n```python\n\n@mock_model('myapp.myfile.MyModel', specs={'field': 'value'})\n\n```\n\n### Attention! Cases where returns must be specified: Model methods\n\nIf your model has custom methods and they are used by the test, you must specify their names and return data to the mock, otherwise your tests won't pass. \n\n```python\n\n model_method_specs = {'to_dict': {'': ''}}\n@mock_model('myapp.myfile.MyModel', model_method_specs=model_method_specs)\n \n ```\n\n\n## 4. Is it production ready? Can I help make it better? \n\nThis is still a very new project, but is quite stable for the general use case. However, there are advanced use cases that are not yet supported, most notably [custom model managers](https://docs.djangoproject.com/en/3.1/topics/db/managers/#custom-managers). For those test cases you can try supplementing Django Mockingbird with your own code or other libraries. Because this tool is really just one elaborate mock model it is very flexible and plays well with pretty much anything.\n\nWe would appreciate you opening issues to bring any defects or oversights to light. Contributions are also kindly accepted - see more on the code arhitecture principles below if you are interested. \n\n## 5. Where can I read more details on the architecture?\n\nRead about the how functional programming principles were used in the library [here](http://www.cmdctrlesc.xyz/post/6) and on metaprogramming features [here](http://www.cmdctrlesc.xyz/post/5).\n\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The fastest way to write the fastest Django unit tests",
"version": "1.0.9",
"split_keywords": [
"django",
"testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c64cff5144d26b91c2abd584cdff9c666f98c9069599637c7657f1a6aeed3392",
"md5": "667f06987481235893ec5419adecbb83",
"sha256": "10fea1ea49da860b94071756a50a7a1da57caaba34384aa1819f20c9ade0e44e"
},
"downloads": -1,
"filename": "djangomockingbird-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "667f06987481235893ec5419adecbb83",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 8640,
"upload_time": "2023-01-21T00:15:16",
"upload_time_iso_8601": "2023-01-21T00:15:16.681840Z",
"url": "https://files.pythonhosted.org/packages/c6/4c/ff5144d26b91c2abd584cdff9c666f98c9069599637c7657f1a6aeed3392/djangomockingbird-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cbd92f35be335ec68d334df47496e6485b33b150da6bde991338e153d072b3ee",
"md5": "5e514126e45dcb11408a9bc1674c6cff",
"sha256": "1b7d9fe252ffa8c79a328a5479df737e090791fec130e052fe3cbdb8a61821b6"
},
"downloads": -1,
"filename": "djangomockingbird-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "5e514126e45dcb11408a9bc1674c6cff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 8566,
"upload_time": "2023-01-21T00:15:19",
"upload_time_iso_8601": "2023-01-21T00:15:19.559463Z",
"url": "https://files.pythonhosted.org/packages/cb/d9/2f35be335ec68d334df47496e6485b33b150da6bde991338e153d072b3ee/djangomockingbird-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-21 00:15:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "larsvonschaff",
"github_project": "Django-mockingbird",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "djangomockingbird"
}
JSON
