Testing Guide¶

omni_test allows you to run tests from within the database.

omni_test is a templated extension

omni_test is a templated extension. This means that by installing it, its default-instantiated into omni_test but can be instantiated into any other schema:

select omni_test.instantiate([schema => 'omni_test'])

In order to use it, you need to provision a template database with your test functions and everything they need:

create database myapp_test;
update pg_database set datistemplate = true where datname = 'myapp_test';
-- provision the content

Use omni_schema.assemble_schema

One of the easiest way to provision files into this new schema is to use omni_schema.assemble_schema:

select * from 
  omni_schema.assemble_schema('dbname=myapp_test ..',
                               omni_vfs.local_fs('/path/to/tests'))

Writing tests¶

Tests are found by signature, they can be either functions or procedures.

Functions must follow this signature:

create function my_test() returns omni_test.test -- ...

What's omni_test.test type?

At this time, omni_test.test is am empty composite type and its value is ignored. It is simply used for finding tests. This may change in the future.

Procedures must follow this signature:

create procedure my_test(inout omni_test.test) -- ..

When to use procedures instead of functions?

Procedures are to be used if the test is to be non-atomic, that is, if it uses commit or rollback.

Settings¶

Test functions and procedures have optionally supplied settings, that can be set using create procedure ... set param = value (or alter ... set param value):

Setting	Description
`omni_test.transaction_isolation`	Transaction isolation level, follows `transaction_isolation` setting

Example:

create procedure tx_iso(inout test omni_test.test)
    set omni_test.transaction_isolation = serializable
    language plpgsql
as
$$
begin
    if current_setting('transaction_isolation') != 'serializable' then
        raise exception 'transaction isolation level was not set';
    end if;
end;
$$;

Running tests¶

To run tests, simply pass the name of the database to the run_tests function:

select * from omni_test.run_tests('myapp_test')

Every test function and procedure is going to be executed in a fresh copy of the myapp_test "template" database.

The results will conform to this structure:

Name	Type	Description
name	`text`	The name of the test.
description	`text`	A detailed description of the test
start_time	`timestamp`	The start time of the test.
end_time	`timestamp`	The end time of the test.
error_message	`text`	An error message, if the test failed.

Filtering tests¶

It's also possible to include only specific tests by using optional filter parameter to run_tests. It's used against function/procedure names and their comments using regular expressions.

select *
from
    omni_test.run_tests('myapp_test', filter => '^(?!.*@slow).*')

(The above will filter out tests with a @slow marker in their comment)