Command Reference ================= ``mcy`` provides the following commands: .. code-block:: text > mcy help Usage: mcy [--trace] init [--nosetup] mcy [--trace] reset mcy [--trace] status mcy [--trace] list [--details] [..] mcy [--trace] run [-jN] [--reset] [..] mcy [--trace] task [-v] [-k] .. mcy [--trace] source [-e ] [] mcy [--trace] lcov mcy [--trace] dash [] mcy [--trace] gui [--src ] mcy [--trace] purge All commands require the project configuration file ``config.mcy`` to be present in the current directory. mcy init [-f] [--nosetup] This command initializes the mcy database. It runs the optional setup script from the ``[setup]`` section in ``config.mcy`` first, then prepares the design using the script from the ``[script]`` section, and generates a list of mutations conforming to the settings in the ``[options]`` section. It queues all mutations to be tested when ``mcy run`` is called. The command fails if the ``database`` directory exists. Run ``mcy purge`` to delete this directory if it is present, or pass ``-f`` to force overwriting the contents. The ``--nosetup`` option skips running the setup section. In combination, ``mcy init -f --nosetup`` allows re-initializing the project without deleting the files present in ``database/setup``. This is useful when the configuration file was changed, but the setup script's output does not need to be re-generated. mcy reset This command will reset various state. If the ``size`` parameter in the section ``[options]`` of ``config.mcy`` was increased, it will create additional mutations. It will re-run the tagging logic of the ``[logic]`` section and re-tag all mutations for which results are cached in the database. It queues the mutations for which results are not available to be tested when ``mcy run`` is called. It will also delete an existing ``tasks`` directory. mcy status This command prints the status of the project. It will indicate the number of cached results and queued tests. If some results are available, it will also report the results in the format specified in the ``[report]`` section of ``config.mcy``. The same status is also printed at the end of the commands ``init``, ``reset``, and ``run``. mcy list [--details] [..] This command prints the list of selected mutations and the tags applied to them. If the optional selection argument ```` is not present, all mutations are listed. There can be multiple selection arguments, in which case mutations matching any of the IDs or tags are listed. If ``--details`` is passed, it will additionally print the mutation command and the results cached in the database. mcy run [-jN] [--reset] [..] This command executes the tests in the queue and any tests subsequently queued based on the results (for conditionally executed tests). The optional argument ``-j N`` allows up to ``N`` tasks to be executed in parallel. If ``--reset`` is passed, ``mcy reset`` will run first (potentially creating additional mutations or queueing more tasks). The optional selection argument ````, of which there can be multiple, restricts mcy to run only tests on the matching mutation(s). (Tests for which results are available will not be re-run.) mcy task [-v] [-k] .. This command runs the test ```` on the mutations matching the ID or tag ````, of which there can be multiple. The test is executed even if the result is cached in the database. If the ``-v`` flag is passed, the output of the task execution is printed to stdout instead of the file ``tasks//logfile.txt``. If ``-k`` is passed, the temporary task execution directory ``tasks/`` is not deleted when the task finishes. mcy source [-e ] [] This command reprints the source file(s) , with annotations on the left side margin for each line of code with the number of mutations tagged COVERED or UNCOVERED (the name of the tags used is hardcoded). The number of COVERED mutations is displayed as a positive number, whereas UNCOVERED mutations are shown as negative numbers, similar to what is shown in ``mcy gui``. Source files are printed from database cache, which is written when ``mcy init`` is called, so the version displayed is always the one the mutations were applied to. The optional ``-e`` parameter allows specifying the file encoding. (Python's `standard encodings `_ are supported, default is utf8.) mcy lcov This command prints coverage information in the format used by ``lcov`` and similar code coverage visualisation tools. mcy dash This command launches the dashboard server. Navigate to the address shown to access the dashboard where you can monitor the MCY status and download the mcy database for viewing with ``mcy-gui``. This is intended to be used when running MCY on a remote server or as part of CI. mcy gui Launch the graphical explorer. The mcy gui allows navigating the list of mutations by source location, mutation id, or tag, and is the easiest way to access associated information. If you have downloaded a database from the mcy dashboard, invoke it directly as ``mcy-gui ``, as the mcy wrapper script will abort if ``config.mcy`` is not present. mcy purge This command removes all files produced by MCY, i.e. it deletes the ``database`` and ``tasks`` directories. Run this command before running ``mcy init``. The optional ``--trace`` argument to ``mcy`` is used for debugging and prints all queries performed on the database during execution to stdout.