Development Guide

This guide lists the available NPM and Make scripts and commands used to simplify Scenic's development process.

To get detailed information on the inner architecture and dependencies of Scenic, please refer to the Maintenance Guide.

NPM Scripts

NPM is used extensively to serve, build, test and document the Scenic codebase. NodeJS LTS must be installed on your system.

Command Mode Description
npm install * Install all internal dependencies of the project
npm start Development Start a webpack development server for the Scenic webapp on localhost:8080
npm run build Production Build and optimize the webapp into the `dist` folder
npm run lint Development Lint the project with the StandardJS linter
npm run test:coverage Development Run all tests and generate a full coverage report of the code (used for CI)
npm run test:unit Development Run all unit tests
npm run test:integration Development Run all integration tests
npm run test Development Run all tests (using Jest
npm run test:watch Development Watch the codebase and rerun the tests when changes are detected (requires the entr utility)
npm run doc:jsdoc * Generate the docs/JSDOC.md file from the JSDoc docstrings embedded in the JavaScript code
npm run doc:selectors * Generate the docs/SELECTOR_GLOSSARY.md file from the React component files
npm run doc:build * Build the whole user documentation using MkDocs into the `public` folder
npm run doc:serve * Start an MkDocs development server for the user documentation on localhost:8000

Keep in mind that scenic-core needs to be running in order for Scenic to do anything. The web application will be unusable as long as a Websocket connection between the UI and the Core isn't established. The UI respects the Websocket API provided by scenic-core.

Warning

The application build is heavy and may fail with a JS heap out of memory error. You can fix this by building the distribution with NODE_ENV=production node --max_old_space_size=8048 ./node_modules/webpack/bin/webpack.js --progress --config config/webpack.config.js

Make Scripts

The project's Makefile provides additional utility scripts, mainly for deployment and CI/CD purposes

Command Purpose Description
make build Deployment Build the application from a clean installation
make bundle Deployment Build and bundle the application into a compressed file
make install Deployment Deploy the application in a local H2O server
make install-apache Deployment Deploy the application in a local Apache2 HTTP server
make clean Housekeeping Remove all auto-generated folders
make install-mkdocs Housekeeping Install the User Documentation dependencies
make uninstall Housekeeping Uninstall everything installed by make install
make sort-locale-keys Housekeeping Alphabetically sort all keys in the locale.json asset files

Debugging

To debug Scenic, you should use the npm start to build and serve the application on localhost:8080. You should also use your browser's Developer Tools to inspect the application. Specifically, the Browser Console will output every message, error and warnings needed for debugging the application, all in real-time.

Testing

To avoid regression bugs, we try to keep Scenic's coverage high. To automate Scenic's testing while making changes to the codebase, we highly recommend the usage of the npm run test:watch script, which leverages the power of the entr utility. This NPM command will automatically run unit tests when changes are detected in the codebase. You can also limit which tests and which part of the codebase will be watched with the following command:

npm run test:watch -- SocketStore # Only runs tests associated with the 'SocketStore'

Generating the documentation

Scenic's user documentation is built with MkDocs. To generate it, first install the Python dependencies:

pip install setuptools # must be installed first
pip install -r docs/requirements.txt

You should then be able to serve the whole documentation on localhost:8000:

npm run doc:serve # Serve the Mkdocs site on localhost:8000
firefox localhost:8000

Know that the JSDoc can be generated separately from the docstrings in the JS codebase, inside the JSDOC.md file. The same applies to the SELECTOR_GLOSSARY.md file, which contains a list of automatically generated CSS selectors used for E2E testing with automated tools such as Selenium. To generate these files separately:

npm run doc:selector # Generate the SELECTOR_GLOSSARY.md file
npm run doc:jsdoc # Generate the JSDOC.md file

The docs/JSDOC.md and docs/SELECTOR_GLOSSARY.md files are also automatically generated by the npm run doc:serve and npm run doc:build commands.