Shinpuru reference

A small and simple PHP testing tool in one file.

This reference lists everything you will stumble upon in your daily work with Shinpuru. The information is extracted out of the documentation comments of the source file and the examples are taken from the actual tests. Fell free to look around and discover new things or use the browser search (strg + f) if you are in a hurry.

If you are new to Shinpuru or look for an introduction into a specific feature you might find more useful information on the project page.

Command line arguments

Every Shinpuru test supports the following command line arguments:

-a, --autotest

This option activates autotest mode. The test will be run once and after that the current directory (and its subdirectories) will be monitored for changes. As soon as a changed file is saved the test will be run again. If you work with Ubuntu Linux a confirmation bubble will show the result of the test run. Use the --silent option to disable this. If you want Shinpuru to monitor other directories than the current one use the --monitor option to specify one or more directories you want to be monitored for changes.

-s, --silent

This option prevents Shinpuru from triggering confirmation bubbles when run in autotest mode.

-m PATH, --monitor PATH

Monitors PATH for changes. If PATH is a file this file will be monitored. If it's a directory all files in it and its subdirectories will be monitored. As soon as a monitored file changes the test will be run again. You can use this option multiple times to make Shinpuru monitor multiple paths. --monitor also enables the autotest mode so you don't need to specify --autotest once you specified --monitor. In fact --autotest is more like a shortcut for --monitor . (the dot is the current directory).

-r STATUS, --report STATUS

Makes Shinpuru print a report which lists all tests with the status STATUS. Valid states are failed (the default), passed, skipped and successful. You can specify multiple states by using multiple --report options, e.g. --report failed --report passed. This will report all failed and passed tests.

-e ENV, --environment ENV

Runs the test in the environment ENV. The code after skip_in() calls for ENV will be skipped and the code after only_in() calls for ENV will be run. This allows you to write test cases that don't run destructive tests in a production environment. You can specify multiple environments by using multiple --environment options to further fine tune what test cases should be run (e.g. on a feature by feature basis).

Exit codes

Since Shinpuru is used from the command line the exit codes are of some interest:

No test failed.
1 - 245
Exit codes in this range indicate the number of failed test. 245 is also returned if more than 245 tests failed.
Shinpuru could not be run in autotest mode because the inotify extension could not be loaded.
PHP uses this exit code to indicate that the source file could not be run, usually because of an syntax error.

You can use this for example to run a test suite as a cron job and send a notification mail only if a test failed.


Options change some details in how Shinpuru or some of its functions work. For example you can set a common base URL that is used by all HTTP request functions instead of writing it into every function call. Options can be set using the option() method and be read as properties of the test suite returned by the suite() function. These options are currently available:


This string will be prepended to any URL requested by the HTTP request functions (get(), post(), …). This will spare you the work to write the full URL at each function call. Combined with environments you can set different base URLs depending on the environment the test suite runs in. The default is an empty string.


The error level at which a test of this test suite fails. The default value is set to E_ALL, that is as soon as a test generates an error it fails. The reasoning behind this rather strict default value is that even notices (E_NOTICE level errors) often indicate errors in the code. If this value is to strict you can use this option to set it to a more permissive value (e.g. E_ALL ^ E_NOTICE).

Test suite name

This is more of a cosmetic option but with the name() function you can set the name of a test suite. The default name is the base name of the test suites file.


The basic building blocks of a Shinpuru test suite are tests which are defined with the test() function. However managing a test suite with dozens of tests can get a bit difficult if you don't have means to express any structure. Therefore Shinpuru (inspired by Shoulda) provides a way to group related tests into a "context".

A context is defined with the context() function and can contain as many tests as you want. A context can also contain other contexts allowing a hierarchical structure. If you have some code that is common to all tests in a context you can put this code into setup() and teardown() functions. These are run before each test in the context and it's child contexts.


Environments allow you to define which test (that is one test() function) should be run or skipped under which conditions. For example you can write a test suite that tests everything when run normally but skips several dangerous tests if run in the "production" environment (you don't want to reset your database in a production environment).

This can be achieved by calling skip_in() or only_in() directly at the start of a test.


test('rebuild the database', function(){
    // Code after that line will be skipped in the production environment
    // Imagine the god of destruction who rebuilds everything after he's done…

If this test suite is run in the "production" environment (with the --environment or -e command line argument) the test is marked as skipped:

$ php test_dummies/environments/skip_with_one_env.php --environment production
Running: skip_with_one_env.php
1 test skipped
No tests failed, good job!

skip_in() as well as only_in() can take an array of environments as the first parameter and a test suite can also take several environments as arguments. This way you can write very fine adjustable tests (e.g. on a feature by feature basis).

Basic assertions

With the following assertions you can cover the functionality of basic PHP code:

You can also use PHPs build in assert() but note that you can not specify a custom error message for it. In that case you need to use assert_true().

HTTP request functions

These functions make it easy to perform HTTP requests. PHPs file_get_contents() function is used so you have the full power of PHPs streams at you disposal. You can modify the behavior of every request function by specifying context options which allow you to add you own headers (e.g. for authorization), change the user agent, set SSL options, etc. In fact post(), put() and delete() are nothing more than calls to get() with some context options set.

HTTP assertions

These assertions can be used to verify several aspects of the last HTTP request. You can check the HTTP response code or phrase with assert_response() and check the content of the request body with assert_select() and assert_xpath().

Additional to the HTTP assertions you can also get the details of the last HTTP response and verify them with the other assertions:

Flow control assertions

These assertions allow you to verify some aspects of your programs control flow like checkponts and exception handling.