npm package: @inpas/test-tools
Description: Helper functions for the unit testing of the Docker services from INPAS 3rd-gen
Author: cepharum GmbH
Latest version: 1.0.12

# INPAS 3rd-gen: Test tools

This project contains files related to unit tests
which are used in many of the other INPAS 3rd-gen projects.

The content will be exposed as a npm-module
so that it can be easily included into other projects
for their unit tests.

# Installation

The module depends on Node.js and mocha. That's the command which has to be invoked within the project's root directory:

```
npm install --save-dev @inpas/test-tools
```

# Usage

The module is to be used with Node.js and mocha. Include the following into every test-file:

```
const Tools = require( "@inpas/test-tools" );
```

# Docker tools

## Tools.docker.exec()

`function( container, command, args = [], expected = null )`

Invokes a system command inside a Docker-container. Some automated tests are run if the matching options are set in argument 'expected'.

```js
// Example:
Tools.docker.exec( "inpas-ldap", "ldapsearch", [ "-x", "-b", "dc=kunde,dc=de" ] )
	.then( output => {
		...
	} );
```

## Tools.docker.start()

`function( composeFile = null, env = {}, containerWithoutRestart = null )`

Starts the given Docker-service.

```js
// Example:
Tools.docker.start()
	.then( output => {
		...
	} );
```

## Tools.docker.check()

`function( containerName, additionalChecks = {} )`

Checks if the given Docker-container is running.

```js
// Example:
Tools.docker.check( "inpas-ldap" )
	.then( running => {
		...
	} );
```

## Tools.docker.stop()

`function( composeFile = null, cleanupVolumes = false )`

Stops the given Docker-service.

```js
// Example:
Tools.docker.stop()
	.then( output => {
		...
	} );
```

## Tools.docker.sysAutomate()

`function( serviceDescription, freshStartOrFinish = [ false, false ] )`

Sets up a before-hook and an after-hook for some mocha-tests. Those hooks shall ensure that the containers of the Docker-service are running during the tests and may return to their initial state afterwards, if needed.

If the function is called again (e.g. because you have two test-files which are run together), no new hooks will be installed. However you have to pass the same options like before or an error will be thrown.

```js
// Example:
Tools.docker.sysAutomate(
	{ title: "LDAP", name: "inpas-ldap", ports: [ 389, 636 ] },
	[ true, false ]
);
```

## Tools.docker.sysStop()

`function()`

Uses the Docker configuration which was given to docker.sysAutomate() and (temporarily) stops the Docker-service.

```js
// Example:
Tools.docker.sysStop();
```

## Tools.docker.sysStart()

`function()`

Uses the Docker configuration which was given to docker.sysAutomate() and starts the Docker-service. If you also want to wait for the Docker-service to be listening on its port(s), use docker.sysIsListening() afterwards.

```js
// Example:
Tools.docker.sysStart()
	.then( () => Tools.docker.sysIsListening() );
```

## Tools.docker.sysIsListening()

`function()`

Uses the Docker configuration which was given to docker.sysAutomate(), checks if the Docker-service is running and - in case some ports where stated to docker.sysAutomate() - if it's listening on at least one of its ports.

```js
// Example:
Tools.docker.sysIsListening();
```

## Tools.docker.sysRestart()

`function( checkListening = true )`

Uses the Docker configuration which was given to docker.sysAutomate(), stops the Docker-service (if it's running) and starts it again.

```js
// Example:
Tools.docker.sysRestart();
```

# HTTP tools

## Tools.http.checkRawResponse()

`function( response, expected )`

Determines the raw body of a HTTP response which was received from module "http-tag-string". Some additional checks may be run, too.

```js
// Example:
HTTP`GET /`()
	.then( response => Tools.http.checkRawResponse( response, { status: 200 } ) )
	.then( bodyBuffer => {
		...
	} );
```

## Tools.http.checkJsonResponse()

`function( response, expected )`

Determines the JSON of a HTTP response which was received from module "http-tag-string". Some additional checks may be run, too.

```js
// Example:
HTTP`GET /`()
	.then( response => Tools.http.checkJsonResponse( response, { status: 200 } ) )
	.then( bodyJSON => {
		...
	} );
```

## Tools.http.checkTextResponse()

`function( response, expected )`

Determines the body of a HTTP response which was received from module "http-tag-string". Some additional checks may be run, too.

```js
// Example:
HTTP`GET /`()
	.then( response => Tools.http.checkTextResponse( response, { status: 200 } ) )
	.then( bodyText => {
		...
	} );
```

## Tools.http.handleRedirect()

`function( response )`

Takes a HTTP response which was delivered from module "http-tag-string" and is expected to be a redirection to another location. The location of the redirection is taken for a new HTTP request which is created with support of module "http-tag-string", again.

```js
// Example:
HTTP`GET /`()
	.then( response => Tools.http.handleRedirect( response ) )
	.then( response => Tools.http.checkTextResponse( response, { status: 200 } ) )
	.then( bodyText => {
		...
	} );
```

# Object tools

## Tools.object.matchData()

`function( dataObject, expected )`

Takes an object and checks if some properties match with the given values.

```js
// Example:
HTTP`GET /`()
	.then( response => Tools.http.checkJsonResponse( response, { status: 200 } ) )
	.then( bodyJSON => Tools.object.matchData( bodyJSON, { error: /invalid model/i } ) );
```