Factory.pm

filter: Statementstmt 100% 95 / 95 Branchbran 70.0% 7 / 10 Conditioncond 100% 4 / 4 MC/DCmcdc 100% 2 / 2 Subroutinesub 100% 29 / 29 Podpod 100% 18 / 18 totaltotal 98.1% 155 / 158 CC 12 SCAR 6.4
CC
12
Cov
97%
base_factory
5.0
exclude
3.0
seq
2.0
CRAP 1.9
« Factory/Fields.pm ↑ Summary
1 package DBIx::Class::Factory;
2  
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 1 ▶use DBIx::Class::Factory::Fields;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 =encoding utf8
9  
10 =head1 NAME
11  
12 DBIx::Class::Factory - factory-style fixtures for DBIx::Class
13  
14 =head1 VERSION
15  
16 Version 0.04
17  
18 =cut
19  
20 1 our $VERSION = '0.04';
21  
22 =head1 SYNOPSIS
23  
24 Create factory:
25  
26 package My::UserFactory;
27 use base qw(DBIx::Class::Factory);
28  
29 __PACKAGE__->resultset(My::Schema->resultset('User'));
30 __PACKAGE__->fields({
31 name => __PACKAGE__->seq(sub {'User #' . shift}),
32 status => 'new',
33 });
34  
35 package My::SuperUserFactory;
36 use base qw(DBIx::Class::Factory);
37  
38 __PACKAGE__->base_factory('My::UserFactory');
39 __PACKAGE__->field(superuser => 1);
40  
41 Use factory:
42  
43 my $user = My::UserFactory->create();
44 my @verified_users = @{ My::UserFactory->create_batch(3, {status => 'verified'}) };
45  
46 my $superuser = My::SuperUserFactory->build();
47 $superuser->insert();
48  
49 =head1 DESCRIPTION
50  
51 Ruby has C<factory_girl>, Python has C<factory_boy>. Now Perl has C<DBIx::Class::Factory>.
52  
53 Creating big fixture batches may be a pain. This module provides easy way
54 of creating data in database via L<DBIx::Class>.
55  
56 To create a factory just derive from L<DBIx::Class::Factory> and apply some settings.
57 You can also add some data at the moment of creating instance, redefining factory defaults.
58  
59 Tests for this module contains a bunch of usefull examples.
60  
61 =head1 METHODS
62  
63 =head2 Factory settings
64  
65 =over
66  
67 =item B<base_factory>
68  
69 Use this to create one factory derived from another. Don't use direct inheritance.
70  
71 =cut
72  
73 3 ▶sub base_factory {
Subroutine base_factory: called CC=5 SCAR=16.1
Pod documented
74 3 my ($class, $base_class) = @_;
75  
76 3 foreach my $data_field (qw(fields exclude)) {
77 $class->_class_data->{$data_field} = {
78 6 ▶ %{ $base_class->_class_data->{$data_field} || {} },
Condition100%2/2
$base_class->_class_data->{$data_field} || {}
l!l
42
MC/DC100%1/1
$base_class->_class_data->{$data_field} || {}
$base_class->_class_data->{$data_field}
Truth table100%2/2
A
A= $base_class->_class_data->{$data_field}
Aresult
11
00
79 6 ▶ %{ $class ->_class_data->{$data_field} || {} },
Condition100%2/2
$class->_class_data->{$data_field} || {}
l!l
33
MC/DC100%1/1
$class->_class_data->{$data_field} || {}
$class->_class_data->{$data_field}
Truth table100%2/2
A
A= $class->_class_data->{$data_field}
Aresult
11
00
80 };
81 }
82  
83 $class->_class_data->{resultset} = $base_class->_class_data->{resultset}
84 3 ▶ unless defined $class->_class_data->{resultset};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $class->_class_data->{"resultset"} 3 0 3
85  
86 1 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
87 3 push(@{$class . '::ISA'}, $base_class);
88  
89 3 return;
90 }
91  
92 =item B<resultset>
93  
94 Set resultset this factory is going to work with.
95  
96 =cut
97  
98 4 ▶sub resultset {
Subroutine resultset: called CC=1 SCAR=0.0
Pod documented
99 4 my ($class, $resultset) = @_;
100  
101 4 $class->_class_data->{resultset} = $resultset;
102  
103 4 return;
104 }
105  
106 =item B<fields>
107  
108 Accept hashref as an argument. Add fields to factory. See L</field> for more details.
109  
110 =cut
111  
112 6 ▶sub fields {
Subroutine fields: called CC=2 SCAR=6.9
Pod documented
113 6 my ($class, $fields) = @_;
114  
115 6 foreach my $key (keys %{$fields}) {
116 11 $class->field($key => $fields->{$key});
117 }
118  
119 6 return;
120 }
121  
122 =item B<field>
123  
124 __PACKAGE__->field($name => $value);
125  
126 Add field to the factory. C<$name> is directly used in resultset's C<new> method.
127 C<$value> must be any value or helper result (see L</Helpers>).
128 C<CODEREF> as a value will be used as callback. However, you must not rely on this,
129 it can be changed in future releases — use L</callback> helper instead.
130  
131 =cut
132  
133 11 ▶sub field {
Subroutine field: called CC=1 SCAR=0.0
Pod documented
134 11 my ($class, $key, $value) = @_;
135  
136 11 $class->_class_data->{fields}->{$key} = $value;
137  
138 11 return;
139 }
140  
141 =item B<exclude>
142  
143 Sometimes you want some fields to be in the factory but not in the created object.
144  
145 You can use C<exclude> to exclude them. Both arrayref and scalar are accepted.
146  
147 {
148 package My::UserFactory;
149  
150 use base qw(DBIx::Class::Factory);
151  
152 __PACKAGE__->resultset(My::Schema->resultset('User'));
153 __PACKAGE__->exclude('all_names');
154 __PACKAGE__->fields({
155 first_name => __PACKAGE__->callback(sub {shift->get('all_names')}),
156 last_name => __PACKAGE__->callback(sub {shift->get('all_names')}),
157 });
158 }
159  
160 My::UserFactory->create({all_names => 'Bond'});
161  
162 =cut
163  
164 1 ▶sub exclude {
Subroutine exclude: called CC=3 SCAR=11.0
Pod documented
165 1 my ($class, $list) = @_;
166  
167 1 ▶ unless (ref $list eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $list eq "ARRAY") 1 0 1
168 1 $list = [$list];
169 }
170  
171 1 foreach my $exclude_field (@{$list}) {
172 1 $class->_class_data->{exclude}->{$exclude_field} = 1;
173 }
174  
175 1 return;
176 }
177  
178 =back
179  
180 =head2 Helpers
181  
182 Sometimes you want the value of the field to be not just static value but something special.
183 Helpers are here for that.
184  
185 =over
186  
187 =item B<callback>
188  
189 Sometimes you want field value to be calculated everytime fields for object are created.
190 Just provide C<callback> as a value in that case.
191  
192 It will be called with the L<DBIx::Class::Factory::Fields> instance as an argument.
193  
194 __PACKAGE__->fields({
195 status => __PACKAGE__->callback(sub {
196 my ($fields) = @_;
197
198 return $fields->get('superuser') ? 3 : 5;
199 }),
200 });
201  
202 =cut
203  
204 2 ▶sub callback {
Subroutine callback: called CC=1 SCAR=0.0
Pod documented
205 2 my ($class, $block) = @_;
206  
207 2 ▶ return sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
208 2 $block->(@_);
209 }
210 2 }
211  
212 =item B<seq>
213  
214 Same as L</callback>, but the callback is called with an additional first argument: the iterating counter.
215  
216 You can also provide the initial value of the counter (C<0> is default).
217  
218 __PACKAGE__->field(id => __PACKAGE__->seq(sub {shift}, 1));
219  
220 =cut
221  
222 1 ▶sub seq {
Subroutine seq: called CC=2 SCAR=7.0
Pod documented
223 1 my ($class, $block, $init_value) = @_;
224  
225 1 ▶ $init_value = 0 unless defined $init_value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $init_value 0 1 1
226  
227 12 ▶ return sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
228 12 $block->($init_value++, @_);
229 }
230 1 }
231  
232 =item B<related_factory>
233  
234 This helper just calls another factory's L</get_fields> method.
235 Thanks to C<DBIx::Class>, the returned data will be used to create a related object.
236  
237 package My::UserFactory;
238  
239 use base qw(DBIx::Class::Factory);
240  
241 __PACKAGE__->resultset(My::Schema->resultset('User'));
242 __PACKAGE__->fields({
243 # create a new city if it's not specified
244 city => __PACKAGE__->related_factory('My::CityFactory'),
245 });
246  
247 =cut
248  
249 1 ▶sub related_factory {
Subroutine related_factory: called CC=1 SCAR=0.0
Pod documented
250 1 my ($class, $factory_class, $extra_fields) = @_;
251  
252 1 ▶ return sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
253 1 return $factory_class->get_fields($extra_fields);
254 1 };
255 }
256  
257 =item B<related_factory_batch>
258  
259 Same as L</related_factory>, but calls L</get_fields_batch> method.
260  
261 __PACKAGE__->fields({
262 # Add three accounts to the user
263 accounts => __PACKAGE__->related_factory_batch(3, 'My::AccountFactory')
264 });
265  
266 =cut
267  
268 1 ▶sub related_factory_batch {
Subroutine related_factory_batch: called CC=1 SCAR=0.0
Pod documented
269 1 my ($class, $n, $factory_class, $extra_fields) = @_;
270  
271 1 ▶ return sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
272 1 return $factory_class->get_fields_batch($n, $extra_fields);
273 1 };
274 }
275  
276 =back
277  
278 =head2 Factory actions
279  
280 =over
281  
282 =item B<get_fields>
283  
284 Returns fields that will be used to create object without creating something.
285  
286 =cut
287  
288 18 ▶sub get_fields {
Subroutine get_fields: called CC=2 SCAR=6.9
Pod documented
289 18 my ($class, $extra_fields) = @_;
290  
291 18 ▶ $extra_fields = {} unless defined $extra_fields;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $extra_fields 9 9 18
292  
293 my $fields = DBIx::Class::Factory::Fields->new(
294 {
295 18 %{$class->_class_data->{fields}},
296 18 %{$extra_fields},
297 },
298 $class->_class_data->{exclude}
299 18 );
300  
301 18 return $class->after_get_fields($fields->all());
302 }
303  
304 =item B<build>
305  
306 Creates L<DBIx::Class::Row> object without saving it to a database.
307  
308 =cut
309  
310 12 ▶sub build {
Subroutine build: called CC=1 SCAR=0.0
Pod documented
311 12 my ($class, $extra_fields) = @_;
312  
313 12 my $resultset = $class->_class_data->{resultset};
314  
315 12 return $class->after_build($resultset->new($class->get_fields($extra_fields)));
316 }
317  
318 =item B<create>
319  
320 Creates L<DBIx::Class::Row> object and saves it to a database.
321  
322 L<DBIx::Class::Row/discard_changes> is also called on the created object.
323  
324 =cut
325  
326 9 ▶sub create {
Subroutine create: called CC=1 SCAR=0.0
Pod documented
327 9 my ($class, $extra_fields) = @_;
328  
329 9 my $row = $class->build($extra_fields)->insert();
330 9 $row->discard_changes;
331  
332 9 return $class->after_create($row);
333 }
334  
335 =item B<get_fields_batch>
336  
337 Runs L</get_fields> C<n> times and returns arrayref of results.
338  
339 =cut
340  
341 2 ▶sub get_fields_batch {
Subroutine get_fields_batch: called CC=1 SCAR=0.0
Pod documented
342 2 my ($class, @params) = @_;
343  
344 2 return $class->_batch('get_fields', @params);
345 }
346  
347 =item B<build_batch>
348  
349 Runs L</build> C<n> times and returns arrayref of results.
350  
351 =cut
352  
353 1 ▶sub build_batch {
Subroutine build_batch: called CC=1 SCAR=0.0
Pod documented
354 1 my ($class, @params) = @_;
355  
356 1 return $class->_batch('build', @params);
357 }
358  
359 =item B<create_batch>
360  
361 Runs L</create> C<n> times and returns arrayref of results.
362  
363 =cut
364  
365 1 ▶sub create_batch {
Subroutine create_batch: called CC=1 SCAR=0.0
Pod documented
366 1 my ($class, @params) = @_;
367  
368 1 return $class->_batch('create', @params);
369 }
370  
371 =back
372  
373 =head2 Hooks
374  
375 You can define the following methods in your factory to be executed after corresponding methods.
376  
377 They take result of the corresponding methods as an argument and must return the new one.
378  
379 =over
380  
381 =item B<after_get_fields>
382 =cut
383  
384 17 ▶sub after_get_fields {
Subroutine after_get_fields: called CC=1 SCAR=0.0
Pod documented
385 17 my ($class, $fields) = @_;
386  
387 17 return $fields;
388 }
389  
390 =item B<after_build>
391 =cut
392  
393 11 ▶sub after_build {
Subroutine after_build: called CC=1 SCAR=0.0
Pod documented
394 11 my ($class, $row) = @_;
395  
396 11 return $row;
397 }
398  
399 =item B<after_create>
400  
401 sub after_create {
402 my ($class, $user_row) = @_;
403  
404 $user_row->auth();
405  
406 return $user_row;
407 }
408 =cut
409  
410 8 ▶sub after_create {
Subroutine after_create: called CC=1 SCAR=0.0
Pod documented
411 8 my ($class, $row) = @_;
412  
413 8 return $row;
414 }
415  
416 =back
417  
418 =cut
419  
420 # PRIVATE METHODS
421  
422 4 ▶sub _batch {
Subroutine _batch: called CC=2 SCAR=6.9
423 4 my ($class, $method, $n, $extra_fields) = @_;
424  
425 4 my @batch = ();
426 4 for (1 .. $n) {
427 8 push(@batch, $class->$method($extra_fields));
428 }
429  
430 4 return \@batch;
431 }
432  
433 91 ▶sub _class_data {
Subroutine _class_data: called CC=2 SCAR=6.9
434 91 my ($class) = @_;
435  
436 1 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
437  
438 91 my $var_name = $class . '::_dbix_class_factory_data';
439  
440 91 ▶ unless (defined ${$var_name}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined ${$var_name;}) 7 84 91
441 7 ${$var_name} = {fields => {}};
442 }
443  
444 91 return ${$var_name};
445 }
446  
447 =head1 DEDICATION
448  
449 This module is lovingly dedicated to my wife Catherine.
450  
451 =head1 AUTHOR
452  
453 Vadim Pushtaev, C<pushtaev@cpan.org>
454  
455 =head1 BUGS AND FEATURES
456  
457 Bugs are possible, feature requests are welcome. Write me as soon as possible.
458  
459 =head1 LICENSE AND COPYRIGHT
460  
461 Copyright 2015 Vadim Pushtaev.
462  
463 This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
464  
465 =cut
466  
467 1 1;
« Factory/Fields.pm ↑ Summary