compliance
v0.2.2compliance
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:
interface modules
- test suites in interface modules
require('compliance/applicant')
to access the implementation module thatcompliance
will inject before running the suites. - additionally,
browserify
is configured withcompliance
as a transform, allowing it to inject the implementation module when generating the test bundle: all occurrences of single- or double-quotedcompliance/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 itspackage.json
file. as for any other entry independencies
, 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 ofpackage.json
, e.g.:
"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'spackage.json
but not listed in itsdependencies
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'spackage.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 arequire
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
Metadata
- SEE LICENSE IN ./LICENSE
- Whatever
- bzb-stcnx
- released 10/23/2015