-
Notifications
You must be signed in to change notification settings - Fork 11
Developing Ensemble Core
Information for people interested in developing Ensemble "core", the standalone ensemble.js library that is included in any Ensemble project.
The standalone version of ensemble.js (which can be found on the Releases page) is compiled by merging all of the JavaScript files listed in the build-library.js build script.
The component files include a few external libraries (primarily Underscore), and, more importantly, the core Ensemble files in the ensemble/ subdirectory. You will likely be editing files in that directory if you're working on Ensemble core.
—Though you could also edit or improve the build process (via the Gruntfile.js and package.json), or remove or update dependencies (by editing both ensemble code and the build-library.js script).
Browse the open ensemble core issues to find something to work on here.
After you make any edits to ensemble/ files, test that you didn't break any unit tests (see instructions below). If you're ready to distribute it as a standalone file, compile it with grunt deploy (see first time setup instructions below). Note, we've explicitly prevented committing the compiled ensemble.js via .gitignore. It should instead be distributed on the Releases page.
Note these instructions haven't been tested with Windows or Linux development environments. They likely won't work perfectly if you aren't developing on macOS.
To run the unit tests, you'll need to compile the library with grunt deploy (see building ensemble.js section below). Then start an HTTP server at the root of the repository and navigate to localhost:YOUR_PORT/tests/ in your web browser. For example, if you ran the following command to start a server:
python -m SimpleHTTPServer 8080...then you could navigate to localhost:8080/tests/ to run the tests.
If all is well, you should be presented with a screen full of green passing tests! If a test does not pass, a message explaining what the test was looking for (and the value it actually saw) will be printed in red. If the unit tests crashed before completion, a red message will appear at the bottom of the page informing you that a crash has occurred.
Open the appropriate file in the tests/js directory based on the module you are writing a test for. Find the function runTests() within it to see the types of things already being tested for. If you want to add an additional test to one of these existing areas, navigate to that function. Otherwise, make a new function (giving it an appropriately descriptive name for what it is testing), and call that new function within the runRules() function.
The basic structure will consist of these three function calls:
-
test.start("MODULENAME", "PARTOFSYSTEMYOUARETESTING");-- An example MODULENAME might be RuleLibrary, and an example part of the system might be "testTimeOrderedRules." -
test.assert(ARG1, ARG2, "MESSAGE");-- Asserts that ARG1 and ARG2 are equal to each other. If they are, then the unit test passes. If they are not, then the MESSAGE will appear, colored red, when you run the unit tests. This is the heart of the unit tests, and you can have as many assert statements as you want and need between the 'start' and 'finish' function calls. -
test.finish();-- Signifies that this unit test is over and that you are ready to move on to the following one.
We use Grunt to compile the standalone library. Grunt is a Javascript task runner for automating routine tasks. (We also use it to build the authoring tool.)
If you're interested in modifying the build process, read the Grunt Getting Started page, the Ensemble Gruntfile.js, and the build-library.js script, which is invoked by the grunt deploy task to concatenate all the individual component files together. Be sure to update this document if any instructions change.
Note, NPM is installed when you install Node.js. Test if you already have them with: node -v and npm -v on a command line.
If not, download and use the installer programs (or package manager alternatives) on the Node.js website.
You may also want to ensure your NPM is up-to-date with npm update -g npm (some systems may require sudo).
See also: the Grunt Getting Started page
If you're using Grunt for the first time on this machine, open a command shell and install the Grunt command line interface (CLI) by running:
npm install -g grunt-cliYou might have to preface this with sudo (on OSX, *nix, BSD, etc) or run your command shell as Administrator (for Windows).
This will install the Grunt CLI globally, putting the grunt command in your system path, allowing it to be run from any directory, as long as you also have a local grunt install in that directory.
Now, if you aren't already there, move to this directory of the Ensemble project (where the js, jslib etc. folders live), and install Grunt locally by running:
npm install gruntThis should create a node_modules folder in this directory. You'll need to do this for every new directory that uses Grunt (e.g., if you re-clone Ensemble).
Then, install the project dependencies listed in package.json with:
npm installSee a list of your newly installed packages with npm list --depth=0.
And finally, run the following to build the standalone ensemble.js file!
grunt deployThis will generate a directory called build/ with a standalone version of ensemble.js inside. You'll be able run grunt deploy from now on in this directory, without having to repeat any of the above steps.