Hitchy SDT Manual v0.4.9

# About

This toolkit is supporting development of software based on or related to Hitchy (opens new window). It is temporarily running an instance of Hitchy in context of a given folder. Methods are exposed to control the Hitchy instance and for integrating it with a test runner as conveniently as possible.

The temporary Hitchy instance serves a project in a customizable or auto-detected folder or based on a map of strings describing files to write before starting Hitchy. Both options can be combined, too.

Last but not least, a CLI tool helps with fetching peer dependencies of your plugin.

# Installation

Always install this package as a development dependency:

npm i -D @hitchy/server-dev-tools

Dependencies of a plugin

A Hitchy plugin should never depend on Hitchy's core (opens new window) directly. It is fetched as a dependency of these server-dev-tools for testing purposes.

For production use, your plugin should mark @hitchy/core as a peer dependency:

{
    "peerDependencies": {
        "@hitchy/core": "*"
    }
}

# Usage

This toolkit expose methods for easily starting and stopping an instance of Hitchy in current process. You can pass options and arguments into started Hitchy application. In addition, you can customize testing environment via some additional options.

# Terminology

# Application vs. plugin

The toolkit is designed to support in two kinds of projects:

  • A Hitchy-based application depends on Hitchy's core to expose endpoints and to route client requests to associated handlers. An application is usually installed as-is.

  • A plugin for Hitchy extends functionality of Hitchy's core. It can be pulled by an application as another dependency. Thus, it is capable of running in context of different applications probably providing each one with a slightly different functionality.

# Folders

In every project, these distinguishable folders are expected:

  • The project folder contains a Hitchy-based application's implementation. It usually consists of folders named config, api/controllers, api/policies etc.

  • The plugins folder consists of a node_modules sub-folder listing dependencies of your application. It is used by Hitchy to discover plugins.

Both folders are usually identical, but may be different, too. The latter applies to test projects used for testing plugins or to application projects combining client-side code with server-side code (opens new window).

Breaking change of names 0.4.0+

In recent versions, the naming of options picking folders has changed several times. However, their latest names haven't been as sound as desired, either. By introducing auto-discovery of folders, names have been reduced again, causing some of them returning to their previous versions.

# Auto-discovering folders 0.3.0+

This toolkit is designed to work out of the box in most use cases by automatically discovering project folder and plugins folder unless configured explicitly.

Auto-discovery often depends on folder containing current test. This file is the one importing @hitchy/server-dev-tools to use exposed methods for starting Hitchy instance.

# Discovering project folder

For discovering projectFolder, closest parent folder satisfying the following rules is picked:

  1. It contains a package.json file.

  2. It does not contain a hitchy.json file (thus it is the root of an application).

    This condition is ignored when setting plugin option. Plugins have to provide a hitchy.json file.

  3. The package.json file is declaring @hitchy/server-dev-tools as a development dependency.

From there, all subordinated folders are inspected, excluding those commonly used in a project, such as:

  • node_modules
  • .vscode
  • .idea
  • .git
  • dist
  • coverage

All sub-folders containing one of

  • config/
  • api/controllers/ or api/controller/
  • api/policies/ or api/policy/
  • api/models/ or api/model/
  • api/services/ or api/service/

are picked as candidates if they contain at least one Javascript file. This includes files with extensions .js, .mjs or .cjs, but excludes files with either extension preceded by .spec or .test.

If multiple folders have been found, a debug message is logged listing all candidates. Auto-discovery has failed in such cases and a project folder must be selected explicitly.

Disabling auto-discovery

Auto-discovery of project folder can be disabled explicitly by either

# Discovering plugins folder

pluginsFolder is discovered after probable discovery of projectFolder.

← API Reference →