Methods

before()

Signature: before( context, toolkitOptions ): Function

This method is generating a function for use with test runners such as mocha (opens new window) on setting up tests or test suites. It requires provision of empty context descriptor to be set up and toolkit options for customizing started Hitchy instance.

The common pattern looks like this:

const ctx = {};

before( ServerDevTools.before( ctx, { ... } ) );

Check out our examples for additional demonstration.

after()

Signature: after( context ): Function

This method is generating a function for use with test runners such as mocha (opens new window) on tearing down tests or test suites. It requires provision of same context descriptor used with before() to pick the right instance of Hitchy to shut down.

Combined with before(), the common pattern looks like this:

const ctx = {};

before( ServerDevTools.before( ctx, { ... } ) );
after( ServerDevTools.after( ctx ) );

Check out our examples for additional demonstration.

start()

Prefer before()

When using test runner such as mocha, before() and after() should be preferred over start() and stop().

Signature: start( toolkitOptions ): Promise<ContextDescriptor>

This method is starting Hitchy instance serving project selected in mandatory set of toolkit options. It is returning promise resolved with context descriptor.

stop()

Prefer after()

When using test runner such as mocha, before() and after() should be preferred over start() and stop().

Signature: stop( context ): Promise<void>

This method requires context descriptor returned from related start() to shut down related instance of Hitchy. It is returning another promise resolved when Hitchy instance has been shut down properly.

request()

Do not use!

This method is exposed to keep providing some basic support for previous use cases based on an API which has been removed already. It's support for recently added options is limited.

You should use request helpers exposed in context descriptor instead.

Signature: request( method, route, body, headers ): Promise<ExtendedServerResponse>

This method is sending an HTTP request to manually bound Hitchy instance using provided HTTP method, some route into the instance as well as some optional body data and custom HTTP request headers.

No support for remote queries

This method is tightly integrated with Hitchy's request dispatcher. Thus, you can't use it to sent requests to remote endpoints. That's why second argument should be path with query, only.

The request data in body might be string, instance of Buffer or some arbitrary data to be converted to JSON string.

The method is returning Promise resolved with completely consumed response. This response is basically an HTTP response object commonly supported by NodeJS. It is though qualified with some additional properties:

• The raw response body is included as a Buffer in property body.

• If response headers indicate JSON-formatted response the parsed object is exposed in property data of promised response.

• If response headers indicate some textual content it is exposed in property text if promised response.

Manual Binding

You must call this method manually bound to context descriptor promised by start() like this:

const Assert = require( "node:assert" );
const { start, stop, request } = require( "@hitchy/server-dev-tools" );
 
start().then( ctx => { 
    return request.call( ctx, "PUT", "/exposed/route/of/hitchy?foo=bar", {
        prop: "some info",
    } )
        .then( response => {
            Assert.strictEqual( response.statusCode, 200, "HTTP status code must be 200" );
        } )
        .finally( () => stop( ctx ) );
} );

Toolkit Options

The toolkit supports the following set of options for controlling context of running Hitchy instances.

projectFolder

The toolkit tries to discover the folder containing a Hitchy-based application to be started for testing. However, when testing a plugin, this test will fail most likely. There may be other reasons for selecting project explicitly, too.

This option can be a string providing the relative or absolute path name of a folder containing usual implementation files of a Hitchy-based application such as config/, api/controllers/ or api/services/.

{ projectFolder: "../projects/sample-a" }

You may provide false instead of a string to explicitly prevent the automatic discovery of a project from interfering with your intention to describe all files of test project using files option.

{ projectFolder: false }

Relative path names

Relative path names must start with ./ or ../. They are resolved in relation to folder containing your test script file.

pluginsFolder

This option selects folder containing sub-folder node_modules with additional Hitchy plugins required at runtime.

Relative path names

Relative path names must start with ./ or ../. They are resolved in relation to folder containing your test script file.

plugin 0.4.0+

You should always set this boolean option when testing a plugin. It is controlling the toolkit to discover default options in a slightly different way.

files

This is an object mapping relative path names of files into either file's content to be written to some temporary project folder created as a copy from selected or discovered project folder.

Project folder, only

Any copy consists of files found in selected or discovered project folder, only. It doesn't apply to separate plugins folder. Any content of a node_modules/ sub-folder is always ignored.

These limitations are intended to improve performance on frequently setting up and tearing down applications based on Hitchy.

This option is useful for adjusting project folder per test more conveniently.

{
    files: {
        "config/routes.js": "exports.routes = { '/': ( _, res ) => res.json( 'success' ) }"
    }
}

This example is writing

exports.routes = { '/': ( _, res ) => res.json( 'success' ) }

to a file named config/routes.js which is picked up by Hitchy instance started afterwards.

useTmpPath

When declaring files, a temporary copy of a selected project is made automatically. Otherwise, Hitchy instance is set up to work on project folder as selected.

This boolean option can be set to enforce tests running on a temporary copy of a selected project folder even without declaring additional files. It is useful to start fresh on every test run assumed to adjust files in tested project folder.

Project folder, only

Any copy consists of files found in selected or discovered project folder, only. It doesn't apply to separate plugins folder. Any content of a node_modules/ sub-folder is always ignored.

These limitations are intended to improve performance on frequently setting up and tearing down applications based on Hitchy.

options

This setting contains custom options forwarded to Hitchy. See Hitchy's manual (opens new window) for options basically supported here. In addition, any plugin or application may support these additional options.

options.debug

This might be the most frequently used option during test implementation as it is enabling all logging.

{ options: { debug: true } }

options.tools

This is optionally picking tools of a different instance of Hitchy to be used instead of those found in declared dependency of server dev tools. This is mostly required for testing Hitchy itself, thus you may consider this option internal.

args

This array lists arguments usually provided on command line when controlling application using CLI script of Hitchy. It is supported to control CLI arguments of your application affecting its behavior.

{ args: [ "--api-key", "secr3tKey", "--license-server", "https://foo.example.com" ] }

Context Descriptor

All methods controlling Hitchy instance are processing or returning a context descriptor. It is used to identify the Hitchy instance to control. And it's providing information for interacting with the running instance as conveniently as possible.

server

This is referring to the HTTP server set up for handling incoming requests to be dispatched into Hitchy instance.

hitchy

This is a reference to started instance of Hitchy. Use hitchy.api to access its API (opens new window) for inspection, only.

WARNING

You shouldn't use this reference for anything but inspecting state of Hitchy at runtime.

temporaryFolder

This property provides the path name of a temporary project folder managed by the toolkit. It might be undefined in case of directly using some existing folder on disk.

logged

This is an array of strings listing messages logged to console.

hitchyOptions

After starting Hitchy instance, this property exposes the set of eventually used Hitchy options.

request()

Signature: request( method, route, body, headers )

This method is exposing common HTTP client for emitting requests implicitly addressing running Hitchy instance. The signature is identical to request(), but this time you don't need to bind it manually.

There are several additionally exposed wrapper methods based on this one:

get()

Signature: get( route, headers )

This method is sending GET request to running Hitchy instance.

No request body!

This method omits separate argument for request body data due to the lack of supporting any such payload in GET requests.

post()

Signature: post( route, body, headers )

This method is sending POST request to running Hitchy instance.

put()

Signature: put( route, body, headers )

This method is sending PUT request to running Hitchy instance.

patch()

Signature: patch( route, body, headers )

This method is sending PATCH request to running Hitchy instance.

delete()

Signature: delete( route, body, headers )

This method is sending DELETE request to running Hitchy instance.

head()

Signature: head( route, headers )

This method is sending HEAD request to running Hitchy instance.

No request body!

This method omits separate argument for request body data due to the lack of supporting any such payload in HEAD requests.

options()

Signature: options( route, headers )

This method is sending OPTIONS request to running Hitchy instance.

No request body!

This method omits separate argument for request body data due to the lack of supporting any such payload in OPTIONS requests.

trace()

Signature: trace( route, headers )

This method is sending TRACE request to running Hitchy instance.

No request body!

This method omits separate argument for request body data due to the lack of supporting any such payload in TRACE requests.