| Index: tests/compiler/dart2js/cps_ir/README.md
|
| diff --git a/tests/compiler/dart2js/cps_ir/README.md b/tests/compiler/dart2js/cps_ir/README.md
|
| new file mode 100644
|
| index 0000000000000000000000000000000000000000..1106a724011e1d2ba656ea86429dfca37f513463
|
| --- /dev/null
|
| +++ b/tests/compiler/dart2js/cps_ir/README.md
|
| @@ -0,0 +1,78 @@
|
| +# CPS IR unit tests
|
| +
|
| +This folder contains unit tests of the CPS IR. These tests run the compiler with
|
| +the cps IR and check for the output of a specific function (typically main).
|
| +
|
| +To make our lives easier, most files here are autogenerated. You should never
|
| +have to edit a file under `expected/` or any file with an `AUTOGENERATED` header
|
| +(including the `_test.dart` files).
|
| +
|
| +See instructions below to add or update tests.
|
| +
|
| +### Adding a new test
|
| +
|
| +Every test has 3 files: an input file, a test runner file, and an expectation
|
| +file. The last two are auto-generated. Here is how:
|
| +
|
| +* add a file under `input/` with a unique name, such as `foo_bar.dart`. Do not
|
| + include `_test` in the name of this file, otherwise the test framework will
|
| + think this test needs to be run directly in the vm and in a browser, that's
|
| + not our goal.
|
| +
|
| +* generate the corresponding test file, by running the `up_to_date_test.dart`
|
| + passing `update` as an argument:
|
| +
|
| +```bash
|
| +dart tests/compiler/dart2js/cps_ir/up_to_date_test.dart update
|
| +```
|
| +
|
| + This will generate a file `foo_bar_test.dart` on this folder.
|
| +
|
| +* generate the expectations of the test file by running the generated test file
|
| + with `update` as an argument:
|
| +
|
| +```bash
|
| +dart --package-root=out/ReleaseX64/packages tests/compiler/dart2js/cps_ir/foo_bar_test.dart update
|
| +```
|
| +
|
| + This will generate a file `expected/foo_bar.js` with the expected output.
|
| +
|
| +### Checking a method other than main
|
| +
|
| +By default, the test expectations will be generated to contain just the body of
|
| +the main function. If you wish to check for a different element, include a
|
| +comment at the top of the input test like this:
|
| +```dart
|
| +// Method to test: function(foo)
|
| +```
|
| +The trailing text should match the string representation of a compiler element.
|
| +
|
| +**Note**: this format will likely change in the future. We would like to have a
|
| +canonical way to refer to elements that is independent of the internal compiler
|
| +implementation, we also want a way to specify more than just one element, and a
|
| +way to specify that an element has been tree-shaken.
|
| +
|
| +### Updating a single test expectation
|
| +
|
| +To update the expectations of a test, simply regenerate it by running the test
|
| +file with `update` as an argument:
|
| +
|
| +```bash
|
| +dart --package-root=out/ReleaseX64/packages tests/compiler/dart2js/cps_ir/foo_bar_test.dart update
|
| +```
|
| +
|
| +This will override the file `expected/foo_bar.js` file with the new output.
|
| +
|
| +If a test fails because the expectations are out of date, you'll see this
|
| +suggestion in the failure message too.
|
| +
|
| +### Updating all test expectations
|
| +
|
| +For convenience, we also provide a script to update all expectations at once.
|
| +
|
| +```bash
|
| +dart --package-root=out/ReleaseX64/packages tests/compiler/dart2js/cps_ir/update_all.dart
|
| +```
|
| +
|
| +It is equivalent to update each test individually. This script can be handy when
|
| +making cross-cutting changes that affect the output of most tests.
|
|
|