Getting Started

After installation, to see the available options to the script use:

> --help

The script has four main commands:

  • makeproject to create your top-level testing project configuration file,

  • make to create individual testcases,

  • run to execute them, and

  • clean to delete testcase output after execution.

For detailed information, see the --help command line.

To get started, create a new directory to hold your tests. Then run the makeproject command from that directory to add a pysysproject.xml file which will hold default settings your all your tests:

> mkdir test
> cd test
> makeproject

Then to create your first test, run:

> make MyApplication_001

This will create a MyApplication_001 subdirectory with a pysystest.xml file holding metadata about the test such as its title, and a where you can add the logic to execute your test, and to validate that the results are as expected.

To run your testcases, simply execute:

> run

To give a flavour for what’s possible, here’s a system test for checking the behaviour of a server application, which shows of the most common PySys methods:

class PySysTest(pysys.basetest.BaseTest):
  """ This is a system test for a server process called MyServer. It checks that the server can be started and
    respond to basic requests. """

  def execute(self):

    # Ask PySys to allocate a free TCP port to start the server on (this allows running many tests in
    # parallel without clashes)
    serverPort = self.getNextAvailableTCPPort()

    # A common system testing task is pre-processing a file, for example to substitute in required
    # testing parameters
    self.copy(self.input+'/myserverconfig.json', self.output+'/', mappers=[
      lambda line: line.replace('@SERVER_PORT@', str(serverPort)),

    # Start the server application we're testing (as a background process)
    # self.project provides access to properties in pysysproject.xml, such as appHome which is the
    # location of the application we're testing
    server = self.startProcess(
      command   = self.project.appHome+'/my_server.%s'%('bat' if IS_WINDOWS else 'sh'),
      arguments = ['--configfile', self.output+'/myserverconfig.json', ],
      environs  = self.createEnvirons(addToExePath=os.path.dirname(PYTHON_EXE)),
      stdouterr = 'my_server', displayName = 'my_server<port %s>'%serverPort, background = True,

    # Wait for the server to start by polling for a grep regular expression. The errorExpr/process
    # arguments ensure we abort with a really informative message if the server fails to start
    self.waitForGrep('my_server.out', 'Started MyServer .*on port .*', errorExpr=[' (ERROR|FATAL) '], process=server)

    # Run a test tool (in this case, written in Python) from this test's Input/ directory.
    self.startPython([self.input+'/', f'http://localhost:{serverPort}/data/myfile.json'],

  def validate(self):
    # This method is called after execute() to perform validation of the results by checking the
    # contents of files in the test's output directory. Note that during test development you can
    # re-run validate() without waiting for a full execute() run using "pysys run --validateOnly".

    # It's good practice to check for unexpected errors and warnings so they don't go unnoticed
    self.assertGrep('my_server.out', ' (ERROR|FATAL|WARN) .*', contains=False)

    self.assertThat('message == expected',
      expected="Hello world!",


If you’re curious about any of the functionality demonstrated above, there’s lots of helpful information on these methods and further examples in the documentation:

Now take a look at pysys.basetest to begin exploring more of the powerful functionality PySys provides to help you implement your own system tests.

The sample projects under are a great starting point for learning more about PySys, and for creating your first project.