<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE doc SYSTEM "doc.dtd">
<doc title="{[project]}" subtitle="Regression, Unit, &amp; Integration Testing" toc="y">
    <description>{[project]} testing configuration requirements, setup, and options.</description>

    <section id="introduction">
        <title>Introduction</title>

        <p><backrest/> uses Docker to run tests and generate documentation.  Docker's light-weight virualization provides the a good balance between proper OS emulation and performance (especially startup)</p>

        <p>A `Vagrantfile` is provided that contains the complete configuration required to run <backrest/> tests and build documentation.  If Vagrant is not suitable then the `Vagrantfile` still contains the configuration steps required to build a test system.</p>

        <admonition type="note">this is not required for normal operation of <backrest/>.</admonition>
    </section>

    <section id="testing">
        <title>Testing</title>

        <p>The easiest way to start testing <backrest/> is with the included `Vagrantfile`.</p>

        <code-block title="Build Vagrant and Logon">
cd test
vagrant up
vagrant ssh
        </code-block>

        <p>The <code>vagrant up</code> command may take some time as a number of Docker containers must also be built.  The <code>vagrant ssh</code> command automatically logs onto the VM.</p>

        <code-block title="Run All Tests">
/backrest/test/test.pl
        </code-block>

        <code-block title="Run Tests for a Specific OS">
/backrest/test/test.pl --vm=co6
        </code-block>

        <code-block title="Run Tests for a Specific OS and Module">
/backrest/test/test.pl --vm=co6 --module=backup
        </code-block>

        <code-block title="Run Tests for a Specific OS, Module, and Test">
/backrest/test/test.pl --vm=co6 --module=backup --test=full
        </code-block>

        <code-block title="Run Tests for a Specific OS, Module, Test, and Run">
/backrest/test/test.pl --vm=co6 --module=backup --test=full --run=1
        </code-block>

        <code-block title="Run Tests for a Specific OS, Module, Test, and Process Max">
/backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4
        </code-block>

        <admonition type="note">process-max is only applicable to the <id>synthetic</id> and <id>full</id> tests in the <id>backup</id> module.</admonition>

        <code-block title="Run Tests for a Specific OS, Module, Test, Process Max, and Database Version">
/backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4 --pg-version=9.4
        </code-block>

        <admonition type="note">pg-version is only applicable to the <id>full</id> test in the <id>backup</id> module.</admonition>

        <code-block title="Iterate All Possible Test Combinations">
/backrest/test/test.pl --dry-run
        </code-block>
    </section>
</doc>
