Configuration

Demeanor use JSON for configuration and looks for the configuration files demeanor.json and demeanor.dist.json by default. A custom configuration file can be used by using the -c or --config command line options.

./vendor/bin/demeanor --config a_custom_config.json

Test Suites

The centerpiece of Demeanor’s configuration is the testsuites argument. If no suites are defined, the command line test runner will error. Similarly if testsuites isn’t a JSON object, the runner will error.

Each test suite can have it’s own bootstrap file(s) as well as define it’s own test locations.

Here’s a complete example:

{
    "testsuites": {
        "A Test Suite": {
            "type": "unit",
            "bootstrap": [
                "test/bootstrap.php"
            ],
            "directories": [
                "test/classes",
                "test/another_directory"
            ],
            "files": [
                "test/path/to/a/file.php"
            ],
            "glob": [
                "test/files/*Test.php"
            ],
            "exclude": {
                "directories": [
                    "test/classes/not_this_one"
                ]
                , "files": [
                    "test/path/to/exclude.php"
                ]
                , "glob": [
                    "test/exclude/*.php"
                ]
            }
        }
    }
}

  • type is the type of test suite. This just tells demeanor what to do with the suite itself. Valid values are unit, spec, and (eventually) story.

  • bootstrap is a list of files that will be require_once‘d before of the suites tests are run. Use these files to do any setup for the test suite.

  • directories tells demeanor to look for files in a directory. What files it looks for depends on the suite type.

    • unit test suites look for files that end in Test.php
    • spec test suites look for files that end in spec.php

  • files is a list of files that will be treated as if they contain test cases.

  • glob is a list of glob patterns that will be used to locate test files.

  • exclude is used to blacklist files from your test suite. It’s an object that looks very similar to the test suite itself. directories, files, and glob work exactly as they do in the test suite itself.

Default Test Suites

There’s a good chance you won’t want to run all your test suites all the time. For instance, acceptance tests often take a long time – they’ll test your complete system end to end.

That’s where the default-suites configuration option comes in. When defined only the test suites defined in it’s array (or string) will be run with the naked demeanor command.

default-suites may be an array.

{
    "default-suites": ["a_suite"],
    "testsuites": {
        "a_suite": {
            "type": "spec",
            "directories": [
                "test/spec"
            ]
        }
    }
}

Or it can just be a string.

{
    "default-suites": "a_suite",
    "testsuites": {
        "a_suite": {
            "type": "spec",
            "directories": [
                "test/spec"
            ]
        }
    }
}

If a suite that doesn’t exist is supplied, the demeanor CLI will fail.

{
    "default-suites": "this-will-not-work",
    "testsuites": {
        "a_suite": {
            "type": "spec",
            "directories": [
                "test/spec"
            ]
        }
    }
}

How can I run other test suites then?

Use the --testuite (or -s) command line option.

./vendor/bin/demeanor --testsuite a_suite

Or use a few of them.

./vendor/bin/demeanor -s a_suite -s another_suite

Or use the --all (or -a) option to run all test suites.

./vendor/bin/demeanor --all

Subscribers

subscribers can be defined in demeanor.json to add event subscribers to that hook in and change how the test runs work.

subscribers should be a list of class names that implement Demeanor\Event\Subscriber.

{
    "subscribers": [
        "Acme\\Example\\TestSubscriber"
    ],
    "testsuites": {
        ...
    }
}

These subscribers should have a argumentless constructor. Demeanor uses the event subscriber API itself, look in the src/Subscriber directory of the demeanor repo for examples.

Code Coverage

Demeanor’s code coverage uses a whitelist of files to generate reports. Unless coverage is defined in demeanor.json no coverage will be reported on.

coverage looks very close to a test suite.

{
    "coverage": {
        "reports": {
            "text": "coverage/coverage.txt",
            "html": "coverage/html_dir",
            "diff": "coverage/diff_dir"
        },
        "directories": [
            "src/"
        ],
        "files": [
            "path/to/a/file.php"
        ],
        "glob": [
            "files/*.php"
        ],
        "exclude": {
            "directories": [
                "src/NotThisOne"
            ],
            "files": [
                "path/to/a/file/excluded.php"
            ],
            "glob": [
                "files/nothere/*.php"
            ]
        }
    }
}
  • directories is a list of directories that will be search for all files ending with .php
  • files and glob work as described in the test suites
  • exclude can be used to leave files out of the coverage report. All of its keys (directories, files, and glob) work the same as described in the two points above.
  • reports is really the only coverage specific part of the configuration. It defines a set of coverage reports with the report type as the key and an output path as the value. Reports is optional, report options can be specified from the CLI.

If no directories, files, or glob keys are provided, Demeanor will no generate any coverage reports or may generate an empty index.html.

Please see Code Coverage for a more complete guide to report types.

Command Line Coverage Configuration

  • The --no-coverage option will completely disable collection and rendering of coverage reports.
  • --coverage-html tells Demeanor to use a the supplied directory to output a html report.
  • --coverage-text tells Demeanor use the supplied file path to write a text report.
  • --coverage-diff tells Demeanor to use the supplied directory to output a diff report.

Some examples:

# disable coverage completely
./vendor/bin/demeanor --no-coverage

# output an HTML report to the coverage directory
./vendor/bin/demeanor --coverage-html=coverage

# output a diff reprot to the coverage directory
./vendor/bin/demeanor --coverage-diff=coverage

# output a text report to the file coverage.txt
./vendor/bin/demeanor --coverage-text=coverage.txt

Filtering Test Cases

Filters allow you to include (and in some cases, exclude) certain tests. Filters require a consensus: all filters must be met for a test case to run.

  • The --filter-name option will allow only test cases that contain the provided string in their name(s).

Examples:

# run tests with `SomeTest` in their name(s)
./vendor/bin/demeanor --filter-name SomeTest

# run tests with `SomeTest` and `config` in their names
./vendor/bin/demeanor --filter-name SomeTest --filter-name config

Including and Excluding Groups

  • The --include-group will exclude all tests but those in a given group.
  • The --exclude-group will exclude any tests in a given group

Some examples:

# include a single group
./vendor/bin/demeanor --include-group aGroup

# include multiple groups
./vendor/bin/demeanor --include-group aGroup --include-group anotherGroup

# exclude a single group
./vendor/bin/demeanor --exclude-group aGroup

# exclude multiple groups
./vendor/bin/demeanor --exclude-group aGroup --exclude-group anotherGroup

Including only Certain Files and Directories

Passing paths as arguments to the demeanor command line tool will include only those paths in a run.

# include only tests in the test/unit/Config directory
./vendor/bin/demeanor test/unit/Config

# include only tests in a single file
./vendor/bin/demeanor test/unit/Config/ConsoleConfigurationTest.php

# include tests in either the directory test/unit/Config or test/unit/Spec
./vendor/bin/demeanor test/unit/Config/ test/unit/Spec/

# include tests in either the directory test/unit/Config or in the file
# test test/unit/Spec/SpecTestCaseTest.php
./vendor/bin/demeanor test/unit/Config test/unit/Spec/SpecTestCaseTest.php