Schema

ResultSet ($source, ?{%search}, ?{%conditions})

    ok ResultSet('Job'), "Yeah, some jobs in the database";
    ok ResultSet( Job => {hourly_pay=>{'>'=>100}}), "Good paying jobs available!";

Since this returns a normal DBIx::Class::ResultSet, you can just call the normal methods against it.

    ok ResultSet('Job')->search({hourly_pay=>{'>'=>100}}), "Good paying jobs available!";

This is the same as the test above.

ResultSet can also be called with a "$source, [\%search, \%condition]" signature.

fixtures_ok

coderef

Given a code reference, execute it against the currently defined schema. This is used when you need a lot of control over installing your fixtures. Example:

    fixtures_ok sub {
        my $schema = shift @_;
        my $cd_rs = $schema->resultset('CD');
        return $cd_rs->create({
            name => 'My First Album',
            track_rs => [
                {position=>1, title=>'the first song'},
                {position=>2, title=>'yet another song'},
            ],
            cd_artist_rs=> [
                {person_artist=>{person => $vanessa}},
                {person_artist=>{person => $john}},
            ],
        });

    }, 'Installed fixtures';
    

The above gets executed at runtime and if there is an error it is trapped, reported and we move on to the next test.

arrayref

Given an array reference, attempt to process it via the default fixtures loader or through the specified loader.

    fixtures_ok [
        Person => [
            ['name', 'age', 'email'],
            ['John', 40, 'john@nowehere.com'],
            ['Vincent', 15, 'vincent@home.com'],
            ['Vanessa', 35, 'vanessa@school.com'],
        ],
    ], 'Installed fixtures';
    

This is a good option to use while you are building up your fixture sets or when your sets are going to be small and not reused across lots of tests. This will get you rolling without messing around with configuration files.

fixture set name

Given a fixture name, or array reference of names, install the fixtures.

    fixtures_ok 'core';
    fixtures_ok [qw/core extra/];
    

Fixtures are installed in the order specified.

All different types can be mixed and matched in a given test file.

is_result ($result, ?$result)

is_resultset ($resultset, ?$resultset)

eq_resultset ($resultset, $resultset, ?$message)

eq_result ($resultset, $resultset, ?$message)

hri_dump ($resultset)

reset_schema

cleanup_schema

dump_settings

is_fields

Example usage for testing a result follows.

    ok my $john = Person->find('john');

    is_fields 'name', $john, ['John Napiorkowski'],
      'Found name of $john';

    is_fields [qw/name age/], $john, ['John Napiorkowski', 40],
      'Found $johns name and age';

    is_fields $john, {
        name => 'John Napiorkowski',
        age => 40,
        email => 'john@home.com'};  # Assuming $john has only the three columns listed

In the case where we need to infer the match pattern, we get the columns of the given result but remove the primary key. Please note the following would also work:

    is_fields [qw/name age/] $john, {
        name => 'John Napiorkowski',
        age => 40}, 'Still got the name and age correct';

You should choose the method that makes most sense in your tests.

Example usage for testing a resultset follows.

    is_fields 'name', Person, [
        'John',
        'Vanessa',
        'Vincent',
    ];

    is_fields ['name'], Person, [
        'John',
        'Vanessa',
        'Vincent',
    ];

    is_fields ['name','age'], Person, [
        ['John',40],
        ['Vincent',15],
        ['Vanessa',35],
    ];

    is_fields ['name','age'], Person, [
        {name=>'John', age=>40},
        {name=>'Vanessa',age=>35},
        {name=>'Vincent', age=>15},
    ];

I find the array version is most consise. Please note that the match is not ordered. If you need to test that a given Resultset is in a particular order, you will currently need to write a custom test. If you have a big need for this I'd be willing to write a test for it, or gladly accept a patch to add it.

You should examine the test cases for more examples.

is_fields_multi

    TBD: Not yet written.

Initialization Options

    use Test::DBIx::Class -config_path=>[qw(t etc config)], 'Person', 'Job';
    use Test::DBIx::Class {config_path=>[qw(t etc config)]}, 'Person', 'Job';

The following options are currently standard and always available. Depending on your storage engine (such as SQLite or MySQL) you will have other options.

config_path

These are the relative paths searched for configuration file information. See "Initialization Sources" for more.

In the case were we have both inlined and file based configurations, the inlined is merged last (that is, has highest authority to override configuration files).

When the final merging of all configurations (both anything inlined at 'use' time, and anything found in any of the specified config_paths, we do a single 'post' config_path check. This allows you to add in a configuration file from inside a configuration file. For safety and sanity you can only do this once. This feature makes it easier to globalize any additional configuration files. For example, I often store user specific settings in "~/etc/conf.*". This feature allows me to add that into my standard "t/etc/schema.*" so it's available to all my test cases.

schema_class

Required. This must be your subclass of DBIx::Class::Schema that defines your database schema.

connect_info

Required. This will accept anything you can send to "connect" in DBIx::Class. Defaults to: ['dbi:SQLite:dbname=:memory:','',''] if left blank (but see 'traits' below for more)

connect_opts

Use this to customise connect_info if you have left that blank in order to have the dsn auto-generated, but require extra attributes such as name_sep and quote_char.

deploy_opts

Use this to customise any arguments that are to be passed to "deploy" in DBIx::Class::Schema, such as add_drop_table or quote_identifiers.

default_resultset_attributes

Allows you to specify default_resultset_attributes to be set on the schema. These will be used when creating all new resultsets.

This is typically done to enable caching or turn on the software_limit flag.

fixture_path

These are a list of relative paths search for fixtures. Each item should be a directory that contains files loadable by Config::Any and suitable to be installed via one of the fixture classes.

fixture_class

Command class that installs data into the database. Must provide a method called 'install_fixtures' that accepts a perl data structure and installs it into the database. Must capture and report errors. Default value is "::Populate", which loads Test::DBIx::Class::FixtureCommand::Populate, which is a command class based on "populate" in DBIx::Class::Schema.

resultsets

Lets you add in some result source definitions to be imported at test script runtime. See "Initialization Sources" for more.

force_drop_table

When deploying the database this option allows you add a 'drop table' statement before the create ddl. Since this will return an error if you attempt to drop a table that doesn't exist, this is off by default for SQLite storage engines. You may need to enble it you you are using the following 'keep_db' option.

keep_db

By default your testing database is 'cleaned up' after you are finished. This drops all the created tables (but currently doesn't delete any related files or database users, if any). If you want to keep your testing database after all the tests are run, you can set this to true. If so, you may also need to set the previously mentioned option 'force_drop_table' to true as well, or we will attempt to create tables and populate them when they are already populated and created.

deploy_db

By default a fresh version of the schema is deployed when 'Test::DBIx::Class' is invoked. If you want to skip the schema deployment and instead connect to an already existing and populated database, set this option to false.

traits

Traits are Moose::Roles that are applied to the class managing the connection to your database. If you leave this option blank and you don't specify anything for 'connect_info' (above), we automatically load the SQLite trait (which can be reviewed at Test::DBIx::Class::SchemaManager::Trait::SQLite). This trait installs the ability to automatically discover and deploy to an in memory or a filesystem SQLite database. If you are just getting started with testing, this is probably your easiest option.

Currently there are only three traits, the SQLite trait just described (and since it get's automatically loaded you never need to load it yourself). The Test::DBIx::Class::SchemaManager::Trait::Testmysqld trait, which is built on top of Test::mysqld and allows you the ability to deploy to and run tests against a temporary instance of MySQL. For this trait MySQL and DBD::mysql needs to be installed, but MySQL does not need to be running, nor do you need to create a test database or user. The third one is the Test::DBIx::Class::SchemaManager::Trait::Testpostgresql trait, which is built on top of Test::Postgresql58 and allows you to deploy to and run tests against a temporary instance of Postgresql. For this trait Postgresql and DBD::Pg needs to be installed, but Postgresql does not need to be running, nor do you need to create a test database or user. See "TRAITS" for more.

fail_on_schema_break

Makes the test run fail when the schema can not be created. Normally the test run is skipped when the schema fails to create. A failure can be more convenient when you want to spot compilation failures.

Please note that although all initialization options can be set inlined or in a configuration file, some options can also be set via %ENV variables. %ENV settings will only apply IF there are no existing values for the option in any configuration file. As of this time we don't merge %ENV settings, they only provider overrides to the default settings. Example use (assumes you are using the default SQLite database)

    DBNAME=test.db KEEP_DB=1 prove -lv t/schema/check-person.t

After running the test there will be a new file called 'test.db' in the home directory of your distribution. You can use:

    sqlite3 test.db

to open and view the tables and their data as loaded by any fixtures or create statements. See Test::DBIx::Class::SchemaManager::Trait::SQLite for more. Note that you can specify both 'dbpath' and 'keep_db' in your configuration files if you prefer. I tried to expose a subset of configuration to %ENV that I thought the most useful. Patches and suggestions welcomed.

Initialization Sources

    $schema->resultset('Source');

Injecting methods are optional since you can also use the 'ResultSet' keyword

Imported Source keywords use Sub::Exporter so you have quite a few options for controling how the keywords are imported. For example:

    use Test::DBIx::Class 
      'Person',
      'Person::Employee' => {-as => 'Employee'},
      'Person' => {search => {age=>{'>'=>55}}, -as => 'OlderPerson'};

This would import three local keywork methods, "Person", "Employee" and "OlderPerson". For "OlderPerson", the search parameter would automatically be resolved via $resultset->search and the correct resultset returned. You may wish to preconfigure all your test result set cases in one go at the top of your test script as a way to promote reusability.

In addition to the 'search' parameter, there is also an 'exec' parameter which let's you process your resultset programatically. For example:

    'Person' => {exec => sub { shift->older_than(55) }, -as => 'OlderPerson'};

This code reference gets passed the resultset object. So you can use any method on $resultset. For example:

    'Person' => {exec => sub { shift->find('john') }, -as => 'John'}; 

    is_result John;
    is John->name, 'John Napiorkowski', "Got Correct Name";

Although since fixtures will not yet be installed, the above is probably not going to be a normally working example :)

Additionally, since you can also initialize sources via the 'resultsets' configuration option, which can be placed into your global configuration files this means you can predefine and result resultsets across all your tests. Here is an example 't/etc/schema.pl' file where I initialize pretty much everything in one file:

     {
      'schema_class' => 'Test::DBIx::Class::Example::Schema',
      'resultsets' => [
        'Person',
        'Job',
        'Person' => { '-as' => 'NotTeenager', search => {age=>{'>'=>18}}},
      ],
      'fixture_sets' => {
        'basic' => [
          'Person' => [
            [
              'name',
              'age',
              'email'
            ],
            [
              'John',
              '40',
              'john@nowehere.com'
            ],
            [
              'Vincent',
              '15',
              'vincent@home.com'
            ],
            [
              'Vanessa',
              '35',
              'vanessa@school.com'
            ]
          ]
        ]
      },
    };

In this case you can simple do "use Test::DBIx::Class" and everything will happen automatically.

In the example 't/etc/schema.pl' file, instead of (or as well as) fixture_sets you could instead define fixture_path to allow resultset data outside of the main 't/etc/schema.pl' file.

     'fixture_path' => [qw{t etc fixtures}],

Create the file './t/etc/fixtures/basic.pl' and insert

    [
      'Person' => [
        [
          'name',
          'age',
          'email'
        ],
        [
          'John',
          '40',
          'john@nowehere.com'
        ],
        [
          'Vincent',
          '15',
          'vincent@home.com'
        ],
        [
          'Vanessa',
          '35',
          'vanessa@school.com'
        ]
      ]
    ]

Additional rulesets should be included within the outermost [ ] like this.

    [
      'Person' => [
        ...
      ],
      'Job' => [
        ...
      ]
    ]

The 'basic' fixture would be used with fixtures_ok in exactly the same way as when it was embedded within schema.pl using fixture_sets.

SQLite

Testmysqld

See Test::DBIx::Class::SchemaManager::Trait::Testmysqld for more.

Testpostgresql

See Test::DBIx::Class::SchemaManager::Trait::Testpostgresql for more.