Building and running the app
Just Spotlight: The simplest way to get started is to run just this app, against production data. You can run the app as follows:
npm install -g grunt-cli # install grunt globally npm install grunt
Now you should be able to connect to the app at
By default, this will look at production data, but perhaps you want to connect
to a different data source. You can do that
by creating your own config file in
/config/config.development_personal.json that mimics
/config/config.development.json with a different
backdropUrl property. It'll be ignored by Git.
Full stack: if you're using our development environment then you can run all our apps in one go and use a real database for development. As a bonus, this will let you test the image fallbacks using the screenshot-as-a-service app.
First, you need to set up the Performance Platform development environment.
Once you have a machine with the required system-level dependencies, you can run the application with:
cd /var/apps/pp-puppet/development bowl performance
Tests are divided into ones that work on both client and server (
test/spec/shared), ones that are server-only (
test/spec/server) and ones that are client-only (
grunt test:all runs all three of these tests, as well as linting the codebase:
grunt jasmine_nodeexecutes shared and server Jasmine tests in Node.js
grunt jasmineexecutes shared and client Jasmine tests in PhantomJS
grunt shell:cheapseatsexecutes feature tests using cheapseats with a small subset of dashboards, for speed
grunt shell:cheapseats_full_runruns cheapseats with all dashboards
grunt test:functionalexecutes functional tests using [nightwatch][https://github.com/beatfactor/nightwatch]
As part of the CI (travis)
grunt test:functional:ci is run. This spins up an instance of spotlight, nightwatch and phantomjs to run the tests in a headless environment.
To assist with debugging the functional tests can also be run in a selenium webdriver using the following command
If you want to run against firefox,chrome and phantom you can also do
All the functional tasks except
ci will require a server to be running already.
In the browser
When the app is running in development mode, Jasmine tests for shared
components are available at
/tests. The specrunner gets automatically
recreated on server start and when the specfiles change. Due to a
bug in grunt-contrib-watch, new spec files are not currently
detected automatically. When you add a new spec file, either restart the
app or run
Install node-inspector where the app runs with
sudo npm install -g firstname.lastname@example.org
and run it with
Start the app with
node --debug app/server.js and visit
to view the console.
grunt build:production to create a production release.
NODE_ENV=production node app/server.js to run the app in production mode.
If you want to deploy the app to Heroku, follow these instructions.
Create an app on Heroku
Using the web interface, or the CLI:
heroku create <app-name>
Set the app to use the node-grunt buildpack
The app runs on Heroku using a custom buildpack for Grunt.js support.
This means it will run the grunt commands we need to compile the app when deploying code.
heroku config:set BUILDPACK_URL=https://github.com/mbuchetics/heroku-buildpack-nodejs-grunt.git
Set configuration vars
heroku config:set NODE_ENV=development # makes app run in development mode heroku config:set npm_config_production=true # does not install dev dependencies
Deploy the code
If the code you're deploying is not in master, then you'll need to make sure you specify your local branch to push to master. Otherwise it will just deploy your local master (and probably not work as expected).
git push heroku <your-branch-name>:master heroku open # opens the freshly deployed app in a browser
If you want the Heroku app to be password-protected, set config variables as follows, before pushing the code.
heroku config:set BASIC_AUTH_USER=xxxx heroku config:set BASIC_AUTH_PASS=xxxx heroku config
You might also want to enable some logging in your Heroku app to assist with debugging. You can use logentries to do that:
heroku addons:add logentries
You can then access the logs from your app's dashboard on Heroku (under the "Add-ons" section).
All content should work well with screenreaders (at least Voiceover and JAWS). 'Work well' means
- a screenreader user can orientate themselves effectively and use the page.
- async updates are reported to the user (an 'accessibility' module exists for this).