compliance


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 below.

test runners

compliance currently relies on browserify
during compliance testing.
compliance supports test runners that play well with browserify
to build the test bundle for the browser.
this includes karma with 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:

$3

* 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,
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.

$3

* 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

this project is currently in concept phase - not appropriate for production.

license

(C) Copyright 2015, bzb-stcnx,
MIT