# Applications

A Hitchy-based application usually focuses on exposing an API over HTTP. For unit testing this API the application must be started and stopped before and after running any test suite.

Assuming there is a Hitchy-based project in folder

/path/to/my/app

Its tests may reside in

/path/to/my/app/test

One of the files in that folder could be named example.spec.js. The following code is an example for a simple unit test to be run with mocha (opens new window):

const { describe, before, after, it } = require( "mocha" );
const ServerDevTools = require( "@hitchy/server-dev-tools" );
require( "should" );

describe( "A controller of my app", () => {
    const ctx = {};
    
    before( ServerDevTools.before( ctx, { options: { ... } } ) );
    after( ServerDevTools.after( ctx ) );
    
    it( "properly responds to incoming query", () => {
        return ctx.post( "/some/url", {
            prop: "value",
        } )
        .then( response => {
            response.statusCode.should.be.equal( 200 );
        } );
    } );
} );

In this example, root folder of project also containing this test file is picked as Hitchy project folder.

# Plugins

Testing a plugin is slightly different from testing an application:

  • A plugin isn't bound to a particular project folder. Instead, you need to provide a fake project which claims to depend on the plugin to be tested.

  • Different applications might use the same plugin for different use cases. The plugin might behave differently depending on its including application. Thus, proper unit testing requires different projects to test the plugin with. Either project must be faked most probably.

  • The project containing a test suite is implementing the plugin, only. It gets integrated with an application as a dependency residing in that application's node_modules/ folder by design. Due to faking multiple project folders, the plugin gets injected explicitly every time.

Assuming you are developing a plugin in folder

/path/to/my/plugin

There may be tests in

/path/to/my/plugin/test/scripts

Fake project folders could be implemented in

/path/to/my/plugin/test/projects

just like

/path/to/my/plugin/test/projects/candidate-a

A resulting test script /path/to/my/plugin/test/scripts/example.spec.js should look like this:

const Path = require( "node:path" );

const { describe, before, after, it } = require( "mocha" );
const SDT = require( "@hitchy/server-dev-tools" );
require( "should" );

describe( "An application relying on my plugin", () => {
    const ctx = {};
    
    before( SDT.before( ctx, {
        pluginTestFolder: Path.join( __dirname, "../.." ),
        projectFolder: Path.join( __dirname, "../project/candidate-a" ),
        options: { ... }
    } ) );
    
    after( SDT.after( ctx ) );
    
    it( "handles request properly", () => {
        return ctx.post( "/some/url", {
            prop: "value",
        } )
        .then( response => {
            response.statusCode.should.be.equal( 200 );
        } );
    } );
} );

This example is different from the previous one for testing application in toolkit options provided:

  • projectFolder is selecting a fake project folder instead of current project's root folder.

  • pluginFolder is picking root folder of plugin's project this test is a part of. This way Hitchy will discover the plugin on running in context of fake application in fake project folder.

# Describing Project Folders

Due to relying on existing fake project folders on disk, implementing unit tests for a plugin may be hard to manage. That's why this toolkit supports self-contained unit tests by describing the desired project folder's content to be written to disk temporarily:

const Path = require( "node:path" );

const { describe, before, after, it } = require( "mocha" );
const ServerDevTools = require( "@hitchy/server-dev-tools" );
require( "should" );

describe( "An application relying on my plugin", () => {
    const ctx = {};
    
    before( ServerDevTools.before( ctx, {
        pluginFolder: Path.join( __dirname, "../.." ),
        files: {
            "config/routes.js": `exports.routes = { "/foo": ( _, res ) => res.send( "Hello!" ) };`,
        }, 
        options: { ... }
    } ) );
    
    after( ServerDevTools.after( ctx ) );
    
    it( "handles request properly", () => {
        return ctx.get( "/foo" )
            .then( response => {
                response.body.toString( "utf8" ).should.be.equal( "Hello!" );
            } );
    } );
} );

In this example toolkit option files is used to provide temporary content for a file to be injected into some temporary project folder. Of course, multiple files may be provided that way.

Combining those two approaches helps with eliminating redundancies. An existing project folder on disk could serve as a common template for several test cases. Either test suite is describing content of files differing from that template, only. The toolkit will copy the selected project folder to temporary location and adjust files according to provided file descriptions afterwards.

# Testing without mocha

This toolkit does not rely on mocha for running your tests. It works just fine without any particular test runner as demonstrated in this example:

const Assert = require( "node:assert" );

const { before, after } = require( "@hitchy/server-dev-tools" );

const ctx = {};

before( ctx, { pluginFolder: __dirname } )()
    .then( () => 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( after( ctx ) );

However, using test runners like mocha is suggested e.g. for conveniently performing multiple tests in scope of a single run of Hitchy.