Bugfix/documentation samples restructuring (#32)

* Update rooibos.cat.brs Add compiled version of `rooibos.cat.brs` with proper Roku comment syntax to avoid compile errors. * Delete rooibosDist.brs Remove the `rooibosDist.brs` file to avoid compile errors when running the nonEval sample code. * Create rooibosFunctionMap.brs Add `rooibosFunctionMap.brs` to `nonEvalSample/source/tests` as this is referenced from `nonEvalSample/components/tests/NodeExampleTests.xml` and project won't compile without it. * Create a more deliberate directory structure so we can easily see which files are part of the framework and which are test specs. * Restructure the samples/Overview directory * Remove the auto generated rooibosFunctionMap.brs files from version control. Add .rooibosrc.json files for use with rooibosC preprocessor * Move some modules from deps to devDeps in package.json and add gulp as devDep * Make the gulp file deploy args configurable via command line env vars. * Ignore generated rooibosFunctionMap.brs file from version control * Update key names in .rooibosrc.json in example app * Rename the nonEvalSample directory to just example as eval is no longer supported * Formalise the directory structures and naming conventions in the example app and update the docs. * Tie up loose ends in regards to naming and directory structure. * Fix doc formatting * Fix doc formatting * Fix doc formatting * Remove old eval example app * Rename framework directory to rooibos in example app * Update the docs page to reference the new 'rooibos' directory instead of 'framework'. * Remove copy to non-existant samples/Overview directory from gulpfile * Fix some file paths in the example app * Fix a few more paths in renaming 'framework' to 'rooibos'
rokucommunity · Mar 13, 2019 · 6df6188 · 6df6188
1 parent 7482b7c
commit 6df6188
Show file tree

Hide file tree

Showing 42 changed files with 2,304 additions and 10,904 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,9 @@ dist/apps
 out/
 dist/
 
+#Rooibos generated
+rooibosFunctionMap.brs
+
 ### Eclipse project files
 
 .metadata
@@ -32,5 +35,3 @@ local.properties
 #node
 node_modules/
 frameworkTests/source/tests/rooibosDist.brs
-samples/nonEvalSample/source/tests/rooibosDist.brs
-samples/Overview/source/tests/rooibosDist.brs
diff --git a/docs/index.md b/docs/index.md
@@ -41,7 +41,7 @@ Simple, mocha-inspired, flexible, fun Brightscript test framework for ROKU apps
 
 
 ## Getting started
-Rooibos is intentionally simple to work with. You simply copy in the `rooibos.cat.brs` file, setup your config, install an npm package, and start writing tests
+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
 
 
 ### Installation
@@ -50,37 +50,66 @@ Rooibos is intentionally simple to work with. You simply copy in the `rooibos.ca
 1. Clone or download this repo
 2. Run `npm install`
 3. Run `gulp build`
-4. Copy `dist/rooibosDist.brs` to your `source/tests` folder
+4. Copy `dist/rooibosDist.brs` to a location in your `source` folder. The suggested folder structure to keep things clear is `source/tests/rooibos`.
 5. Add the following line to your main method, in your `main.brs` file It should be placed before you initialize your scenegraph screens
 
-	```
+	```sh
 	if (type(Rooibos__Init) = "Function") then Rooibos__Init()
 	```
 
-	Note - rooibos will run if it is present. *You should be filtering out your tests folder, containing rooibosDist.brs, and your tests as part of your build process*, which is the preferred mechanism to disable/enable rooibos.
+	Note - rooibos will run if it is present. *You should be filtering out your tests folder, containing rooibosDist.brs, and your tests as part of your non-test build/release process*, which is the preferred mechanism to disable/enable rooibos.
 
-6. Create a Scene named `TestsScene.xml`, in your `components` folder, which Rooibos will use when running tests. This Scene must have a function definition for the `Rooibos_CreateTestNode` method, and include the rooibos library (which mixes in the method body for `Rooibos_CreateTestNode`. `samples/Overview/` contains a reference implementation.
-7. Create `.brs` test files within your `tests` folder, which corresponds to the `testsDirectory` config setting (default is "pkg:/source/Tests"). Test files can (and are encouraged to) be stored in nested folders, to match your source/component folder hiearchy
-8. Install [RooibosC](#rooibosC) preprocessor
+6. Create a Scene named `TestsScene.xml`, in your `components` folder. Again, we'd suggest following an easy to understand structure like `components/test/rooibos`. Rooibos will use this when running tests. This Scene must have a function definition for the `Rooibos_CreateTestNode` method, and include the rooibos library (which mixes in the method body for `Rooibos_CreateTestNode`.
+7. Create a folder for your test specs. We'd suggest `source/tests/specs` to keep things simple. Write your `.brs` test files here.  
+	If you are testing RSG components you will also need to create a folder to hold the test components, such as `components/tests/specs`.
+
+	__See the example app to get a clearer understanding of the directory structures__ [Example app](../samples/example)
+	<br>
+8. Install [RooibosC](#rooibosC) preprocessor and run it.
+9. Run your tests
 
 ### RooibosC
 
-To get the best performance and test flexibility, rooibos leverages a typescript preprocessor, named [rooibosC](https://github.com/georgejecook/rooibosPreprocessor), which prepares some files which get sideloaded with your tests. Simply:
+To get the best performance and test flexibility, rooibos leverages a typescript preprocessor, named [rooibosC](https://github.com/georgejecook/rooibosPreprocessor), which prepares some files which get sideloaded with your tests. Simply: `npm install -g rooibos-preprocessor`
+
+Then call `rooibosC -h` to check the install worked and see the help menu.
+
+There are two ways to invoke RooibosC:
+
+1. Define a config file that returns a JSON object and tell RooibosC to use that via the `-c` flag:
+
+	```sh
+	rooibosC -c path/to/config.json
+	```
+
+	_To see an example config file take a look at the [Example app](../samples/example)_
+	<br>
+
+2. Use the `-t  -r -o` flags to set your paths like so:
+
+	```sh
+	rooibosC -t source/tests/specs -r ./ -o source/tests/rooibos
+	```
 
-1. `npm install -g rooibos-preprocessor`
-2. execute the following command from your ci/test run/make file/gulp script: `rooibosC p build/path/source/tests/ build/path`, where the args are pathToYourTests, pathToRootFolder. The latter is used to fix the `pkg:/locations` in rooibos's output.
+	`-t` is the _"testPath"_ where your `.brs` test specs live
+
+	`-r` is the _"rootPath"_, i.e. the path to the root of your project. This is used to fix the `pkg:/locations` in rooibos's output.
+
+	`-o` is the _"outputPath"_. This is where rooibosC will write the map file which informs rooibos about your tests.
 
 ### Configuring Rooibos
-Rooibos's configuration is controlled via a json config file. The default location for this file is `pkg:/source/Tests/testconfig.json`. If the file is not found, then it is created with default values.
+Rooibos's configuration is controlled via a json config file. The default location for this file is `pkg:/source/tests/rooibos/testconfig.json`.
+See [Example app](../samples/example)
+If the no testconfig is found a default one will be used.
 
 An example config file looks like this:
 
-```
+```json
 {
-	"logLevel": 1,
-	"failFast": false,
-	"swallowRuntimeErrors": false,
-	"showOnlyFailures": false,
+  "logLevel": 1,
+  "failFast": false,
+  "swallowRuntimeErrors": false,
+  "showOnlyFailures": false,
 }
 ```
 

diff --git a/gulpfile.ts b/gulpfile.ts
@@ -16,8 +16,9 @@ const rokuDeploy = require('roku-deploy');
 const cp = require('child_process');
 
 const args = {
-  host: '192.168.16.3',
-  password: 'aaaa',
+  host: process.env.ROKU_HOST || '192.168.16.3',
+  username: process.env.ROKU_USER || 'rokudev',
+  password: process.env.ROKU_PASSWORD || 'aaaa',
   rootDir: './',
   files: ['frameworkTests/**/*'],
   outDir: './out',
@@ -57,8 +58,7 @@ function squash() {
 
 function copyToSamples(cb) {
   fs.copyFile(fullDistPath, path.join('frameworkTests/source/tests', distFile), cb);
-  fs.copyFile(fullDistPath, path.join('samples/Overview/source/tests', distFile), cb);
-  fs.copyFile(fullDistPath, path.join('samples/nonEvalSample/source/tests', distFile), cb);
+  fs.copyFile(fullDistPath, path.join('samples/example/source/tests/rooibos', distFile), cb);
 }
 
 /**