.. Copyright NTESS. See COPYRIGHT file for details.

   SPDX-License-Identifier: MIT

.. _tutorial-intro-testfile:

What is a test file?
====================

A test file is a file from which test cases can be generated

For example, a YAML file may contain instructions for running multiple test cases:

.. code-block:: yaml

  tests:
  - name: test 1
    command: my-app file.inp | && echo "success"; exit 0 || echo "failed"; exit 1
  - name: test 2
    command: mpiexec -np 4 my-app file.inp && echo "success"; exit 0 || echo "failed"; exit 1

.. admonition:: ``canary`` does not generate test cases!

  * Test cases are generated by subclasses of :class:`~AbstractTestGenerator`
  * The generator is responsible for interpreting the contents of the test file and generating test cases
  * Test generators are implemented as :ref:`plugins <extending-plugins>`
  * ``canary`` ships with builtin generator plugins for ``.pyt``, ``.vvt``, and ``CTestTestfile.cmake`` test files.
