compliance
Version:
validate compliance of a javascript module against a test suite module
104 lines (88 loc) • 5.47 kB
Markdown
# compliance
[](https://nodei.co/npm/compliance/)
[](http://travis-ci.org/bzb-stcnx/compliance)
[](https://github.com/feross/standard)
validate compliance of a javascript module against a test suite module.
primarily intended for **validating that a module implements given interfaces**.
interfaces are implemented as modules which contain compliance test suites.
compliance of an implementation module to a set of interface modules
is validated by running the implementation module against the test suites
from the declared interface modules.
this is supplementary to static type-checking as it ensures
that an implementation module not only exposes the proper object and method signatures
but that it also provides the expected functionality
defined in the test suites of the interface modules.
although this goes beyond the current scope of this project,
interface modules are a good place to keep additional interface-related files,
such as typescript type declaration files `.d.ts`.
compliance has zero impact on production runtime:
like static type-checking, it runs during the development phase of a project.
# motivation
"program to an interface, not an implementation" - GoF
see [dependency injection](#dependency-injection) below.
# test runners
`compliance` currently relies on [browserify](https://www.npmjs.com/package/browserify)
during compliance testing.
`compliance` supports test runners that play well with `browserify`
to build the test bundle for the browser.
this includes [karma](http://karma-runner.github.io/) with [karma-browserify](https://www.npmjs.com/package/karma-browserify).
# usage
## configuration
to enable compliance testing of an implementation module to interface module specs,
the implementation and the interface modules should be set up as follows:
### interface modules
* test suites in interface modules `require('compliance/applicant')`
to access the implementation module
that `compliance` will inject before running the suites.
* additionally, `browserify` is configured with `compliance` as a
[transform](https://github.com/substack/browserify-handbook#browserifytransform-field),
allowing it to inject the implementation module when generating the test bundle:
all occurrences of single- or double-quoted `compliance/applicant` are replaced
with respectively single- or double-quoted file path of the implementation module.
### implementation module
* the implementation module naturally lists all interface modules it implements
as `dependencies` in its `package.json` file.
as for any other entry in `dependencies`,
this clearly defines the desired version of each interface module.
* additionally, each interface module against which the implementation module
should be tested is listed in a dedicated `compliance` entry of `package.json`,
e.g.:
```json
"compliance": [ "an-interface-module", "another-interface-module", ... ]
```
## compliance validation
to validate compliance of an implementation module against declared interface modules,
run the `compliance` command from the shell or a `test` script of the implementation module.
* interface modules listed as `compliance` in the implementation module's `package.json`
but not listed in its `dependencies` are ignored
and will trigger a corresponding warning during compliance validation
* compliance will only be validated against the test suites from interface modules
listed as `compliance` in the implementation module's `package.json`
* the version of the interface module against which an implementation module
is validated is that listed in its `dependencies`
# dependency injection
`compliance` allows to define dependencies as interfaces rather than implementations.
* library modules (i.e. modules meant to be called upon by client code) can list
interface module dependencies without specifying corresponding implementations.
* library modules can either expect the implementation dependencies to be
supplied by client code as arguments to its factory function,
or simply `require` the interface modules and
expect the corresponding implementation modules to be injected by client code.
* client code directly or indirectly depending on such library modules
can themselves define corresponding implementation module dependencies,
and either provide these as arguments to library module factories
or inject these appropriately into the library modules.
* `browserify` provides means of statically injecting an implementation module
in place of a `require` for a corresponding interface module during bundling.
* client code relies on the fact that the compliance
of the injected implementation module has been validated
against the required interface module by the implementations module test suite.
* however, it is also conceivable to add additional validation in the client's test suites
* for example, to compare declared versions during bundling for additional security,
* or to run the interface's test suites on the injected module.
# status
[](http://github.com/badges/stability-badges)
this project is currently in concept phase - not appropriate for production.
# license
(C) Copyright 2015, bzb-stcnx,
[MIT](./LICENSE)