diff --git a/docs/index.md b/docs/index.md index 7e70f6d2..894f4b87 100644 --- a/docs/index.md +++ b/docs/index.md @@ -41,14 +41,22 @@ Simple, mocha-inspired, flexible, fun Brightscript test framework for ROKU apps - [Code coverage](#generate-code-coverage) ## Getting started -Rooibos is intentionally simple to work with. You simply copy in the `rooibosDist.brs` file, setup your config, install an npm package, and start writing tests +Rooibos is intentionally simple to work with. Simply install the `rooibos-cli` npm package and use that to install the framework files, and run your tests. + +You can even use `rooibos-cli` from your npm-compatible build tools, such as gulp. ### Installation 1. Either: + - use the `rooibos-cli` tool (preferred way) + ``` + npm install rooibos-cli -g + rooibos cli i myProject/source/tests + ``` + - download the [latest relases's] (https://github.com/georgejecook/rooibos/releases/latest) `rooibosDist.brs` to a location in your `source` folder. The suggested folder structure to keep things clear is `source/tests/rooibos`. - clone or download this repo and copy `dist/rooibosDist.brs` to a location in your `source` folder. The suggested folder structure to keep things clear is `source/tests/rooibos`. @@ -66,14 +74,14 @@ Rooibos is intentionally simple to work with. You simply copy in the `rooibosDis __See the example app to get a clearer understanding of the directory structures__ [Example app](../samples/example)
-6. Integrate [rooibos-preprocessor](#rooibos-preprocessor) into your tool-chain. +6. Integrate [rooibos-cli](#rooibos-cli) into your tool-chain. 7. Run your tests **For an example of how to use rooibos with gulp, see the gulpfile.ts in this project, which is used to run the framework unit tests.** -### rooibos-preprocessor +### rooibos-cli -To get the best performance and test flexibility, rooibos leverages a typescript preprocessor, named [rooibos-preprocessor](https://github.com/georgejecook/rooibosPreprocessor), which prepares some files which get sideloaded with your tests. +To get the best performance and test flexibility, rooibos leverages a typescript preprocessor, named [rooibos-cli](https://github.com/georgejecook/rooibosPreprocessor), which prepares some files which get sideloaded with your tests. ### From javascript/typescript/node @@ -81,8 +89,8 @@ To get the best performance and test flexibility, rooibos leverages a typescript See `gulpfile.ts`, in this project, for a robust typescript-based gulp example demonstrating how to seamlessly integrate rooibos with gulp. However, the process is as follows: - - `npm install rooibos-preprocessor --save-dev` - - Add the following to the top of gulpfile.ts/js `import { RooibosProcessor, createProcessorConfig, ProcessorConfig } from 'rooibos-preprocessor';` + - `npm install rooibos-cli --save-dev` + - Add the following to the top of gulpfile.ts/js `import { RooibosProcessor, createProcessorConfig, ProcessorConfig } from 'rooibos-cli';` - Create a task to process your test files, such as: ``` @@ -107,7 +115,7 @@ export async function prepareTests() { For those who are not using typescript, the usage is as follows: ``` -var rooibos = require('rooibos-preprocessor'); +var rooibos = require('rooibos-cli'); gulp.task('prepareTests', ['collect'], async function() { @@ -126,18 +134,33 @@ gulp.task('prepareTests', ['collect'], async function() { ``` -#### CLI usage +#### Installing or updating the testing framework with rooibos-cli + +To install latest + + ``` + rooibos-cli i myProject/source/tests + ``` + +To install a specific release -You can also use rooibos-preprocessor from the command line, by installing it globally. i.e `npm install -g rooibos-preprocessor`. The CLI app is vcalled `rooibos` + ``` + rooibos-cli i myProject/source/tests -r 3.0.2 + ``` -Then call `rooibosC -h` to check the install worked and see the help menu. -There are two ways to invoke RooibosC: +#### Running tests with rooibos-cli -1. Define a config file that returns a JSON object and tell RooibosC to use that via the `-c` flag: +You can also use rooibos-cli from the command line, by installing it globally. i.e `npm install -g rooibos-cli`. The CLI app is vcalled `rooibos-cli` + +Then call `rooibos-cli -h` to check the install worked and see the help menu. + +There are two ways to invoke rooibos-cli: + +1. Define a config file that returns a JSON object and tell rooibos-cli to use that via the `-c` flag: ``` - rooibosC -c path/to/config.json + rooibos-cli r path/to/config.json ``` _To see an example config file take a look at the [Example app](../samples/example)_ @@ -145,17 +168,19 @@ There are two ways to invoke RooibosC: 2. Alternately, use the following flags to configure test behaviour, like so: - ```sh - rooibosC -p ./ -t source/tests ``` -### Description of rooibosC flags + rooibos-cli r -p ./ -t source/tests + ``` +### Description of rooibos-cli commands + +``` | flag | argument | Fescription | |--- |--- |:-: | | `-p` | `--projectPath` | the path to the root of your project. This is used to fix the `pkg:/locations` in rooibos's output. | | `-t` | `--testsFilePattern` | array of globs, specifying which test files (i.e. your test _.brs_ files) to include. Relative to projectPath, relative to _"projectPath"_ | -| `-o` | `--outputPath` | you can also specity the _"outputPath"_. This is where rooibosC will write the map file, and other files it needs which informs rooibos about your tests. It is relative to | +| `-o` | `--outputPath` | you can also specity the _"outputPath"_. This is where rooibos-cli will write the map file, and other files it needs which informs rooibos about your tests. It is relative to | | `-v` | `--isRecordingCodeCoverage` | indicates that we want to generate coverage | | `-s` | `--sourceFilePattern` | array of globs, specifying which files to include/exclude in code coverage. Relative to projectPath. Required if `-v` is set. | | `-f` | `--showFailuresOnly` | Show results for failed tests, if any. If none fail, then all results are shown | @@ -164,7 +189,7 @@ There are two ways to invoke RooibosC: ### Configuring Rooibos's runtime behaviour -Rooibos's configuration is controlled via the configuration passed into the `rooibos-preprocessor` via flags on the `rooibosC` command, or values in the json used to initialize `rooibosC` via the command line, or via javacript code. +Rooibos's configuration is controlled via the configuration passed into the `rooibos-cli` via flags on the `rooibos-cli` command, or values in the json used to initialize `rooibos-cli` via the command line, or via javacript code. _Deprecation warning: This behaviour is going to change - in future, these json settings will be merged with the preprocessor config._ @@ -903,7 +928,7 @@ For now, here are the complete steps: - This file should be located somewhere in your `components` folder, placing it under `components/tests` is a good idea, as you can easily exclude it from production builds. - The file must extend the node you wish to test, e.g. `extends="NetworkLayer.xml"` - You must also include an interface function definition for a function named `Rooibos_RunNodeTests`. You _must not_ implement it, it is mixed in for you automatically. - - You must import your unit test suite (e.g. `NetworkLayerTests.brs`) as well as the rooibos framework (i.e. `rooibosDist.brs`) and the rooibos map file generated by `rooibosC` (i.e. `rooibosFunctionMap.brs`) + - You must import your unit test suite (e.g. `NetworkLayerTests.brs`) as well as the rooibos framework (i.e. `rooibosDist.brs`) and the rooibos map file generated by `rooibos-cli` (i.e. `rooibosFunctionMap.brs`) 2. In your unit test suite, before the ``@TestSuite` delcaration you _must_ place a `'@SGNode` Annotation, with the name of the node that will be used to test this suite. e.g. `'@SGNode NodeExampleTests.brs ` #### Example test suite: NetworkLayerTests.brs @@ -1014,7 +1039,7 @@ end function -Rooibos is nbackward compatible with the [legacy framework](https://github.com/rokudev/unit-testing-framework/), Use the `-l --legacySupport` flag with rooibosC to use this feature. +Rooibos is nbackward compatible with the [legacy framework](https://github.com/rokudev/unit-testing-framework/), Use the `-l --legacySupport` flag with rooibos-cli to use this feature. `'@Only`, `'@Ingore`, `'@Setup`, `'@TearDown` are all supported. Only and Ignore can be applied to a whole test suite, or individual test cases. @@ -1073,11 +1098,11 @@ An example, using a json config file is : This can be done, from the command line also, with the following command: -```rooibosC -p stubProject -t source/tests/**/*.brs -v -s '**/*.brs,**/*.xml,!**/tests/**/*.*,!**/tests,!**/rLog,!**/rLog/**/*.*,!**/rLogComponents,!**/rLogComponents/**/*.*,!**/rooibosDist.brs,!**/rooibosFunctionMap.brs,!**/TestsScene.brs,!**/ThreadaUtils.brs'``` +```rooibos-cli -p stubProject -t source/tests/**/*.brs -v -s '**/*.brs,**/*.xml,!**/tests/**/*.*,!**/tests,!**/rLog,!**/rLog/**/*.*,!**/rLogComponents,!**/rLogComponents/**/*.*,!**/rooibosDist.brs,!**/rooibosFunctionMap.brs,!**/TestsScene.brs,!**/ThreadaUtils.brs'``` ### How coverage works -rooibos-preprocessor, via `rooibosC` command line tool, or the npm package will run against a root project folder, and using the `sourceFilePattern` globs your provide, will ascertain which files require coverage. +rooibos-cli, via `rooibos-cli` command line tool, or the npm package will run against a root project folder, and using the `sourceFilePattern` globs your provide, will ascertain which files require coverage. It then buils an Abstract Syntax Tree, using Sean Barag's wonderful [brs interpreter](https://github.com/sjbarag/brs), to ascertain which lines of the identified files can have their coverage tracked.