hphp/test/README.md

   1 # Suites
   2
   3 Tests are grouped into "suites". They are just directories. Suites can have
   4 subdirectories if you want to group them even more. Running a suite will run
   5 all sub-suites.
   6
   7 * quick - High quality high signal tests. No duplicated logic. If you aren't
   8   sure, your test doesn't belong here.
   9 * slow - Slower full featured tests. Grouped into sub-suites. By default put
  10   your test here.
  11 * zend/good - Passing tests from Zend's suite.
  12
  13 # Examples how to run them
  14
  15 * Quick suite with the JIT on -
  16 `test/run test/quick`
  17
  18 * Zend tests just with the interpreter in RepoAuthoritative mode -
  19 `test/run test/zend/good -m interp -r`
  20
  21 * Slow tests with the JIT in PGO mode -
  22 `test/run test/slow -m pgo`
  23
  24 * Run everything that is supposed to pass -
  25 `test/run all`
  26
  27 * Run just the slow Hack typechecker tests -
  28 `test/run --typechecker slow`
  29
  30 # File Layout
  31
  32 The format is the same as Zend's `.phpt` but instead of sections it is
  33 separate files with the section name converted to an extension. This allows
  34 you to easily run the `.php` file without first running the test suite.
  35
  36 These are the allowed extensions:
  37
  38 * `.php` - The source of the test.
  39 * `.php.expect` - The exact string expected output.
  40 * `.php.expectf` - The exact string expected output with formating characters.
  41 * `.php.hhvm.expect` - The exact string expected output. Same as `.php.expect`.
  42 * `.php.hhvm.expectf` - The exact string expected output with formating characters. Same as `.php.expectf`.
  43 * `.php.typechecker.expect` - The exact string expected output for typechecker tests.
  44 * `.php.typechecker.expectf` - The exact string expected output for typechecker tests with formatting characters.
  45 * `.php.expectregex` - A regex that matches the output.
  46 * `.php.in` - When you run the test, the input will be obtained from here.
  47 * `.php.out` - When you run the test, the output will be stored here.
  48 * `.php.opts` - Runtime options to pass to hhvm.
  49 * `.php.cli_args` - Command line arguments to the test file (e.g., `$argv` options).
  50 * `.php.serial` - The test will always be put in the serial bucket to be run sequentially with other serial tests so as to avoid any timing problems or collisions.
  51 * `.php.hphp_opts` - Options passed to hphp when generating a bytecode repo.
  52 * `.php.diff or hhas.diff` - The diff for .expect tests.
  53 * `.hhas` - HipHop Assembly.
  54 * `.php.norepo` - don't run the test in repo mode
  55 * `.php.noserver` - don't run the test in server mode
  56 * `.php.hhconfig` - A blank or syntactically valid Hack typechecker configuration file if you want the test to be able to be run in typechecker mode.
  57 * `inc.php` - Use this extension for `require` or `include` files if you are going to have a typechecker test that uses them. For now, make sure they are in the same directory as the test. They will be copied along with the core test files when the test runner is executing.
  58
  59 You must have one `.php` (or `.php.type-errors` file -- see below); if you are
  60 running tests against HHVM, you must have one and only one of `.php.expect`,
  61 `.php.hhvm.expect`, `.php.expectf`, `.php.hhvm.expectf`, or
  62 `.php.expectregex`; if you are running tests against the  typechecker, you
  63 must have one and only one of `.php.typechecker.expect` or
  64 `.php.typechecker.expectf`, and you must have a `.php.hhconfig` file as well;
  65 and the rest are optional.
  66
  67 NOTE: If you are using a `.php.type-errors` file, then all the files suffixes listed in the paragraph above will include `type-errors` (e.g., `.php.type-errors.hhvm.expectf`).
  68
  69 NOTE: You can have both a `.php.[hhvm].expect[f]` and a
  70 `.php.typechecker.expect[f]`.
  71
  72 Any suite can have a `config.hdf` file in it that will be used. If one isn't
  73 present, then the parent suite it checked recursively until we use
  74 test/config.hdf.
  75
  76 If a suite contains an `hphpd.ini` file, all of the files in the suite will be
  77 run with the `-m debug` and `--debug-config _dir_/hphpd.ini` switches added to
  78 the command line. (`_dir_` will be replaced by path of the suite directory.)
  79
  80 Name your test in a descriptive manner and when in doubt break your test into
  81 many files. You can use comments too so future engineers know if it is a real
  82 breakage or they need to change the expected output.
  83
  84 ## `.php.type-errors` Source File Suffix
  85
  86 The test runner will look for source code files with the `.php.type-errors`
  87 suffix as well as `.php` files. The use case for this type of file is create a
  88 test runner compliant source file, but to also allow the actual typechecker
  89 `hh_client` ignore the file when run on its own. For example, in our doc repo
  90 https://github.com/hhvm/user-documentation, we use these files to have a clean
  91 `hh_client` run on our examples, but still can have examples showing
  92 typechecker errors as well.
  93
  94 ## Format Characters
  95
  96 These can appear in `.expectf` or `typechecker.expectf` files.
  97
  98 | Char    | Description                                | Regex
  99 |---------|--------------------------------------------|-------
 100 | %e      | Path separator                             | \/
 101 | %s      | Any characters except newlines             | [^\r\n]+
 102 | %S      | Optionally any characters except newlines  | [^\r\n]*
 103 | %a      | Any characters                             | .+
 104 | %A      | Optionally any characters                  | .*
 105 | %w      | Optional whitespace                        | \s*
 106 | %i      | Integer with optional sign                 | [+-]?\d+
 107 | %d      | Digits                                     | \d+
 108 | %x      | Hex                                        | [0-9a-fA-F]+
 109 | %f      | Float                                      | [+-]?\.?\d+\.?\d|(?:[Ee][+-]?\d+)?
 110 | %c      | Character                                  | .
 111 | %r...%r | The ... is a regex                         | The part that is ...