1# NAME
2
3Test::DBIx::Class - Easier test cases for your DBIx::Class applications
4
5# SYNOPSIS
6
7The following is example usage for this module. Assume you create a standard
8Perl testing script, such as "MyApp/t/schema/01-basic.t" which is run from the
9shell like "prove -l t/schema/01-basic.t" or during "make test". That test
10script could contain:
11
12 use Test::More;
13
14 use strict;
15 use warnings;
16
17 use Test::DBIx::Class {
18 schema_class => 'MyApp::Schema',
19 connect_info => ['dbi:SQLite:dbname=:memory:','',''],
20 connect_opts => { name_sep => '.', quote_char => '`', },
21 fixture_class => '::Populate',
22 }, 'Person', 'Person::Employee' => {-as => 'Employee'}, 'Job', 'Phone';
23
24 ## Your testing code below ##
25
26 ## Your testing code above ##
27
28 done_testing;
29
30Yes, it looks like a lot of boilerplate, but sensible defaults are in place
31(the above code example shows most of the existing defaults) and configuration
32data [can be loaded from a central file](#configuration-by-file). So,
33assuming you put all of your test configuration in the standard place, your
34'real life' example is going to look closer to:
35
36 use Test::More;
37
38 use strict;
39 use warnings;
40 use Test::DBIx::Class qw(:resultsets);
41
42 ## Your testing code below ##
43 ## Your testing code above ##
44
45 done_testing;
46
47Then, assuming the existence of a [DBIx::Class::Schema](https://metacpan.org/pod/DBIx::Class::Schema) subclass called,
48"MyApp::Schema" and some [DBIx::Class::ResultSource](https://metacpan.org/pod/DBIx::Class::ResultSource)s named like "Person",
49"Person::Employee", "Job" and "Phone", will automatically deploy a testing
50schema in the given database / storage (or auto deploy to an in-memory based
51[DBD::SQLite](https://metacpan.org/pod/DBD::SQLite) database), install fixtures and let you run some test cases,
52such as:
53
54 ## Your testing code below ##
55
56 fixtures_ok 'basic'
57 => 'installed the basic fixtures from configuration files';
58
59 fixtures_ok [
60 Job => [
61 [qw/name description/],
62 [Programmer => 'She who writes the code'],
63 ['Movie Star' => 'Knows nothing about the code'],
64 ],
65 ], 'Installed some custom fixtures via the Populate fixture class',
66
67
68 ok my $john = Person->find({email=>'jjnapiork@cpan.org'})
69 => 'John has entered the building!';
70
71 is_fields $john, {
72 name => 'John Napiorkowski',
73 email => 'jjnapiork@cpan.org',
74 age => 40,
75 }, 'John has the expected fields';
76
77 is_fields ['job_title'], $john->jobs, [
78 {job_title => 'programmer'},
79 {job_title => 'administrator'},
80 ],
81 is_fields 'job_title', $john->jobs,
82 [qw/programmer administrator/],
83 'Same test as above, just different compare format;
84
85
86 is_fields [qw/job_title salary/], $john->jobs, [
87 ['programmer', 100000],
88 ['administrator, 120000],
89 ], 'Got expected fields from $john->jobs';
90
91 is_fields [qw/name age/], $john, ['John Napiorkowski', 40],
92 => 'John has expected name and age';
93
94 is_fields_multi 'name', [
95 $john, ['John Napiorkowski'],
96 $vanessa, ['Vanessa Li'],
97 $vincent, ['Vincent Zhou'],
98 ] => 'All names as expected';
99
100 is_fields 'fullname',
101 ResultSet('Country')->find('USA'),
102 'United States of America',
103 'Found the USA';
104
105 is_deeply [sort Schema->sources], [qw/
106 Person Person::Employee Job Country Phone
107 /], 'Found all expected sources in the schema';
108
109 fixtures_ok my $first_album = sub {
110 my $schema = shift @_;
111 my $cd_rs = $schema->resultset('CD');
112 return $cd_rs->create({
113 name => 'My First Album',
114 track_rs => [
115 {position=>1, title=>'the first song'},
116 {position=>2, title=>'yet another song'},
117 ],
118 cd_artist_rs=> [
119 {person_artist=>{person => $vanessa}},
120 {person_artist=>{person => $john}},
121 ],
122 });
123 }, 'You can even use a code reference for custom fixtures';
124
125 ## Your testing code above ##
126
127Please see the test cases for more examples.
128
129# DESCRIPTION
130
131The goal of this distribution is to make it easier to write test cases for your
132[DBIx::Class](https://metacpan.org/pod/DBIx::Class) based applications. It does this in three ways. First, it trys
133to make it easy to deploy your Schema. This can be to your dedicated testing
134database, or a simple SQLite database. This allows you to run tests without
135interfering with your development work and having to stop and set up a testing
136database instance.
137
138Second, we allow you to load test fixtures via several different tools. Last
139we create some helper functions in your test script so that you can reduce
140repeated or boilerplate code.
141
142Overall, we attempt to reduce the amount of code you have to write before you
143can begin writing tests.
144
145# IMPORTED METHODS
146
147The following methods are automatically imported when you use this module.
148
149## Schema
150
151You probably won't need this directly in your tests unless you have some
152application logic methods in it.
153
154## ResultSet ($source, ?{%search}, ?{%conditions})
155
156Although you can import your sources as local keywords, sometimes you might
157need to get a particular resultset when you don't wish to import it globally.
158Use like
159
160 ok ResultSet('Job'), "Yeah, some jobs in the database";
161 ok ResultSet( Job => {hourly_pay=>{'>'=>100}}), "Good paying jobs available!";
162
163Since this returns a normal [DBIx::Class::ResultSet](https://metacpan.org/pod/DBIx::Class::ResultSet), you can just call the
164normal methods against it.
165
166 ok ResultSet('Job')->search({hourly_pay=>{'>'=>100}}), "Good paying jobs available!";
167
168This is the same as the test above.
169
170ResultSet can also be called with a `$source, [\%search,
171\%condition]` signature.
172
173## fixtures\_ok
174
175This is used to install and verify installation of fixtures, either inlined,
176from a fixture set in a file, or through a custom sub reference. Accept three
177argument styles:
178
179- coderef
180
181 Given a code reference, execute it against the currently defined schema. This
182 is used when you need a lot of control over installing your fixtures. Example:
183
184 fixtures_ok sub {
185 my $schema = shift @_;
186 my $cd_rs = $schema->resultset('CD');
187 return $cd_rs->create({
188 name => 'My First Album',
189 track_rs => [
190 {position=>1, title=>'the first song'},
191 {position=>2, title=>'yet another song'},
192 ],
193 cd_artist_rs=> [
194 {person_artist=>{person => $vanessa}},
195 {person_artist=>{person => $john}},
196 ],
197 });
198
199 }, 'Installed fixtures';
200
201 The above gets executed at runtime and if there is an error it is trapped,
202 reported and we move on to the next test.
203
204- arrayref
205
206 Given an array reference, attempt to process it via the default fixtures loader
207 or through the specified loader.
208
209 fixtures_ok [
210 Person => [
211 ['name', 'age', 'email'],
212 ['John', 40, 'john@nowehere.com'],
213 ['Vincent', 15, 'vincent@home.com'],
214 ['Vanessa', 35, 'vanessa@school.com'],
215 ],
216 ], 'Installed fixtures';
217
218 This is a good option to use while you are building up your fixture sets or
219 when your sets are going to be small and not reused across lots of tests. This
220 will get you rolling without messing around with configuration files.
221
222- fixture set name
223
224 Given a fixture name, or array reference of names, install the fixtures.
225
226 fixtures_ok 'core';
227 fixtures_ok [qw/core extra/];
228
229 Fixtures are installed in the order specified.
230
231All different types can be mixed and matched in a given test file.
232
233## is\_result ($result, ?$result)
234
235Quick test to make sure $result does inherit from [DBIx::Class](https://metacpan.org/pod/DBIx::Class) or that it
236inherits from a subclass of [DBIx::Class](https://metacpan.org/pod/DBIx::Class).
237
238## is\_resultset ($resultset, ?$resultset)
239
240Quick test to make sure $resultset does inherit from [DBIx::Class::ResultSet](https://metacpan.org/pod/DBIx::Class::ResultSet)
241or from a subclass of [DBIx::Class::ResultSet](https://metacpan.org/pod/DBIx::Class::ResultSet).
242
243## eq\_resultset ($resultset, $resultset, ?$message)
244
245Given two ResultSets, determine if the are equal based on class type and data.
246This is a true set equality that ignores sorting order of items inside the
247set.
248
249## eq\_result ($resultset, $resultset, ?$message)
250
251Given two row objects, make sure they are the same.
252
253## hri\_dump ($resultset)
254
255Not a test, just returns a version of the ResultSet that has its inflator set
256to [DBIx::Class::ResultClass::HashRefInflator](https://metacpan.org/pod/DBIx::Class::ResultClass::HashRefInflator), which returns a set of hashes
257and makes it easier to stop issues. This return value is suitable for dumping
258via [Data::Dump](https://metacpan.org/pod/Data::Dump), for example.
259
260## reset\_schema
261
262Wipes and reloads the schema.
263
264## cleanup\_schema
265
266Wipes schema and disconnects.
267
268## dump\_settings
269
270Returns the configuration and related settings used to initialize this testing
271module. This is mostly to help you debug trouble with configuration and to help
272the authors find and fix bugs. At some point this won't be exported by default
273so don't use it for your real tests, just to help you understand what is going
274on. You've been warned!
275
276## is\_fields
277
278A 'Swiss Army Knife' method to check your results or resultsets. Tests the
279values of a Result or ResultSet against expected via a pattern. A pattern
280is automatically created by instrospecting the fields of your ResultSet or
281Result.
282
283Example usage for testing a result follows.
284
285 ok my $john = Person->find('john');
286
287 is_fields 'name', $john, ['John Napiorkowski'],
288 'Found name of $john';
289
290 is_fields [qw/name age/], $john, ['John Napiorkowski', 40],
291 'Found $johns name and age';
292
293 is_fields $john, {
294 name => 'John Napiorkowski',
295 age => 40,
296 email => 'john@home.com'}; # Assuming $john has only the three columns listed
297
298In the case where we need to infer the match pattern, we get the columns of the
299given result but remove the primary key. Please note the following would also
300work:
301
302 is_fields [qw/name age/] $john, {
303 name => 'John Napiorkowski',
304 age => 40}, 'Still got the name and age correct';
305
306You should choose the method that makes most sense in your tests.
307
308Example usage for testing a resultset follows.
309
310 is_fields 'name', Person, [
311 'John',
312 'Vanessa',
313 'Vincent',
314 ];
315
316 is_fields ['name'], Person, [
317 'John',
318 'Vanessa',
319 'Vincent',
320 ];
321
322 is_fields ['name','age'], Person, [
323 ['John',40],
324 ['Vincent',15],
325 ['Vanessa',35],
326 ];
327
328 is_fields ['name','age'], Person, [
329 {name=>'John', age=>40},
330 {name=>'Vanessa',age=>35},
331 {name=>'Vincent', age=>15},
332 ];
333
334I find the array version is most consise. Please note that the match is not
335ordered. If you need to test that a given Resultset is in a particular order,
336you will currently need to write a custom test. If you have a big need for
337this I'd be willing to write a test for it, or gladly accept a patch to add it.
338
339You should examine the test cases for more examples.
340
341## is\_fields\_multi
342
343 TBD: Not yet written.
344
345# SETUP AND INITIALIZATION
346
347The generic usage for this would look like one of the following:
348
349 use Test::DBIx::Class \%options, @sources
350 use Test::DBIx::Class %options, @sources
351
352Where %options are key value pairs and @sources an array as specified below.
353
354## Initialization Options
355
356The only difference between the hash and hash reference version of %options
357is that the hash version requires its keys to be prepended with "-". If
358you are inlining a lot of configuration the hash reference version may look
359neater, while if you are only setting one or two options the hash version
360might be more readable. For example, the following are the same:
361
362 use Test::DBIx::Class -config_path=>[qw(t etc config)], 'Person', 'Job';
363 use Test::DBIx::Class {config_path=>[qw(t etc config)]}, 'Person', 'Job';
364
365The following options are currently standard and always available. Depending
366on your storage engine (such as SQLite or MySQL) you will have other options.
367
368- config\_path
369
370 These are the relative paths searched for configuration file information. See
371 ["Initialization Sources"](#initialization-sources) for more.
372
373 In the case were we have both inlined and file based configurations, the
374 inlined is merged last (that is, has highest authority to override configuration
375 files).
376
377 When the final merging of all configurations (both anything inlined at 'use'
378 time, and anything found in any of the specified config\_paths, we do a single
379 'post' config\_path check. This allows you to add in a configuration file from
380 inside a configuration file. For safety and sanity you can only do this once.
381 This feature makes it easier to globalize any additional configuration files.
382 For example, I often store user specific settings in "~/etc/conf.\*". This
383 feature allows me to add that into my standard "t/etc/schema.\*" so it's
384 available to all my test cases.
385
386- schema\_class
387
388 Required. This must be your subclass of [DBIx::Class::Schema](https://metacpan.org/pod/DBIx::Class::Schema) that defines
389 your database schema.
390
391- connect\_info
392
393 Required. This will accept anything you can send to ["connect" in DBIx::Class](https://metacpan.org/pod/DBIx::Class#connect).
394 Defaults to: \['dbi:SQLite:dbname=:memory:','',''\] if left blank (but see
395 'traits' below for more)
396
397- connect\_opts
398
399 Use this to customise connect\_info if you have left that blank in order to
400 have the dsn auto-generated, but require extra attributes such as name\_sep
401 and quote\_char.
402
403- deploy\_opts
404
405 Use this to customise any arguments that are to be passed to
406 ["deploy" in DBIx::Class::Schema](https://metacpan.org/pod/DBIx::Class::Schema#deploy), such as add\_drop\_table or quote\_identifiers.
407
408- fixture\_path
409
410 These are a list of relative paths search for fixtures. Each item should be
411 a directory that contains files loadable by [Config::Any](https://metacpan.org/pod/Config::Any) and suitable to
412 be installed via one of the fixture classes.
413
414- fixture\_class
415
416 Command class that installs data into the database. Must provide a method
417 called 'install\_fixtures' that accepts a perl data structure and installs
418 it into the database. Must capture and report errors. Default value is
419 "::Populate", which loads [Test::DBIx::Class::FixtureCommand::Populate](https://metacpan.org/pod/Test::DBIx::Class::FixtureCommand::Populate), which
420 is a command class based on ["populate" in DBIx::Class::Schema](https://metacpan.org/pod/DBIx::Class::Schema#populate).
421
422- resultsets
423
424 Lets you add in some result source definitions to be imported at test script
425 runtime. See ["Initialization Sources"](#initialization-sources) for more.
426
427- force\_drop\_table
428
429 When deploying the database this option allows you add a 'drop table' statement
430 before the create ddl. Since this will return an error if you attempt to drop
431 a table that doesn't exist, this is off by default for SQLite storage engines.
432 You may need to enble it you you are using the following 'keep\_db' option.
433
434- keep\_db
435
436 By default your testing database is 'cleaned up' after you are finished. This
437 drops all the created tables (but currently doesn't delete any related files
438 or database users, if any). If you want to keep your testing database after
439 all the tests are run, you can set this to true. If so, you may also need to
440 set the previously mentioned option 'force\_drop\_table' to true as well, or we
441 will attempt to create tables and populate them when they are already populated
442 and created.
443
444- deploy\_db
445
446 By default a fresh version of the schema is deployed when 'Test::DBIx::Class'
447 is invoked. If you want to skip the schema deployment and instead connect
448 to an already existing and populated database, set this option to false.
449
450- traits
451
452 Traits are [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are applied to the class managing the connection
453 to your database. If you leave this option blank and you don't specify anything
454 for 'connect\_info' (above), we automatically load the SQLite trait (which can
455 be reviewed at [Test::DBIx::Class::SchemaManager::Trait::SQLite](https://metacpan.org/pod/Test::DBIx::Class::SchemaManager::Trait::SQLite)). This trait
456 installs the ability to automatically discover and deploy to an in memory or a
457 filesystem SQLite database. If you are just getting started with testing, this
458 is probably your easiest option.
459
460 Currently there are only three traits, the SQLite trait just described (and since
461 it get's automatically loaded you never need to load it yourself). The
462 [Test::DBIx::Class::SchemaManager::Trait::Testmysqld](https://metacpan.org/pod/Test::DBIx::Class::SchemaManager::Trait::Testmysqld) trait, which is built on
463 top of [Test::mysqld](https://metacpan.org/pod/Test::mysqld) and allows you the ability to deploy to and run tests
464 against a temporary instance of MySQL. For this trait MySQL and [DBD::mysql](https://metacpan.org/pod/DBD::mysql)
465 needs to be installed, but MySQL does not need to be running, nor do you need
466 to create a test database or user. The third one is the
467 [Test::DBIx::Class::SchemaManager::Trait::Testpostgresql](https://metacpan.org/pod/Test::DBIx::Class::SchemaManager::Trait::Testpostgresql) trait, which is
468 built on top of [Test::Postgresql58](https://metacpan.org/pod/Test::Postgresql58) and allows you to deploy to and run tests
469 against a temporary instance of Postgresql. For this trait Postgresql
470 and [DBD::Pg](https://metacpan.org/pod/DBD::Pg) needs to be installed, but Postgresql does not need to be
471 running, nor do you need to create a test database or user.
472 See ["TRAITS"](#traits) for more.
473
474- fail\_on\_schema\_break
475
476 Makes the test run fail when the schema can not be created. Normally the
477 test run is skipped when the schema fails to create. A failure can be more
478 convenient when you want to spot compilation failures.
479
480Please note that although all initialization options can be set inlined or in
481a configuration file, some options can also be set via %ENV variables. %ENV
482settings will only apply IF there are no existing values for the option in any
483configuration file. As of this time we don't merge %ENV settings, they only
484provider overrides to the default settings. Example use (assumes you are
485using the default SQLite database)
486
487 DBNAME=test.db KEEP_DB=1 prove -lv t/schema/check-person.t
488
489After running the test there will be a new file called 'test.db' in the home
490directory of your distribution. You can use:
491
492 sqlite3 test.db
493
494to open and view the tables and their data as loaded by any fixtures or create
495statements. See [Test::DBIx::Class::SchemaManager::Trait::SQLite](https://metacpan.org/pod/Test::DBIx::Class::SchemaManager::Trait::SQLite) for more.
496Note that you can specify both 'dbpath' and 'keep\_db' in your configuration
497files if you prefer. I tried to expose a subset of configuration to %ENV that
498I thought the most useful. Patches and suggestions welcomed.
499
500## Initialization Sources
501
502The @sources are a list of result sources that you want helper methods injected
503into your test script namespace. This is the 'Source' part of:
504
505 $schema->resultset('Source');
506
507Injecting methods are optional since you can also use the 'ResultSet' keyword
508
509Imported Source keywords use [Sub::Exporter](https://metacpan.org/pod/Sub::Exporter) so you have quite a few options
510for controling how the keywords are imported. For example:
511
512 use Test::DBIx::Class
513 'Person',
514 'Person::Employee' => {-as => 'Employee'},
515 'Person' => {search => {age=>{'>'=>55}}, -as => 'OlderPerson'};
516
517This would import three local keywork methods, "Person", "Employee" and
518"OlderPerson". For "OlderPerson", the search parameter would automatically be
519resolved via $resultset->search and the correct resultset returned. You may
520wish to preconfigure all your test result set cases in one go at the top of
521your test script as a way to promote reusability.
522
523In addition to the 'search' parameter, there is also an 'exec' parameter
524which let's you process your resultset programatically. For example:
525
526 'Person' => {exec => sub { shift->older_than(55) }, -as => 'OlderPerson'};
527
528This code reference gets passed the resultset object. So you can use any
529method on $resultset. For example:
530
531 'Person' => {exec => sub { shift->find('john') }, -as => 'John'};
532
533 is_result John;
534 is John->name, 'John Napiorkowski', "Got Correct Name";
535
536Although since fixtures will not yet be installed, the above is probably not
537going to be a normally working example :)
538
539Additionally, since you can also initialize sources via the 'resultsets'
540configuration option, which can be placed into your global configuration files
541this means you can predefine and result resultsets across all your tests. Here
542is an example 't/etc/schema.pl' file where I initialize pretty much everything
543in one file:
544
545 {
546 'schema_class' => 'Test::DBIx::Class::Example::Schema',
547 'resultsets' => [
548 'Person',
549 'Job',
550 'Person' => { '-as' => 'NotTeenager', search => {age=>{'>'=>18}}},
551 ],
552 'fixture_sets' => {
553 'basic' => [
554 'Person' => [
555 [
556 'name',
557 'age',
558 'email'
559 ],
560 [
561 'John',
562 '40',
563 'john@nowehere.com'
564 ],
565 [
566 'Vincent',
567 '15',
568 'vincent@home.com'
569 ],
570 [
571 'Vanessa',
572 '35',
573 'vanessa@school.com'
574 ]
575 ]
576 ]
577 },
578 };
579
580In this case you can simple do "use Test::DBIx::Class" and everything will
581happen automatically.
582
583In the example 't/etc/schema.pl' file, instead of (or as well as) fixture\_sets
584you could instead define fixture\_path to allow resultset data outside of the
585main 't/etc/schema.pl' file.
586
587 'fixture_path' => [qw{t etc fixtures}],
588
589Create the file './t/etc/fixtures/basic.pl' and insert
590
591 [
592 'Person' => [
593 [
594 'name',
595 'age',
596 'email'
597 ],
598 [
599 'John',
600 '40',
601 'john@nowehere.com'
602 ],
603 [
604 'Vincent',
605 '15',
606 'vincent@home.com'
607 ],
608 [
609 'Vanessa',
610 '35',
611 'vanessa@school.com'
612 ]
613 ]
614 ]
615
616Additional rulesets should be included within the outermost \[ \] like
617this.
618
619 [
620 'Person' => [
621 ...
622 ],
623 'Job' => [
624 ...
625 ]
626 ]
627
628The 'basic' fixture would be used with fixtures\_ok in exactly the same way
629as when it was embedded within schema.pl using fixture\_sets.
630
631# CONFIGURATION BY FILE
632
633By default, we try to load configuration files from the following locations:
634
635 ./t/etc/schema.*
636 ./t/etc/[test file path].*
637
638Where "." is the root of the distribution and "\*" is any of the configuration
639file types supported by [Config::Any](https://metacpan.org/pod/Config::Any) configuration loader. This allows you
640to store configuration in the format of your choice.
641
642"\[test file path\]" is the relative path part under the "t" directory of the
643calling test script. For example, if your test script is "t/mytest.t" we add
644the path "./t/etc/mytest.\*" to the path.
645
646Additionally, we do a merge using [Hash::Merge](https://metacpan.org/pod/Hash::Merge) of all the matching found
647configurations. This allows you to do 'cascading' configuration from the most
648global to the most local settings.
649
650You can override this search path with the "-config\_path" key in options. For
651example, the following searches for "t/etc/myconfig.\*" (or whatever is the
652correct directory separator for your operating system):
653
654 use Test::DBIx::Class -config_path => [qw/t etc myconfig/];
655
656Relative paths are rooted to the distribution home directory (ie, the one that
657contains your 'lib' and 't' directories). Full paths are searched without
658modification.
659
660You can specify multiple paths. The following would search for both "schema.\*"
661and "share/schema".
662
663 use Test::DBIx::Class -config_path => [[qw/share schema/], [qw/schema/]];
664
665Lastly, you can use the special symbol "+" to indicate that your custom path
666adds to or prepends to the default search path. Since as indicated we merge
667all the configurations found, this means it's easy to create user level
668configuration settings mixed with global settings, as in:
669
670 use Test::DBIx::Class
671 -config_path => [
672 [qw(/ etc myapp test-schema)],
673 '+',
674 [qw(~ etc test-schema)],
675 ];
676
677Which would search and combine "/etc/myapp/test-schema.\*", "./t/etc/schema.\*",
678"./etc/\[test script name\].\*" and "~/etc/test-schema.\*". This would let you set
679up server level global settings, distribution level settings and finally user
680level settings.
681
682Please note that in all the examples given, paths are written as an array
683reference of path parts, rather than as a string with delimiters (i.e. we do
684\[qw(t etc)\] rather than "t/etc"). This is not required but recommended. All
685arguments, either string or array references, are passed to [Path::Class](https://metacpan.org/pod/Path::Class) so
686that we can maintain better compatibility with non unix filesystems. If you
687are writing for CPAN, please consider our non Unix filesystem friends :)
688
689Lastly, there is an %ENV variable named 'TEST\_DBIC\_CONFIG\_SUFFIX' which, if it
690exists, can be used to further customize your configuration path. If we find
691that $ENV{TEST\_DBIC\_CONFIG\_SUFFIX} is set, we attempt to find configuration files
692with the suffix appended to each of the items in the config\_path option. So, if
693you have:
694
695 use Test::DBIx::Class
696 -config_path => [
697 [qw(/ etc myapp test-schema)],
698 '+',
699 [qw(~ etc test-schema)],
700 ];
701
702
703and $ENV{TEST\_DBIC\_CONFIG\_SUFFIX} = '-mysql' we will check the following paths
704for valid and loading configuration files (assuming unix filesystem conventions)
705
706 /etc/myapp/test-schema.*
707 /etc/myapp/test-schema-mysql.*
708 ./t/etc/schema.*
709 ./t/etc/schema-mysql.*
710 ./etc/[test script name].*
711 ./etc/[test script name]-mysql.*
712 ~/etc/test-schema.*
713 ~/etc/test-schema-mysql.*
714
715
716Each path is tested in turn and all found configurations are merged from top to
717bottom. This feature is intended to make it easier to switch between sets of
718configuration files when developing. For example, you can create a test suite
719intended for a MySQL database, but allow a failback to the default Sqlite should
720certain enviroment variables not exist.
721
722# CONFIGURATION SUBSTITUTIONS
723
724Similarly to [Catalyst::Plugin::ConfigLoader](https://metacpan.org/pod/Catalyst::Plugin::ConfigLoader), there are some macro style
725keyword inflators available for use within your configuration files. This
726allows you to set the value of a configuration setting from an external source,
727such as from %ENV. There are currently two macro substitutions:
728
729- ENV
730
731 Given a value in %ENV, substitute the keyword for the value of the named
732 substitution. For example, if you had:
733
734 email = 'vanessa__ENV(TEST_DBIC_LAST_NAME)__@school.com'
735
736 in your configuration filem your could:
737
738 TEST_DBIC_LAST_NAME=_lee prove -lv t/schema-your-test.t
739
740 and then:
741
742 is $vanessa->email, 'vanessa_lee@school.com', 'Got expected email';
743
744 You might find this useful for configuring localized username and passwords
745 although personally I'd rather set that via configuration in the user home
746 directory.
747
748# TRAITS
749
750As described, a trait is a [Moose::Role](https://metacpan.org/pod/Moose::Role) that is applied to the class
751managing your database and test instance. Traits are installed by the
752'traits' configuration option, which expects an ArrayRef as its input
753(however will also normalize a scalar to an ArrayRef).
754
755Available traits are as follows.
756
757## SQLite
758
759This is the default trait which will be loaded if no other traits are installed
760and there is not 'connect\_info' in the configuration. In this case we assume
761you want us to go and create a tempory SQLite database for testing. Please see
762[Test::DBIx::Class::SchemaManager::Trait::SQLite](https://metacpan.org/pod/Test::DBIx::Class::SchemaManager::Trait::SQLite) for more.
763
764## Testmysqld
765
766If MySQL is installed on the testing machine, and [DBD::mysql](https://metacpan.org/pod/DBD::mysql), we try to auto
767create an instance of MySQL and deploy our tests to that. Similarly to the way
768the SQLite trait works, we attempt to create the database without requiring any
769other using effort or setup.
770
771See [Test::DBIx::Class::SchemaManager::Trait::Testmysqld](https://metacpan.org/pod/Test::DBIx::Class::SchemaManager::Trait::Testmysqld) for more.
772
773## Testpostgresql
774
775If Postgresql is installed on the testing machine, along with [DBD::Pg](https://metacpan.org/pod/DBD::Pg), we try
776to auto create an instance of Postgresql in a testing area and deploy our tests
777and fixtures to it.
778
779See [Test::DBIx::Class::SchemaManager::Trait::Testpostgresql](https://metacpan.org/pod/Test::DBIx::Class::SchemaManager::Trait::Testpostgresql) for more.
780
781# SEE ALSO
782
783The following modules or resources may be of interest.
784
785[DBIx::Class](https://metacpan.org/pod/DBIx::Class), [DBIx::Class::Schema::PopulateMore](https://metacpan.org/pod/DBIx::Class::Schema::PopulateMore), [DBIx::Class::Fixtures](https://metacpan.org/pod/DBIx::Class::Fixtures)
786
787# AUTHOR
788
789 John Napiorkowski C<< <jjnapiork@cpan.org> >>
790
791# CONTRIBUTORS
792
793 Tristan Pratt
794 Tomas Doran C<< <bobtfish@bobtfish.net> >>
795 Kyle Hasselbacher C<< kyleha@gmail.com >>
796 cvince
797 colinnewell
798 rbuels
799 wlk
800 yanick
801 hippich
802 lecstor
803 bphillips
804 abraxxa
805 oalders
806 felliott
807 Vadim Pushtaev C<< <pushtaev@cpan.org> >>
808 simonamor
809
810# COPYRIGHT & LICENSE
811
812Copyright 2012, John Napiorkowski `<jjnapiork@cpan.org>`
813
814This program is free software; you can redistribute it and/or modify
815it under the same terms as Perl itself.
816