How does it work?The script is invoked when the
window.onloadevent fires. In rough order, this is what happens:
- The script counts up how many tests are in the test suite. It doesn't rely on Mocha's internal count because Mocha allows users to selectively run portions of a test suite. When that happens, Mocha will report the total number of tests that ran as the total number of examples. E.g., if a student has one passing test in a 50-test suite and chooses to run only that test (by clicking on the 'play' symbol next to the test description in the browser), Mocha will report that the entire test suite contains one test and the student passed one test. If we simply passed this on to Learn's servers, it would erroneously trigger the Run Local Tests light to turn green for the student, suggesting that they completed the lab despite only passing a single test.
- The script builds a
resultsobject that mirrors the object sent to Ironbroker by the old, Node-based Mocha / Mocha Multi test strategy. The results object is poorly structured, containing some duplicate information and some very odd nesting, but I matched it up exactly with the old payloads for data consistency. Eventually, it would be cool to rethink the payload structure to make it easier to look at granular data on how students are interacting with our tests.
- The script invokes the test runner (Mocha) and attaches two lifecycle hooks. After each individual test runs, the script formats the test output and then sorts the test into one of three categories, pending, failures, or passes. After the last test finishes, Learn Browser adds some counting stats to the
resultsobject, creates the payload that will be transmitted to Ironbroker, and then sends it off.
InstallationTo use Learn Browser to test a new lab or code-along, add the package as a project dependency with Yarn:
yarn add learn-browser
or with NPM:
npm i --save learn-browser
UsageIn the lesson's
index.htmlfile, add the minified version of Learn Browser in a script tag:
<!DOCTYPE html> <html lang="en"> <head> <!-- *snip* --> </head> <body> <!-- *snip* --> <!-- Include Flatiron School's minified test runner to push results to Learn. --> <script src="node_modules/learn-browser/learnBrowser.min.js"></script> </body> </html>
The minified copy of Learn Browser should be the last thing loaded in
index.html. The script has some basic dependency checking built-in, but, in general, the
index.htmlfile should look like this: