Configuration

Basics

The XML Configuration contains all your test suites for your tests.

A single test suite defines where to run a subset of your tests. This means you can configure a test run for a specific Docker image and ENV variables.

The tests can then be used from either shared test directories or specific ones for your environment. You can also configure single files that contain the full tests for your use case.

<svrunit setupTime="12">

    <testsuites>

        <testsuite name="Docker Image with PHP 8.1" 
                   group="php8"
                   dockerImage="mycompany/docker-image:latest" 
                   dockerEnv="PHP_VERSION=8.1,XDEBUG_ENABLED=1">
            <directory>./shared</directory>
            <directory>./php/v8.1</directory>
        </testsuite>
        
        <testsuite name="Docker Image as Command Runner with PHP 8.0" 
                   group="php8"
                   dockerImage="mycompany/docker-image:latest" 
                   dockerEnv="PHP_VERSION=8.0,XDEBUG_ENABLED=1"
                   dockerCommandRunner="true">
            <directory>./shared</directory>
            <directory>./php/v8.0</directory>
        </testsuite>

        <testsuite name="Docker Container with PHP 7.4"
                   dockerContainer="my_running_php74">
            <directory>./shared</directory>
            <directory>./php/v7.4</directory>
        </testsuite>

        <testsuite name="Local Server Check with File">
            <directory>./shared</directory>
            <file>./my_server_spec.xml</file>
        </testsuite>
        
    </testsuites>

</svrunit>

Setup / Teardown

Every test run has a single setup and teardown phase.

If you run tests in Docker images you might want to assign a setup time in seconds. This is the time that SVRUnit will wait before starting your tests.

Make sure you plan enought time to have everything ready before your tests get started.

<svrunit setupTime="12">

    <testsuites>
          .........
    </testsuites>

</svrunit>

Test Runners

Every test suite is executed on a specific environment. Depending on what type of environment you chose (Docker, localhost, ...), a different Test Runner is being used to run the tests.

This helps you to reuse your existing tests on different types of environments.

Docker Image

If you want to create tests for your built Docker images, you can provide the following configuration. In that case SVRUnit will always start a new image before executing your tests. It will use a name with "svrunit_" prefix. Containers will be automatically removed on teardown.

You can also assign a comma separated lists of special ENV variables that you want to use when starting the image.

<testsuite name="My Docker Image, PHP 8.0" 
           dockerImage="mycompany/docker-image:latest" 
           dockerEnv="PHP_VERSION=8.0,XDEBUG_ENABLED=1">
            .....
</testsuite>

Docker Image Command Runner

You can also run tests by using your Docker image as command runner. In this case, SVRUnit will not launch a new independent container from that image and execute all tests. Instead it will use a simple "docker run" command where the commands of the tests are appended to the inline command.

The difference to the basic launch of a container is, that this option will override the built-in CMD part of the Docker image. So you can also verify this kind of usage when testing Docker images.

The configuration is almost the same as above. Just add the key "dockerCommandRunner" with TRUE.

<testsuite name="My Docker Image, PHP 8.0" 
           dockerImage="mycompany/docker-image:latest" 
           dockerEnv="PHP_VERSION=8.0,XDEBUG_ENABLED=1"
           dockerCommandRunner="true">
            .....
</testsuite>

Docker Container

If you want to start tests in a running Docker Container, provide these configuration values to let SVRUnit know where to run your tests.

<testsuite name="My running Docker Container" 
           dockerContainer="my_app">
            .....
</testsuite>

Local Tests

If you just want to test your local server, simply configure your test suite without any additional information. This will start all your tests on the executing system.

<testsuite name="My local Tests">
            .....
</testsuite>

Advanced

Groups

You can define groups for your Test Suites.

This helps you to build categories of different tests, e.g. all PHP 8.x Docker Images, or all test suites that run "Security" tests.

You can then use these groups for filters when running SVRUnit.

Just define the group you want to run, using the --group=xy argument.

<testsuite name="My Tests" group="php8">
      <directory>./shared</directory>
      <directory>./php/v8.0</directory>
</testsuite>

Placeholders

SVRUnit allows you to use placeholders for specific things. Here is a list of available placeholders.

Executable (EXEC)

Use this to define the executable that should be tested.

This is a great way to test different versions of your application with the same tests. This could be a /bin/script version of your framework, next to the phar binary. Both executables tested with the same SVRUnit tests.

You can use the placeholder (($EXEC)) within your tests.

  - name: "Test validate command"
    command: "(($EXEC)) validate"
    expected: "All translations are valid"

Now create 2 test suites with the same tests, but different executables.

<testsuite name="bin" executable="php bin/myapp">
    <directory>tests/svrunit/tests</directory>
</testsuite>

<testsuite name="phar" executable="php myapp.phar">
    <directory>tests/svrunit/tests</directory>
</testsuite>

Both of your application versions are now tested with the same test files.