DESCRIPTION

Takes care of setting up a Test::Mojo with the Conch application pre-configured.

Includes JSON validation ability.

my $t = Test::Conch->new;
$t->get_ok('/')->status_is(200)->json_schema_is('Whatever');

CONSTANTS

METHODS

pg

Override with your own Test::PostgreSQL object if you want to use a custom database, perhaps with extra settings or loaded with additional data.

This is the attribute to copy if you want multiple Test::Conch objects to be able to talk to the same database.

fixtures

Provides access to the fixtures defined in Test::Conch::Fixtures. See “load_fixture”.

stash

After the request has been dispatched, contains the stash values.

new

Constructor. Takes the following arguments:

* pg (optional). uses this as the postgres db.
  Otherwise, an empty database is created, using the schema in sql/schema.sql.

* config (optional). adds the provided configuration data.

init_db

Sets up the database for testing, using the final schema rather than running migrations. No data is added – you must load all desired fixtures.

Note that the Test::PostgreSQL object must stay in scope for the duration of your tests. Returns the Conch::DB object as well when called in list context.

ro_schema

Returns a read-only connection to an existing Test::PostgreSQL instance (requires “init_db” to have been run first).

status_is

Wrapper around “status_is” in Test::Mojo, adding some additional checks.

0. GET requests should not have request body content
1. successful GET requests should not return 201, 202 (ideally just 200, 204)
2. successful DELETE requests should not return 201
3. 201 and most 3xx responses should have a Location header
3.1. 2xx and 4xx JSON responses should have a Link header
4. HEAD requests should not have body content
5. 200, 203, 206, 207 and most 4xx responses should have body content
6. 204, 205 and most 3xx responses should not have body content
7. 302 should not be used at all
8. 401, 403 responses should have a WWW-Authenticate header

Also, unexpected responses will dump the response payload.

location_is

Stolen from Test::Mojo’s examples. I don’t know why this isn’t just part of the interface!

location_like

As “location_is”, but takes a regular expression.

json_schema_is

Validates the JSON response of the most recent request. If given a string that looks like a URL, fetches that URL; otherwise if a string, looks up the schema in #/$defs in the JSON Schema response specification document to validate. If given a hash, uses the hash as the schema to validate.

json_cmp_deeply

Like “json_is” in Test::Mojo, but uses “cmp_deeply” in Test::Deep for the comparison instead of “is_deep” in Test::More. This allows for more flexibility in how we test various parts of the data.

stash_cmp_deeply

Test the “stash” with “cmp_deeply” in Test::Deep, with optional JSON Pointer.

load_validation_plans

Takes an array ref of structured hash refs and creates a validation plan (if it doesn’t exist, or updates an existing entry otherwise) and adds specified validation plans for each of the structured hashes.

Each hash has the structure:

{
    id          => optional, if existing row should be updated
    name        => 'Validation plan name',
    description => 'Validation plan description',
    validations => [
        'Conch::Validation::Foo',
        'Conch::Validation::Bar',
    ]
}

If a validation plan by the same id or name already exists, all associations to validations are dropped before the specified validations are added. This allows modifying the membership of the validation plans.

Returns the list of validations plan objects.

load_validation

Add data for a validator module to the database, if it does not already exist.

load_fixture

Populate the database with one or more fixtures. Returns the objects that were explicitly requested.

reload_fixture

Loads the fixture again. Will die if it already exists (you should use “load_fixture” unless you are sure it has since been deleted).

add_fixture

Add one or more fixture definition(s), and populate the database with it.

load_fixture_set

Generates a set of fixtures by name and optional arguments, then loads them into the database. See “generate_set” in Test::Conch::Fixtures for available sets.

generate_fixtures

Generate fixture definition(s) using generic data, and any necessary dependencies, and populate the database with them.

Not-nullable fields are filled in with sensible defaults, but all may be overridden.

Data may be nested to indicate proper relationships.

e.g.:

$t->generate_fixtures(
    device => {
        device_location => { rack_unit_start => 2 },    # creates a rack_layout automatically
    },
    rack_layouts => [
        { rack_unit_start => 1 },
        { rack_unit_start => 2 },    # ..making this entry redundant with the above
        { rack_unit_start => 3 },
    ],
    device_location => { rack_unit_start => 3 },        # but this will work too
);

or, to get all the defaults with no overrides:

$t->generate_fixtures('device_location');

See “_generate_definition” in Test::Conch::Fixtures for the list of recognized types.

authenticate

Authenticates a user in the current test instance. Uses default (superuser) credentials if not provided. Optionally will bail out of all tests on failure.

By default this will also set ‘user_id’ in the session (stored in $t->ua->cookie_jar, accessed internally via $c->session('user_id')), so a token is not needed on subsequent requests.

txn_local

Given a subref, execute the code inside a transaction that is rolled back at the end. Useful for testing with mutated data that should not affect other tests. The subref is called as a subtest and is invoked with the test object as well as any additional provided arguments.

email_cmp_deeply

Wrapper around “cmp_deeply” in Test::Deep to test the email(s) that were “sent”. $got should contain a hashref, or an arrayref of hashrefs, containing the headers and content of the message(s), allowing you to test any portion of these that you like using cmp_deeply constructs.

$t->email_cmp_deeply([
    {
        To => '"Foo" <foo@conch.us>',
        From => '"Admin' <admin@conch.us>',
        Subject => 'About your new account',
        body => re(qr/^An account has been created for you.*Username:\s+foo.*Email:\s+foo@conch.us\s+Password:/ms),
    },
]);

A default ‘From’ header corresponding to the main test user is added as a default to your $expected message(s) if you don’t provide one.

Remember: “Line endings in the body will normalized to CRLF.” (see “create” in Email::Simple)

email_not_sent

Tests that no email was sent as a result of the last request.

log_is

Searches the log lines emitted for the last request for one with the provided message, which can be either an exact string or anything that Test::Deep recognizes.

If you are expecting a list of message strings (sent at once to the logger), pass a listref rather than a list.

A log line at any level matches, or you can use a more specific method that matches only one specific log level:

log_debug_is

log_info_is

log_warn_is

log_error_is

log_fatal_is

log_like

Like “log_like”, but uses a regular expression to express the expected log content.

A log line at any level matches, or you can use a more specific method that matches only one specific log level:

log_debug_like

log_info_like

log_warn_like

log_error_like

log_fatal_like

logs_are

Like “log_is”, but tests for multiple messages at once.

reset_log

Clears the log history. This does not normally need to be explicitly called, since it is cleared before every request.

add_routes

Convenience method to add additional route(s) to the application, without breaking the routes that are already in a specific order.

$routes should be a Mojolicious::Routes object that holds the route(s) to be added.

do_and_wait_for_event

Sets up a Mojo::Promise to wait for a specific event name, then executes the first subref provided. When the event is received and the task subref has finished, the success subref is invoked with the argument(s) sent to the event. If the timeout is reached, the failure subref is called, or if left undefined a test failure is generated.

LICENSING

Copyright Joyent, Inc.

This Source Code Form is subject to the terms of the Mozilla Public License, v.2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://www.mozilla.org/en-US/MPL/2.0/.