openmct/README.md

Open MCT Web

Open MCT Web is a web-based platform for mission operations user interface software.

Bundles

A bundle is a group of software components (including source code, declared as AMD modules, as well as resources such as images and HTML templates) that are intended to be added or removed as a single unit. A plug-in for Open MCT Web will be expressed as a bundle; platform components are also expressed as bundles.

A bundle is also just a directory which contains a file bundle.json, which declares its contents.

The file bundles.json (note the plural), at the top level of the repository, is a JSON file containing an array of all bundles (expressed as directory names) to include in a running instance of Open MCT Web. Adding or removing paths from this list will add or remove bundles from the running application.

Bundle Contents

A bundle directory will contain:

• bundle.json, the declaration of the bundles contents.
• A source code directory, named src by convention. This contains all JavaScript sources exposed by the bundle. These are declared as AMD modules.
• A directory for other resources, named res by convention. This contains all HTML templates, CSS files, images, and so forth to be used within a given bundle.
• A library directory, named lib by convention. This contains all external libraries used and/or exposed by the bundle.
• A test directory, named test by convention. This contains all unit tests declared for the bundle, as well as a suite.json that acts as a listing of these dependencies. See the section on unit testing below.

Following these bundle conventions is required, at present, to ensure that Open MCT Web (and its build and tests) execute correctly.

Tests

The repository for Open MCT Web includes a test suite that can be run directly from the web browser, test.html. This page will:

• Load bundles.json to determine which bundles are in the application.
• Load test/suite.json to determine which source files are to be tested. This should contain an array of strings, where each is the name of an AMD module in the bundle's source directory. For each source file:
  • Code coverage instrumentation will be added, via Blanket.
  • The associated test file will be loaded, via RequireJS. These will be located in the bundle's test folder; the test runner will presume these follow a naming convention where each module to be tested has a corresponding test module with the suffix Spec in that folder.
• Jasmine will then be invoked to run all tests defined in the loaded test modules. Code coverage reporting will be displayed at the bottom of the test page.

At present, the test runner presumes that bundle conventions are followed as above; that is, sources are contained in src, and tests are contained in test. Additionally, individual test files must use the Spec suffix as described above.

An example of this is expressed in platform/framework, which follows bundle conventions.

Build

Open MCT Web includes a Maven command line build. Although Open MCT Web can be run as-is using the repository contents (that is, by viewing index.html in a web browser), and its tests can be run in-place similarly (that is, by viewing test.html in a browser), the command line build allows machine-driven verification and packaging.

This build will:

• Check all sources (excluding those in directories named lib) with JSLint for code style compliance. The build will fail if any sources do not satisfy JSLint.
• Run unit tests. This is done by running test.html in a PhantomJS browser-like environment. The build will fail if any tests fail.
• Package the application as a war (web archive) file. This is convenient for deployment on Tomcat or similar. This archive will include sources, resources, and libraries for bundles, as well as the top-level files used to initiate running of the application (index.html and bundles.json).

Run as mvn clean install.