1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
.. _ddf:
Core DDF features
*******************************************************************************
.. contents::
:local:
Get: G
===============================================================================
The ``G`` function (shortcut for the ``get`` function) is the main feature of DDF. It is useful for integration tests, for the model logic and queries to the database.
It receives a model class and it will return a **valid and persisted instance** filled with dynamically generated data::
from ddf import G # or from ddf import get
author = G(Author)
assert author.id is not None # indicating the instance was saved
assert author.name is not None # indicating a name was generated for you
assert len(author.name) > 0
This facilitates writing tests and it hides all dummy data that pollutes the source code. But all **important data of the test may be explicitly defined**. This is even a good practice, because it let the test very clear and cohesive::
book = G(Book, name='The Lord of the Rings', publish_date=date(1954, 07, 29))
assert book.name == 'The Lord of the Rings'
assert book.publish_date == date(1954, 07, 29)
Important details:
* The **id** (AutoField) is auto filled, unless you set a value to it.
* if a field has **default value**, it is used by default. Unless you override it.
* if a field has **choices**, the first option is selected by default. Unless you override it.
New: N
===============================================================================
This function ``N`` (shortcut to ``new``) is similar to ``G``, except it will NOT save the generated instance. This is good for **unit tests**, without touching the database::
from ddf import N
not_saved_book = N(Book)
assert not_saved_book.id is None # indicating the instance was NOT saved
assert not_saved_book.name is not None # indicating a name was generated for you
It can also be usefuf to **manipulate the instance before saving it**. Usually, we need that to deal with custom fields, custom validations etc. For these cases, we can use the ``persist_dependencies=True`` parameter to save internal dependencies of ``ForeignKey`` and ``OneToOneField`` fields::
book = N(Book, persist_dependencies=True)
assert book.id is None # the Book was not persisted
assert book.publisher.id is not None # internal dependency was persisted
ps: Since the instance does not have an ID, it can NOT insert instances in ``ManyToManyField`` fields. So, be aware to use the ``G`` function for these cases.
Fixture: F
===============================================================================
DDF also allows you **customise recursively through relationship fields** ``ForeignKey``, ``OneToOneField`` and ``ManyToManyField``) using the ``F`` function (shortcut for ``fixture``).
ForeignKey and OneToOneField
-------------------------------------------------------------------------------
To customise relationships, you can use the ``F`` function or the Django look up syntax::
from ddf import G, F
book = G(Book, author=F(name='Eistein'))
# or, even simpler, using the Django loop up syntax:
book = G(Book, author__name='Eistein')
assert book.author.name == 'Eistein'
This is the equivalent to::
author = G(Author, name='Eistein')
book = G(Book, author=author)
assert book.author.name == 'Eistein'
``F`` function is recursible::
book = G(Book, author=F(address=F(zipcode='123456789')))
# or, even simpler, using the Django loop up syntax:
book = G(Book, author__address__zipcode='123456789')
assert book.author.address.zipcode == '123456789'
``F`` can be used to customize instances of a ``ManyToManyField`` too::
book = G(Book, authors=[F(name='Eistein'), F(name='Tesla')])
assert book.authors.all()[0].name == 'Eistein'
assert book.authors.all()[1].name == 'Tesla'
Django Look Up fields syntax (New in 1.6.1) (Fixed in 3.0.0)
-------------------------------------------------------------------------------
This is an alias to ``F`` function, and it follows the Django pattern of filters that use two underlines to access internal fields of foreign keys. You can **combine** multiple parameters to create a complete customisable instance.
ps: Just be careful because DDF does NOT interpret **related names** yet. It has also some limitation for many to many fields.
Many to Many fields
-------------------------------------------------------------------------------
DDF can add instances in ``ManyToManyFields``, but only if the instance has been persisted to the database (Django requirement). DDF handles ``ManyToManyFields`` with ``through`` table as well.
It is possible to define **how many instances** will be created dynamically::
book = G(Book, authors=5)
assert book.authors.all().count() == 5
It is possible to customize each instance of the ``ManyToManyField``::
book = G(Book, authors=[F(name='Eistein'), F(address__zipcode='123456789')])
assert book.authors.all().count() == 2
assert instance.authors.all()[0].name == 'Eistein'
assert instance.authors.all()[1].address.zipcode == '123456789'
It is possible to pass already created instances too::
author1 = G(Author)
author2 = G(Author)
book = G(Book, authors=[author1, author2])
assert book.authors.all().count() == 2
Or even mixed them up::
book = G(Book, authors=[F(), author1, F(), author2])
assert book.authors.all().count() == 4
Mask: M (New in 3.1.0)
===============================================================================
``M`` (shortcut for ``Mask``) is a feature that tell DDF to generate a random string using a custom mask.
The mask symbols are:
- ``#``: represents a number: 0-9
- ``-``: represents a upper case char: A-Z
- ``_``: represents a lower case char: a-z
- ``!``: escape mask symbols, inclusive itself
Examples::
from ddf import G, M
instance = G(Publisher, address=M(r'St. -______, ### !- -- --'))
assert instance.address == 'St. Imaiden, 164 - SP BR'
Copier: C (New in 1.6.0)
===============================================================================
``C`` (shortcut for ``Copier``) is a feature to copy the data of a field to another one. It is necessary to avoid cycles in the copier expression. If a cycle is found, DDF will alert the programmer the expression is invalid::
from ddf import G, C
user = G(User, first_name=C('username'))
assert instance.first_name == instance.username
instance = G(MyModel, first_name=C('username'), username='eistein')
assert instance.first_name == 'eistein'
It is possible to copy values of internal relationships, but only in the **bottom-up way**::
person = G(Person, phone=C('parent.phone'))
assert person.phone == person.parent.phone
Teaching DDF with Lessons (shelve in 2.1.0) (New in 3.0.0)
===============================================================================
Sometimes DDF can not generate a valid and persisted instance because it contains custom fields or custom validations (field or model validation). In these cases, it is possible to **teach DDF how to build a valid instance**. It is necessary to create a valid configuration and save it in an internal and global DDF library of configurations. All future instances of that model will use the saved lesson as base.
In the **PyTest** **conftest.py** file or another global module that will be loaded before the test suite::
from ddf import teach
teach(Author, name='Eistein')
# After this command, all authors will have the name Eistein, unless it was overrided.
In the test files::
from ddf import G
author = G(Author)
assert author.name == 'Eistein'
It is possible to **override** the lessons though::
author = G(Author, name='Tesla')
assert author.name == 'Tesla'
It is possible to store **custom functions** of data fixtures for fields too::
zip_code_data_fixture = lambda field: 'MN {}'.format(random.randint())
teach(Address, zip_code=zip_code_data_fixture)
address = G(Address)
assert address.zip_code == 'MN 55416'
It is possible to store **Copiers** too::
teach(Author, first_name=C('username'))
author = G(Author, username='eistein')
assert instance.username == 'eistein'
assert instance.first_name == 'eistein'
It is also possible to save custom lessons that will override the default one. But avoid having too many of them, since this will became the test suite very complex.
You can have **many custom lessons** too, giving names to them::
from ddf import teach
teach(Model, field_x=77)
teach(Model, field_x=88, ddf_lesson='my custom lesson 1')
teach(Model, field_x=99, ddf_lesson='my custom lesson 2')
instance = G(Model)
assert instance.field_x == 77
instance = G(Model, ddf_lesson='my custom lesson 1')
assert instance.field_x == 88
instance = G(Model, ddf_lesson='my custom lesson 2')
assert instance.field_x == 99
ps: Just be aware that overriding lessons is an anti-pattern and may let your test suite very hard to understand.
|
