Factory.pm

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