azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[JS] Add some helpful documentation regarding testing to the readme.

Browse Source
This commit is contained in:
Sergej Jaskiewicz
2022-05-26 01:56:34 +03:00
committed by Space
parent 30b47b6902
commit f2111c9dc8
1 changed files with 42 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
js/ReadMe.md
+42
View File
@@ -25,3 +25,45 @@ We love contributions! The JavaScript translation could really use your help! If
* check the [contributing section](https://github.com/JetBrains/kotlin/blob/master/ReadMe.md) on general stuff like getting the code etc
* try fix one of the pending [JavaScript translation issues](https://youtrack.jetbrains.com/issues/KT?q=Subsystems:%20%7BBackend.%20JS%7D%20-Resolved)
## Testing the Kotlin/JS compiler
The following Gradle tasks are responsible for testing the Kotlin/JS compiler:
- `:js:js.tests:jsIrTest` — run JS tests against the IR backend, plus the same tests with dead code elimination (DCE) enabled.
- `:js:js.tests:jsTest` — run JS tests against the legacy backend, plus the same tests with DCE enabled.
- `:js:js.tests:quickTest` — run JS tests against the legacy backend. No DCE.
- `:js:js.tests:test` — run all JS tests, against both the legacy and the IR backends, plus the same tests with DCE enabled.
The JavaScript files generated from the test files are located in the following directories, divided by the translation mode:
- `js/js.tests/build/out` — JS files generated with the `FULL` translation mode (all modules are compiled into one big JS file)
- `js/js.tests/build/out-min` — the same as previous, but with DCE applied.
- `js/js.tests/build/out-per-module` — JS files generated with the `PER_MODULE` translation mode (each module is compiled into a separate JS file)
- `js/js.tests/build/out-per-module-min` — the same as previous, but with DCE applied.
There are multiple kinds of tests. Here are some of them:
- Box tests. Those are the tests that we are often most interested in, they are located in `js/js.translator/testData/box`.
Such tests must contain a `fn box(): String` function. If this function returns `"OK"`,
the test is considered passed, and if it returns anything else, the test is considered failed.
- Line number tests, located in `js/js.translator/testData/lineNumbers`. These are to ensure that the debug info in the generated JavaScript matches some expectation.
The expectation is written in a comment staring with `// LINES(JS):` or `// LINES(JS_IR):`.
These comments contain a list of line numbers in the test file that the compiler output is generated from.
The actual line numbers can be viewed in the generated JS file whose name ends with `-lines.js`.
- TypeScript export tests, located in `js/js.translator/testData/typescript-export`.
These test that the generated `.d.ts` (TypeScript definitions) file matches the reference `.d.ts` file.
- Also, some tests located in `compiler/testData/codegen` are shared between the JS and the JVM backends.
### Manually running the generated JS files (IR backend only)
There is a helpful tool for running and debugging JS code generated from test files right in Intellij IDEA.
Note that this will only work for files generated with the IR backend in the `FULL` translation mode,
because these files are self-sufficient and don't require any dependencies.
Just open a generated JS file located in `js/js.tests/build/out`, select
the "run IR test in node.js" run configuration in IDEA, and click on the "Run" or "Debug" icon.
The test output will be printed in the console.
Bonus: debugging is supported! You can set a breakpoint in a test file, open the generated JS file,
select the "run IR test in node.js" run configuration and click on the "Debug" icon.
The execution should pause and the breakpoint will be hit.
This works because a source map located next to the generated JS file.