# ut-run > UT run module Latest version **10.78.19** (published 2025-08-18) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install ut-run pnpm add ut-run yarn add ut-run bun add ut-run ``` Provides the command `ut-run`. ## Health **Score 45/100 (D)** — status: stable. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: stale. ## Facts | | | |---|---| | Version | 10.78.19 | | Published | 2025-08-18 | | First published | 2016-08-12 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | CommonJS | | Node | ^14.15.3 \|\| ^16.14.0 | | Dependencies | 23 | | Unpacked size | 840 KB | | Known vulnerabilities | 0 (+6 in 4 direct dependencies) | | Install scripts | no | | GitHub stars | 4 | | Maintainers | kalin.krustev | ## Links - npm: https://www.npmjs.com/package/ut-run - Repository: https://github.com/softwaregroup-bg/ut-run - Homepage: https://github.com/softwaregroup-bg/ut-run#readme - Issues: https://github.com/softwaregroup-bg/ut-run/issues - npm.io page: https://npm.io/package/ut-run ## Dependencies (23) - [got](https://npm.io/package/got.md) 11.8.5 - [joi](https://npm.io/package/joi.md) 17.4.2 - [uuid](https://npm.io/package/uuid.md) 8.3.2 - [yaml](https://npm.io/package/yaml.md) 1.10.0 - [semver](https://npm.io/package/semver.md) 7.5.4 - [ut-bus](https://npm.io/package/ut-bus.md) ^7.66.4 - [ut-log](https://npm.io/package/ut-log.md) ^6.11.3 - [ut-port](https://npm.io/package/ut-port.md) ^6.45.2 - [chokidar](https://npm.io/package/chokidar.md) 3.5.3 - [loadtest](https://npm.io/package/loadtest.md) 5.1.0 - [through2](https://npm.io/package/through2.md) 4.0.2 - [commander](https://npm.io/package/commander.md) ^7.2.0 - [csv-parse](https://npm.io/package/csv-parse.md) 5.0.4 - [sort-keys](https://npm.io/package/sort-keys.md) 4.1.0 - [ut-config](https://npm.io/package/ut-config.md) ^7.10.0 - [@types/tap](https://npm.io/package/@types/tap.md) ^15.0.7 - [stack-utils](https://npm.io/package/stack-utils.md) 2.0.5 - [@npmcli/arborist](https://npm.io/package/@npmcli/arborist.md) 5.6.0 - [lodash.clonedeep](https://npm.io/package/lodash.clonedeep.md) 4.5.0 - [joi-to-typescript](https://npm.io/package/joi-to-typescript.md) 2.2.1 - [ut-function.merge](https://npm.io/package/ut-function.merge.md) ^1.5.6 - [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) 4.0.0 - [browser-process-hrtime](https://npm.io/package/browser-process-hrtime.md) 1.0.0 ## Recent versions - 10.78.19 (latest) — 2025-08-18 - 11.0.0-jod.0 (jod) — 2025-11-12 - 10.70.22-jose.0 (jose) — 2022-11-17 - 10.70.0-config-ref.1 (config-ref) — 2022-07-06 - 10.67.0-gallium.3 (gallium) — 2022-03-22 - 9.4.1-config-crypt-9-4-0.0 (config-crypt-9-4-0) — 2021-01-13 - 9.7.2-config-crypt-9-7-1.0 (config-crypt-9-7-1) — 2021-01-13 - 10.41.0-mle.3 (mle) — 2020-11-07 - 10.30.0-start-namespace.1 (start-namespace) — 2020-07-29 - 10.21.0-login.1 (login) — 2020-05-18 - 10.20.0-validations.10 (validations) — 2020-04-30 - 9.2.2 (patch-abtDevelop) — 2019-12-04 - 9.2.1 (abtDevelop) — 2019-12-03 - 10.7.0-k8s.12 (k8s) — 2019-08-02 - 9.8.1-amret.1 (amret) — 2019-04-22 - … 534 more at https://npm.io/package/ut-run/versions ## README # UT Run ## Purpose The module is used to start UT applications by initializing logging, starting bus and optional broker and then creating and initializing ports, modules and validations. ## Usage In the root of the application in file `index.js`, the module `ut-run` should be required and its function 'run' should be called. The file `index.js` in the root is used to start the application. Typical `index.js` file looks like: ```js let run = module.exports = params => require('ut-run').run({ version: require('./package.json').version, root: __dirname, resolve: require.resolve, params }); if (require.main === module) run(); ``` It uses `ut-run` package to start the application and passes the package version to it. ### Starting Starting the application from the command line can be done by passing these command line arguments: ```bash node index {app} {method} {env} ``` - `{app}` - specifies the name of sub-folder, where to find the app server to start. Defaults to 'server'. - `{method}` - specifies the way of running, defaults to 'debug'. The following methods are available: - `debug` - start the server - `install` - generate configuration for various installation targets - `{env}` - specifies the name of configuration file related to the environment. Environments like 'dev', 'prod' and 'test' are commonly used. Defaults to 'dev'. Using environment variables is also possible ```bash UT_APP=server UT_METHOD=debug UT_ENV=dev node index ``` ### Recommended application structure The recommended filesystem structure, when running only one server looks like this: ```text application ├───index.js └───server ├──common.js - common configuration for all environments ├──install.json - configuration applied during installation ├──debug.json - configuration applied during debugging ├──index.js - server startup file ├──prod.json - environment configuration file ├──test.json - environment configuration file └──dev.json - environment configuration file ``` When multiple servers exists in a single application, usually the folder structure is: ```text application ├───index.js └───server ├──server1 │ ├──common.js │ ├──index.js │ ├──prod.json │ ├──test.json │ └──dev.json └──server2 ├──common.js ├──index.js ├──prod.json ├──test.json └──dev.json ``` To run specific server in such cases, either set `UT_APP=server/server1` or pass as argument `node index server/server1` ### Configuration `ut-run` uses `ut-config` to load or edit the application configuration. For more information consult the [README](https://github.com/softwaregroup-bg/ut-config) there. When running an application with `ut-run.run` in standard (debug) mode you can take advantage of `ut-config` [templating capabilities](https://github.com/softwaregroup-bg/ut-config#templating). In other words everything explained there (including the encrypt/decrypt methods) can be applied when loading configuration. E.g. ```javascript require('ut-run').run({ context: { test: params => {/* do something*/} // or some function or something else // ...other context properties } // ...other run properties }); ``` Then in all configuration files (no matter whether they are rc, json, etc.) you can use the specified context as '${test(...something)}' ### Servers Server startup file `server/index.js` is recommended to follow this pattern: ```javascript module.exports = function({config}) { return [{ main: require.resolve('ut-telemetry'), pkg: require.resolve('ut-telemetry/package.json') }, { main: require.resolve('ut-module1'), pkg: require.resolve('ut-module1/package.json') }, { // ... }, { main: require.resolve('moduleN'), pkg: require.resolve('moduleN/package.json') }].filter(item => item).map(item => [item, ...arguments]); }; ``` The `config` parameter holds the environment configuration and can be used to implement more complex logic, when the default logic is not sufficient. It is not recommended to pass this configuration to the packages, as they should only be allowed to access their own section within the configuration. Usually modules are either reusing some standard functionality `require('ut-something')` or some application specific functionality `require('../impl/something')`. See [composable microservices](./microservices.md) for detailed description of module structure and configuration. See [standard UnderTree module structure](https://github.com/softwaregroup-bg/ut-standard) for recommended practical structure for modules. ### Working directory `ut-run` sets also the working directory for the application. This folder is used for temporary file uploads, log files, etc. and must be writeable. Location of this directory depends on the operating system: - Windows: C:/ProgramData/SoftwareGroup/UnderTree/{implementation-name} - Linux: /var/lib/SoftwareGroup/UnderTree/{implementation-name} - MacOS: ~/Library/Application Support/SoftwareGroup/UnderTree/{implementation-name} ### Unit tests There are 2 ways of unit-testing a port: - specify steps as in integration tests. ```js require('ut-run').run({ main: require('..'), method: 'unit', config: { SqlPort: { allowQuery: true, connection: { server: 'utPortTestDbServer', database: 'ut-port-sql-test', user: 'utPortTestDbUser', password: 'utPortTestDbPassword' }, create: { user: 'utPortTestDbCreateUser', password: 'utPortTestDbCreatePassword' } } }, params: { steps: [ { method: 'SqlPort.query', name: 'exec', params: { query: 'SELECT 1 AS test', process: 'json' }, result: (result, assert) => { assert.true(Array.isArray(result.dataSet)); assert.equals(result.dataSet[0].test, 1); } } ] } }); ``` - Write arbitrary unit tests. If you don't want to use predefined steps but to write any type of tests in functional or snapshot manner then just omit the steps from the ut-run configuration object like this: ```js require('ut-run').run({ main: require('..'), method: 'unit', config: { SqlPort: { allowQuery: true, connection: { server: 'utPortTestDbServer', database: 'ut-port-sql-test', user: 'utPortTestDbUser', password: 'utPortTestDbPassword' }, create: { user: 'utPortTestDbCreateUser', password: 'utPortTestDbCreatePassword' } } }, params: { // or omit the entire params property // steps: [ // { // method: 'SqlPort.query', // name: 'exec', // params: { // query: 'SELECT 1 AS test', // process: 'json' // }, // result: (result, assert) => { // assert.true(Array.isArray(result.dataSet)); // assert.equals(result.dataSet[0].test, 1); // } // } // ] } }).then(async({serviceBus, stop}) => { // write arbitrary tests // call serviceBus.importMethod to invoke port methods // call stop() once done }); ``` ### Documentation Ut-run provides a bin script for automatic port configuration documentation. In order to generate a configuration documentation for a given port you need to add `ut-run`and `json-schema-to-markdown` as devDependencies and `ut-doc` as `doc` script in its `package.json`. E.g. ```json { "scripts": { "doc": "ut-run doc" }, "devDependencies": { "json-schema-to-markdown": "1.1.1", "ut-run": "10.17.0" } } ``` ### Examples Look in the [doc/examples](./doc/examples) folder for more examples. --- _Source: https://npm.io/package/ut-run · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._