travis/README.md

   1 Testing NASM
   2 ============
   3 We use [Travis CI](https://travis-ci.org/) service to execute NASM tests,
   4 which basically prepares the environment and runs our `nasm-t.py` script.
   5
   6 The script scans a testing directory for `*.json` test descriptor files
   7 and runs test by descriptor content.
   8
   9 Test engine
  10 -----------
  11 `nasm-t.py` script is a simple test engine written by Python3 language
  12 which allows either execute a single test or run them all in a sequence.
  13
  14 A typical test case processed by the following steps:
  15
  16  - a test descriptor get parsed to figure out which arguments
  17    are to be provided into the NASM command line;
  18  - invoke the NASM with arguments;
  19  - compare generated files with precompiled templates.
  20
  21 `nasm-t.py` supports the following commands:
  22
  23  - `list`: to list all test cases
  24  - `run`: to run test cases
  25  - `update`: to update precompiled templates
  26
  27 Use `nasm-t.py -h` command to get the detailed description of every option.
  28
  29 ### Test unit structure
  30 Each test consists at least of three files:
  31
  32  - a test descriptor in with `*.json` extension;
  33  - a source file to compile;
  34  - a target file to compare result with, it is assumed to have
  35    the same name as output generated during the pass file but with `*.t`
  36    extension; thus if a test generates `*.bin` file the appropriate target
  37    should have `*.bin.t` name.
  38
  39 Running tests
  40 -------------
  41 To run all currently available tests simply type the following
  42
  43 ```console
  44 python3 travis/nasm-t.py run
  45 ```
  46
  47 By default the `nasm-t.py` scans `test` subdirectory for `*.json` files and
  48 consider each as a test descriptor. Then every test is executed sequentially.
  49 If the descriptor can not be parsed it silently ignored.
  50
  51 To run a particular test provide the test name, for example
  52
  53 ```console
  54 python3 travis/nasm-t.py list
  55 ...
  56 ./travis/test/utf                Test __utf__ helpers
  57 ./travis/test/utf                Test errors in __utf__ helpers
  58 ...
  59 python3 travis/nasm-t.py run -t ./travis/test/utf
  60 ```
  61
  62 Test name duplicates in the listing above means that the descriptor
  63 carries several tests with same name but different options.
  64
  65 Test descriptor file
  66 --------------------
  67 A descriptor file should provide enough information how to run the NASM
  68 itself and which output files or streams to compare with predefined ones.
  69 We use *JSON* format with the following fields:
  70
  71  - `description`: a short description of a test which is shown to
  72    a user when tests are being listed;
  73  - `id`: descriptor internal name to use with `ref` field;
  74  - `ref`: a reference to `id` from where settings should be
  75    copied, it is convenient when say only `option` is different
  76    while the rest of the fields are the same;
  77  - `format`: NASM output format to use (`bin`,`elf` and etc);
  78  - `source`: is a source file name to compile, this file must
  79    be shipped together with descriptor file itself;
  80  - `option`: an additional option passed to the command line;
  81  - `update`: a trigger to skip updating targets when running
  82    an update procedure;
  83  - `target`: an array of targets which the test engine should
  84    check once compilation finished:
  85     - `stderr`: a file containing *stderr* stream output to check;
  86     - `stdout`: a file containing *stdout* stream output to check;
  87     - `output`: a file containing compiled result to check, in other
  88       words it is a name passed as `-o` option to the compiler;
  89  - `error`: an error handler, can be either *over* to ignore any
  90    error happened, or *expected* to make sure the test is failing.
  91
  92 ### Examples
  93 A simple test where no additional options are used, simply compile
  94 `absolute.asm` file with `bin` format for output, then compare
  95 produced `absolute.bin` file with precompiled `absolute.bin.t`.
  96
  97 ```json
  98 {
  99         "description": "Check absolute addressing",
 100         "format": "bin",
 101         "source": "absolute.asm",
 102         "target": [
 103                 { "output": "absolute.bin" }
 104         ]
 105 }
 106 ```
 107
 108 Note the `output` target is named as *absolute.bin* where *absolute.bin.t*
 109 should be already precompiled (we will talk about it in `update` action)
 110 and present on disk.
 111
 112 A slightly complex example: compile one source file with different optimization
 113 options and all results must be the same. To not write three descriptors
 114 we assign `id` to the first one and use `ref` term to copy settings.
 115 Also, it is expected that `stderr` stream will not be empty but carry some
 116 warnings to compare.
 117
 118 ```json
 119 [
 120         {
 121                 "description": "Check 64-bit addressing (-Ox)",
 122                 "id": "addr64x",
 123                 "format": "bin",
 124                 "source": "addr64x.asm",
 125                 "option": "-Ox",
 126                 "target": [
 127                         { "output": "addr64x.bin" },
 128                         { "stderr": "addr64x.stderr" }
 129                 ]
 130         },
 131         {
 132                 "description": "Check 64-bit addressing (-O1)",
 133                 "ref": "addr64x",
 134                 "option": "-O1",
 135                 "update": "false"
 136         },
 137         {
 138                 "description": "Check 64-bit addressing (-O0)",
 139                 "ref": "addr64x",
 140                 "option": "-O0",
 141                 "update": "false"
 142         }
 143 ]
 144 ```
 145
 146 Updating tests
 147 --------------
 148 If during development some of the targets are expected to change
 149 the tests will start to fail so the should be updated. Thus new
 150 precompiled results will be treated as templates to compare with.
 151
 152 To update all tests in one pass run
 153
 154 ```console
 155 python3 travis/nasm-t.py update
 156 ...
 157 === Updating ./travis/test/xcrypt ===
 158         Processing ./travis/test/xcrypt
 159         Executing ./nasm -f bin -o ./travis/test/xcrypt.bin ./travis/test/xcrypt.asm
 160         Moving ./travis/test/xcrypt.bin to ./travis/test/xcrypt.bin.t
 161 === Test ./travis/test/xcrypt UPDATED ===
 162 ...
 163 ```
 164
 165 and commit the results. To update a particular test provide its name
 166 with `-t` option.