intern-ui

  

WIP. Project is usable, but make sure to always update to the latest version.

Warnings:

Installing this package will overwrite your /tests folder.
Make sure to temporarily rename your /tests folder to ensure no files are lost.

Installation:

In your project directory, run npm install intern-ui.

In your package.json, make sure you have the following:

"scripts": {
"intern-ui": "node node_modules/intern-ui/server.js"
}

Now you can run npm run-script intern-ui. UI is accessible at localhost:9090/node_modules/intern-ui/.

If you don't want to add the script to your package.json, feel free to start the server with
just node node_modules/intern-ui/server.js.

Reserved Words / Filenames

Do not add ~@~ to your filenames (i.e. /tests/unit/your_project/someFileName~@~whichIsInvalid will error out).

The mock name is reserved for custom helpers within your /tests/unit/your_project
and /tests/functional/your_project folders. Any files within this folder will not be tested.
This is intentional, as it allows you to have /tests/unit/your_project/mock/someHelperFile.js without
it muddling your tests.

Creating Tests

$3

In order to be picked up by the UI, the following file structure must be adhered to:

/tests
/functional
/yourProjectName
all.js
yourTest.js
/unit
/yourProjectName
/mock
yourLocalHelpers.js
/yourModuleGroup
all.js
yourTest.js
all.js

Where yourProjectName may be a single library, or a full-blown
website with multiple scripts. yourModuleGroup is an organizational
sub-folder, such as "controllers", "models", etc.

The other folders within /test are mere recommendations, not requirements.

Within /yourProjectName, all javascript files _not_ in the /mock folder
will be included as a test. all.js is required to be able to run all tests
within the folder. These tests must be manually added into the dependency array.
Future versions of intern-ui will automate this process.

all.js follows the following structure:

if (typeof define === 'function') {
define([
'./yourTest',
'./yourModuleGroup/all'
], function() {});
} else {
module.exports = function() {};
}

It's simply a RequireJS Asynchronous Module Definition (AMD). The CommonJS
export is used for the UI, and _is_ required. You must manually add your
tests within the dependency array passed through to the define function.

$3

Within your /tests/unit folder, make a copy of the /tests/unit/template folder and rename
the folder to your project's name. Rename template.js to the module of code you are testing.
Within all.js, update the dependency call from ./template to whatever you renamed the file
to. You may delete the folder /nested. Now that you're set up, follow the examples to see
how to write your very own unit tests.

#### Examples

Navigate to /tests/unit/intern-ui to see commented examples on how
to create unit tests for angular.js modules.

$3

Within your /tests/functional folder, copy and rename /tests/unit/functional to
your project's name. A login example is included to get you started.

$3

Within /tests/intern.js, edit the internConfig object to change the intern's
configuration (e.g. to add your BrowserStack / SauceLabs credentials). To add
global dependencies to your tests, edit the projects and cPackages objects.

To add browsers to the UI's browser drop-down, edit /tests/environments.json.
This file _must_ be updated if using a cloud testing service other than BrowserStack.
An example file for SauceLabs will be included in the future. For now, just follow
the naming convention for SauceLabs
and naming conventions for BrowserStack
to properly add / edit browsers into environments.json.

$3

As this project completely relies on The Intern, here are
some shortcuts to the documentation there. I plan on adding enough documentation here to make
it a one-stop-shop for learning how to make tests, but these resources will always be useful:

- Writing unit tests in the Object interface
- Currently, I have only tested the Object interface when writing tests in this project. This will be updated in future versions.
- Unit tests
- Unit tests are designed to test individual modules / functions within your code base.
- Functional tests
- Functional tests are designed to automate the manual testing you do now.