tests/README.md

   1 # Regression test for the Nit project
   2
   3 ## Content of the directory
   4
   5 This directory contains small Nit programs and useful scripts to test the non regression of the nit tools.
   6
   7 ### Useful scripts
   8
   9 * `tests.sh` is the main test script used to run some specific tests.
  10 * `testall.sh` runs some tests on all engines.
  11   (No more excuse to forget to check your new tests with an obscure engine).
  12 * `testfull.sh` runs all tests on a single engine.
  13   (go and grab a coffee)
  14 * `search_test.sh` lists tests given a testname, a basename, or a `.res` file.
  15   Useful when `foo failed` but you do not know where the program `foo` is.
  16 * `search_tests_git.sh` lists tests that seem modified between 2 git revisions.
  17   Useful before committing something.
  18 * `listfull.sh` lists tests that are run by `testfull.sh`.
  19   It is used by other scripts but can be used by human to see what is tested.
  20
  21   Currently, all files in `tests/`, `lib/` and `examples/` are executed, some of `contrib/` and the main programs of `src/`.
  22   To update the list of tested files, just edit this script.
  23
  24 ### Small Nit programs
  25
  26 They are divided in categories:
  27
  28 * `base` are minimal and fundamental tests.
  29   They are small and test the fundamental language specifications.
  30 * `bench` are memory and time tests
  31 * `error` are invalid programs
  32   They test the error message and the good behavior of the tool.
  33   Nowadays, alternatives (see below) are more used to test erroneous programs.
  34 * `example` are examples
  35   Nowadays, examples are developed in the `examples/` root directory.
  36 * `test` are others tests that usually depend on standard or other libraries.
  37   Nowadays, nitunit are a better place for them.
  38 * `shootout` are benchmarks from http://shootout.alioth.debian.org/
  39
  40 ### Other stuff
  41
  42 The .gitignore contains specific artefacts produced by some tests.
  43 However, it is better to produce these artifacts in the `out` directory instead,
  44 because `out` is cleaned before running tests (so that old artefacts do not
  45 interfere with new executions of tests)
  46
  47 The `sav/` directory contains reference result files for tests (see below)
  48
  49 The `alt/` and `out/` directory are transient directories used during the tests.
  50
  51 The `zzz_tests/` directory contains tests to test the test system.
  52 Execute `./tests.ss zzz_tests/*.nit` if you want.
  53
  54 ## Running tests
  55
  56 ~~~
  57 ./tests.sh filepath.nit...
  58 ./tests.sh base_attr*.nit
  59 ~~~
  60
  61 Will execute the program filepath for all its alternative (see below) and all its arguments (see below) for the default engine (see below).
  62
  63 The output is something like
  64 ~~~
  65 => test_args: . [ok] out/test_args.res sav/test_args.res
  66 ~~~
  67
  68 where in order, there is
  69
  70 * The test description (`test_args` in the example).
  71   It is the basename of the file + information about alternatives and arguments.
  72 * The build status: `.`, `!`, or `nocc`, or `_`.
  73   They respectively mean "compilation OK", "compilation error", "compilation skipped", "compilation OK but execution skipped".
  74 * The test status (see below) where `out/*.res` is the produced result file, and `sav/*.res` is the reference result file.
  75
  76
  77 ## Test statuses
  78
  79 ### Ok
  80
  81 `[ok] out/zzz_test_ok.res sav/zzz_test_ok.res`
  82
  83 The produced result file correspond to the reference result file (according to `diff`).
  84 It is a success.
  85
  86 ### 0k, is empty
  87
  88 `[0k] out/zzz_test_0k.res is empty`
  89
  90 The produced result file is empty and no reference result file is present.
  91 It is a success.
  92
  93 If you introduced a new library, it is likely that you get this.
  94 It basically means that the module compile and does noting, and its fine.
  95
  96 ### Fail
  97
  98 `[======= fail out/zzz_test_fail.res sav/zzz_test_fail.res =======]`
  99
 100 The produced result file do not correspond to the reference result file.
 101 It is a failure.
 102
 103 Did something break? or does the reference result file need to be updated?
 104
 105 ### No sav
 106
 107 `[=== no sav ===] out/zzz_test_nosav.res is not empty`
 108
 109 The produced result file is not empty but no reference result file is present.
 110 It is a failure.
 111
 112 Did something break? or does the reference result file need to be created?
 113 If you introduced a new program, it is likely that you get this.
 114 It basically means the program compiles and produces something.
 115 Please create a new reference result file for it.
 116
 117 ### Soso
 118
 119 `[======= soso out/zzz_test_soso.res sav//zzz_test_soso.res =======]`
 120
 121 The produced result file do not correspond to the reference result file.
 122 But the difference in only in errors or warnings.
 123 It is a failure.
 124
 125 Usually, some lines in error messages changed.
 126 So just update the reference result file.
 127
 128 ### Fixme
 129
 130 `[fixme] out/zzz_test_fixme.res sav//fixme/zzz_test_fixme.res`
 131
 132 The produced result file correspond to a *fixme* reference result file.
 133 It is an expected error. So not a regression.
 134
 135 Reference result files in `sav/**/fixme/` are considered expected errors.
 136 The distinction with standard reference result files is only for final statistics.
 137
 138 ### Ok, but fixme remains
 139
 140 `[*ok*] out/zzz_test_fixme_remains.res sav//zzz_test_fixme_remains.res - but sav//fixme/zzz_test_fixme_remains.res remains!`
 141
 142 There is a fixme reference result file and a standard reference result file. But the produced result file correspond to the standard one.
 143 Usually it means that a bug was fixed. But is considered a regression until the *fixme* reference result file is removed.
 144 It is a failure.
 145
 146 ### Changed fixme
 147
 148 `[======= changed out/zzz_test_fixme_changed.res sav//fixme/zzz_test_fixme_changed.res ======]`
 149
 150 The produced result file do not correspond to the *fixme* reference result file.
 151 It is a failure, and analogous to the standard `fail`.
 152
 153 ### Todo, not yet implemented
 154
 155 `[todo] out/zzz_test_todo.res -> not yet implemented`
 156
 157 The produced result file contains a magic string, like `NOT YET IMPLEMENTED`.
 158 Those are considered the same as expected errors (like a fixme)
 159 It is a success.
 160
 161 The magic strings are listed in `todo` files in the root and `sav` directories.
 162 They are used by engines, libraries or program just print this to simplify the management of tests.
 163
 164 Magic strings are used with `grep -f`, so each line is a pattern that is searched within the res files.
 165
 166 ### Skipped
 167
 168 `[skip]`
 169
 170 The test is skipped.
 171 It is a success.
 172
 173 The `$engine.skip` files (where `$engine` is an engine name, see below) describe tests that are skipped completely on a given engine.
 174 Usually it used with then engine `niti` because tests are too long.
 175
 176 The `cc.skip` file describes tests that are analyzed but no executable is generated.
 177 Usually it is because of expected CC errors or missing C libraries.
 178
 179 The `exec.skip` file describes tests that compiled but not executed.
 180 Usually it is because the programs are interactive or run some kind of server.
 181
 182 The `$os.skip` file describes tests that are to be skipped completely on the given OS.
 183 Usually it is because of OS specific libraries.
 184
 185 The `turing.skip` file describes tests that are to be skipped completely on the Turing cluster doing continuous testing over MPI.
 186 Usually it is because of an unavailable library or a large work which would not benefit from parallelization.
 187
 188 These `*.skip` files contain a list of patterns that will be used against test names.
 189 A single substring can thus be used to skip a full family of tests.
 190
 191 ## Update reference result files
 192
 193 To update the reference result files, just create/remove/update files in the `sav/` directory.
 194
 195 HINT: for easy management, just copy-paste parts of the test status to build your command.
 196 Example `cp <copy-paste out/zzz_test_fail.res sav/zzz_test_fail.res>` to update a file.
 197
 198
 199 If a reference result file contains only `UNDEFINED`, then the produced result file is always considered successful.
 200 It is used to store system-dependant *fixme* reference result files.
 201 Once the problem is solved, the status will become `Ok but fixme remains`
 202
 203
 204 Note: `UNDEFINED` still gives a success even if the tests is uncompilable.
 205 So do not use it for standard reference result files.
 206 Use the various skipping or controls to try to produce reproducible results.
 207
 208
 209 ## Engines
 210
 211 Engines are selected with the option `--engine`.
 212
 213 ~~~
 214 ./tests.sh --engine nitce base_class_name.nit
 215 ~~~
 216
 217 Current engines are:
 218
 219 * `nitcs`, for `nitc --separate` (this is the default)
 220 * `nitce`, for `nitc --erasure`
 221 * `nitcsg`, for `nitc --separate --semi-global`
 222 * `nitcg`, for `nitc --global`
 223 * `niti`, for `nit`, the interpreter
 224 * `nitvm`, for `nit --vm`, the virtual machine
 225 * `emscripten`, for `nitc --semi-global -m emscripten` (not automatically executed by `testall.sh`)
 226
 227 Engines control:
 228
 229 * How tests are run: compiled or interpreted? which binary? what options?
 230 * Where to find the reference result files.
 231   The sav/ directory contains subdirectories per engine that are used to store specific reference result files.
 232   Specific reference result files override the generic ones.
 233
 234
 235 ## Alternatives
 236
 237 See `README_alternatives.md`
 238
 239
 240 ## Controlling the execution of program tests
 241
 242
 243 ### Arguments
 244
 245 Argument files `*.args` are used to run program tests with specific command line arguments.
 246
 247 * `foo.args` are used for the test file basenamed `foo`.
 248 * `foo_*alt*.args` are used for specific alternatives if they exists.
 249
 250 Each line of an argument file produces an additional distinct test, with its own testname and reference result files.
 251
 252
 253 The first test, with a short arrow `=>`, is the test executed without any arguments.
 254 Other tests are arguments tests and have a longer arrow `==>`.
 255 If the first test does not produce an executapel, arguments tests are not run.
 256
 257 Example:
 258
 259 ~~~
 260 $ tail zzz_test_args.args zzz_tests/zzz_test_args.nit
 261 $ ./tests.sh zzz_tests/zzz_test_args.nit
 262 $ tail out/zzz_test_args*.res
 263 ~~~
 264
 265
 266 ### Input
 267
 268 By default, stdin is read from `/dev/null.`
 269 Specific tests may need prepared inputs.
 270
 271 The `*.inputs` files are used to provide inputs during the execution of program tests.
 272
 273 * `foo.inputs` are used for the test file basenamed `foo`
 274 * `foo_*alt*_args*.args` are used for specific alternatives and/or arguments if they exists.
 275
 276 Example:
 277
 278 ~~~
 279 $ tail zzz_test_in.inputs zzz_tests/zzz_test_in.nit
 280 $ ./tests.sh zzz_tests/zzz_test_in.nit
 281 $ cat out/zzz_test_in.res
 282 ~~~
 283
 284
 285 ### Output and generated files
 286
 287 The stdout and stderr are redirected to the produced result file.
 288
 289 Sometimes, files are also produced by the programs.
 290 In order to check those files, a special path by testname is watched.
 291 Its name is `out/foo.write` where `foo` is the complete testname (with alts and args).
 292
 293 The shell variable `$WRITE` can be used in `*.args` file in order to give the correct path to the program.
 294
 295 If it exists, the content of the `$WRITE` file is appended at the end of the produced result file.
 296 If `$WRITE` is created as a directory, then the names of files in this directory is appended.
 297
 298 Example:
 299
 300 ~~~
 301 $ tail zzz_test_write.args zzz_tests/zzz_test_write.nit
 302 $ ./tests.sh zzz_tests/zzz_test_write.nit
 303 $ cat out/zzz_test_write.out
 304 ~~~
 305
 306
 307 ### Post-processing
 308
 309 Some simple post-processing can be executed after each tests associated to a line in a `.args` file.
 310
 311 In `*.args` files, semicolons can be used to introduce and separate additional shell commands.
 312
 313 ~~~
 314 $ tail zzz_test_post_proc.args zzz_tests/zzz_test_post_proc.nit
 315 $ ./tests.sh zzz_tests/zzz_test_post_proc.nit
 316 $ cat out/zzz_test_post_proc.res
 317 ~~~
 318
 319
 320 ### Environment variable
 321
 322 The environment variable `NIT_TESTING` is set to `true` during the execution of program tests.
 323 Some libraries of programs can use it to produce specific reproducible results ; or just to exit their executions.
 324
 325 ~~~
 326 $ cat zzz_tests/zzz_test_envvar.nit
 327 $ ./tests.sh zzz_tests/zzz_test_envvar.nit
 328 $ cat out/zzz_test_post_proc.res
 329 ~~~