rzzzwilson.pymlac/pyasm/asm_tests

test_harness
============

Testing **pyasm** is done by **test_harness**.

**test_harness** reads one or more test files from the **tests** directory.
A test file contains assembler code and *test comments* that define the tests
to be performed.  **test_harness** will read the PTP file generated when
assembling the test file and run the tests on the data from the PTP file.

Test File Layout
----------------

A test file is just an Imlac assembler source file with special comments that
define tests to be performed.  For example:

::

    ; test file
            org     0100
            law     1
            hlt
            end
    ;|0100 004001
    ;|0101 000000

The special test comments have **';|** in column 1.  Normal comments may also
exist in the file.  Here the test comments are:

::

    ;|0100 004001
    ;|0101 000000

which tells **test_harness** to check that the PTP file generated by the
assembler does load *004001* at address *0100*, etc.

Test comments may appear anywhere in a test file, and are executed in the order
they appear in the file.

Failing tests
-------------

Sometime we might write a test that we expect to fail.  A normal test that
succeeds produces no error output, but a failing test does.  These *expected*
failures make it harder for the user to check that all is well.

The **unittest** module allows failures that are expected to be considered as a
test pass.  We want to do the same with **test_harness**.

Tests that we expect to fail are written just the same as *normal* tests except
that we start the test comment with '**;!**'.

For example, if we want to make sure that a **BSS** generates the right number
of zero bytes we could do this:

::

    ; test operation of BSS
            org     0100
            law     1       ; 0100
            bss     3       ; 0101
            law     2       ; 0104
            end
    ;|$1   04000+1
    ;|     0
    ;|     0
    ;|     0
    ;!     0        ; tests that 0104 is NOT a zero byte
    ;|0104 04000+2  ; retest 0104 for "law 2"

test_harness Usage
==================

::

    Usage: test_harness [ -h ] [ -d <directory> ] [ -p <prefix> ]
    
    Where <prefix> is the test filename prefix of files to test,
          <directory> is a directory of test files.
    
    If <directory> is specified run tests in that directory.  If not specified
    the test directory is assumed to be './tests'.
    
    If <prefix> is specified, run tests on files in the test subdirectory with
    a filename of <prefix>* .  If <prefix> is not specified all files are tested.

The future
==========

The test comments will change to be much more flexible.  Follow the design
discussion in `issue #7 <https://github.com/rzzzwilson/pymlac/issues/7>`_.