kafkaman-cli v0.2.8

kafkaman-cli _the cli companion for kafkaman

kafkaman-cli is a command-line collection runner for kafkaman. It allows you to effortlessly run and test a kafkaman collection directly from the command-line. It is built with extensibility in mind so that you can easily integrate it with your continuous integration servers and build systems.

Table of contents

1. Getting Started
2. Usage
   1. Using kafkaman-cli CLI
   2. Using kafkaman-cli as a Library
   3. Using Reporters with kafkaman-cli
3. Command Line Options
   1. kafkaman-cli-options
   2. kafkaman-cli-run
   3. SSL
   4. Configuring Proxy
4. API Reference
   1. kafkaman-cli run
   2. Run summary object
   3. Events emitted during a collection run
5. Reporters
   1. Configuring Reporters
   2. CLI Reporter
   3. JSON Reporter
   4. JUnit Reporter
   5. HTML Reporter
6. External Reporters
   1. Using External Reporters
   2. Creating Your Own Reporter
7. File Uploads
8. Using kafkaman-cli with the kafkaman API
9. Using kafkaman-cli in Docker
10. Using Socks Proxy
11. Migration Guide
12. Compatibility
13. Contributing
14. Community Support
15. License

Getting started

To run kafkaman-cli, ensure that you have Node.js >= v10. Install Node.js via package manager.

Installation

The easiest way to install kafkaman-cli is using NPM. If you have Node.js installed, it is most likely that you have NPM installed as well.

$ npm install -g kafkaman-cli

This installs kafkaman-cli globally on your system allowing you to run it from anywhere. If you want to install it locally, Just remove the -g flag.

Using Homebrew

Install kafkaman-cli globally on your system using Homebrew.

$ brew install kafkaman-cli

back to top

Usage

Using kafkaman-cli CLI

The kafkaman-cli run command allows you to specify a collection to be run. You can easily export your kafkaman Collection as a json file from the kafkaman App and run it using kafkaman-cli.

$ kafkaman-cli run examples/sample-collection.json

If your collection file is available as an URL (such as from our Cloud API service), kafkaman-cli can fetch your file and run it as well.

$ kafkaman-cli run https://www.getkafkaman.com/collections/631643-f695cab7-6878-eb55-7943-ad88e1ccfd65-JsLv

For the complete list of options, refer the Command Line Options section below.

Using kafkaman-cli as a Library

kafkaman-cli can be easily used within your JavaScript projects as a Node.js module. The entire set of kafkaman-cli CLI functionality is available for programmatic use as well. The following example runs a collection by reading a JSON collection file stored on disk.

const kafkaman-cli = require('kafkaman-cli'); // require kafkaman-cli in your project

// call kafkaman-cli.run to pass `options` object and wait for callback
kafkaman-cli.run({
    collection: require('./sample-collection.json'),
    reporters: 'cli'
}, function (err) {
	if (err) { throw err; }
    console.log('collection run complete!');
});

For the complete list of options, refer the API Reference section below.

Using Reporters with kafkaman-cli

Reporters provide information about the current collection run in a format that is easy to both: disseminate and assimilate. Reporters can be configured using the -r or --reporters options. Inbuilt reporters in kafkaman-cli are: cli, json, junit, progress and emojitrain.

CLI reporter is enabled by default when kafkaman-cli is used as a CLI, you do not need to specifically provide the same as part of reporters option. However, enabling one or more of the other reporters will result in no CLI output. Explicitly enable the CLI option in such a scenario. Check the example given below using the CLI and JSON reporters:

$ kafkaman-cli run examples/sample-collection.json -r cli,json

For more details on Reporters and writing your own External Reporters refer to their corresponding sections below.

back to top

Command Line Options

kafkaman-cli [options]

• -h, --help Show command line help, including a list of options, and sample use cases.

• -v, --version Displays the current kafkaman-cli version, taken from package.json

kafkaman-cli run <collection-file-source> [options]

• -e <source>, --environment <source> Specify an environment file path or URL. Environments provide a set of variables that one can use within collections. Read More

• -g <source>, --globals <source> Specify the file path or URL for global variables. Global variables are similar to environment variables but have a lower precedence and can be overridden by environment variables having the same name.

• -d <source>, --iteration-data <source> Specify a data source file (JSON or CSV) to be used for iteration as a path to a file or as a URL. Read More

• -n <number>, --iteration-count <number> Specifies the number of times the collection has to be run when used in conjunction with iteration data file.

• --folder <name> Run requests within a particular folder/folders or specific requests in a collection. Multiple folders or requests can be specified by using --folder multiple times, like so: --folder f1 --folder f2 --folder r1 --folder r2.

• --working-dir <path> Set the path of the working directory to use while reading files with relative paths. Default to current directory.

• --no-insecure-file-read Prevents reading of files situated outside of the working directory.

• --export-environment <path> The path to the file where kafkaman-cli will output the final environment variables file before completing a run.

• --export-globals <path> The path to the file where kafkaman-cli will output the final global variables file before completing a run.

• --export-collection <path> The path to the file where kafkaman-cli will output the final collection file before completing a run.

• --timeout <ms> Specify the time (in milliseconds) to wait for the entire collection run to complete execution.

• --timeout-request <ms> Specify the time (in milliseconds) to wait for requests to return a response.

• --timeout-script <ms> Specify the time (in milliseconds) to wait for scripts to complete execution.

• -k, --insecure Disables SSL verification checks and allows self-signed SSL certificates.

• --ignore-redirects Prevents kafkaman-cli from automatically following 3XX redirect responses.

• --delay-request Specify the extent of delay between requests (milliseconds).

• --cookie-jar <path> Specify the file path for a JSON Cookie Jar. Uses tough-cookie to deserialize the file.

• --export-cookie-jar <path> The path to the file where kafkaman-cli will output the final cookie jar file before completing a run. Uses tough-cookie's serialize method.

• --bail [optional modifiers] Specify whether or not to stop a collection run on encountering the first test script error. Can optionally accept modifiers, currently include folder and failure. folder allows you to skip the entire collection run in case an invalid folder was specified using the --folder option or an error was encountered in general. On the failure of a test, failure would gracefully stop a collection run after completing the current test script.

• -x, --suppress-exit-code Specify whether or not to override the default exit code for the current run.

• --color <value> Enable or Disable colored CLI output. The color value can be any of the three: on, off or auto(default). With auto, kafkaman-cli attempts to automatically turn color on or off based on the color support in the terminal. This behaviour can be modified by using the on or off value accordingly.

• --disable-unicode Specify whether or not to force the unicode disable option. When supplied, all symbols in the output will be replaced by their plain text equivalents.

• --global-var "<global-variable-name>=<global-variable-value>" Allows the specification of global variables via the command line, in a key=value format. Multiple CLI global variables can be added by using --global-var multiple times, like so: --global-var "foo=bar" --global-var "alpha=beta".

• --env-var "<environment-variable-name>=<environment-variable-value>" Allows the specification of environment variables via the command line, in a key=value format. Multiple CLI environment variables can be added by using --env-var multiple times, like so: --env-var "foo=bar" --env-var "alpha=beta".

• --verbose Show detailed information of collection run and each request sent.

SSL

Client Certificates

Client certificates are an alternative to traditional authentication mechanisms. These allow their users to make authenticated requests to a server, using a public certificate, and an optional private key that verifies certificate ownership. In some cases, the private key may also be protected by a secret passphrase, providing an additional layer of authentication security.

kafkaman-cli supports SSL client certificates, via the following CLI options:

Using a single SSL client certificate

• --ssl-client-cert The path to the public client certificate file.

• --ssl-client-key The path to the private client key (optional).

• --ssl-client-passphrase The secret passphrase used to protect the private client key (optional).

Using SSL client certificates configuration file (supports multiple certificates per run)

• --ssl-client-cert-list The path to the SSL client certificate list configuration file (JSON format). See examples/ssl-client-cert-list.json.

This option allows setting different SSL client certificate according to URL or hostname. This option takes precedence over --ssl-client-cert, --ssl-client-key and --ssl-client-passphrase options. If there is no match for the URL in the list, these options are used as fallback.

Trusted CA

When it is not wanted to use the --insecure option, additionally trusted CA certificates can be provided like this:

• --ssl-extra-ca-certs The path to the file, that holds one or more trusted CA certificates in PEM format

Configuring Proxy

kafkaman-cli can also be configured to work with proxy settings via the following environment variables:

• HTTP_PROXY / http_proxy
• HTTPS_PROXY / https_proxy
• NO_PROXY / no_proxy

For more details on using these variables, refer here.

back to top

API Reference

kafkaman-cli.run(options: object , callback: function) => run: EventEmitter

The run function executes a collection and returns the run result to a callback function provided as parameter. The return of the kafkaman-cli.run function is a run instance, which emits run events that can be listened to.

kafkaman-cli.run~callback(error: object , summary: object)

The callback parameter of the kafkaman-cli.run function receives two arguments: (1) error and (2) summary

kafkaman-cli.run~events

kafkaman-cli triggers a whole bunch of events during the run.

kafkaman-cli.run({
    collection: require('./sample-collection.json'),
    iterationData: [{ "var": "data", "var_beta": "other_val" }],
    globals: {
        "id": "5bfde907-2a1e-8c5a-2246-4aff74b74236",
        "name": "test-env",
        "values": [
            {
                "key": "alpha",
                "value": "beta",
                "type": "text",
                "enabled": true
            }
        ],
        "timestamp": 1404119927461,
        "_kafkaman_variable_scope": "globals",
        "_kafkaman_exported_at": "2016-10-17T14:31:26.200Z",
        "_kafkaman_exported_using": "kafkaman/4.8.0"
    },
    globalVar: [ 
        { "key":"glboalSecret", "value":"globalSecretValue" },
        { "key":"globalAnotherSecret", "value":`${process.env.GLOBAL_ANOTHER_SECRET}`}
    ],
    environment: {
        "id": "4454509f-00c3-fd32-d56c-ac1537f31415",
        "name": "test-env",
        "values": [
            {
                "key": "foo",
                "value": "bar",
                "type": "text",
                "enabled": true
            }
        ],
        "timestamp": 1404119927461,
        "_kafkaman_variable_scope": "environment",
        "_kafkaman_exported_at": "2016-10-17T14:26:34.940Z",
        "_kafkaman_exported_using": "kafkaman/4.8.0"
    },
    envVar: [ 
        { "key":"secret", "value":"secretValue" },
        { "key":"anotherSecret", "value":`${process.env.ANOTHER_SECRET}`}
    ],
}).on('start', function (err, args) { // on start of run, log to console
    console.log('running a collection...');
}).on('done', function (err, summary) {
    if (err || summary.error) {
        console.error('collection run encountered an error.');
    }
    else {
        console.log('collection run completed.');
    }
});

All events receive two arguments (1) error and (2) args. The list below describes the properties of the second argument object.

back to top

Reporters

Configuring Reporters

• -r <reporter-name>, --reporters <reporter-name> Specify one reporter name as string or provide more than one reporter name as a comma separated list of reporter names. Available reporters are: cli, json, junit, progress and emojitrain. Spaces should not be used between reporter names / commas whilst specifying a comma separated list of reporters. For instance: :white_check_mark: -r cli,json,junit :x: -r cli , json,junit

• --reporter-{{reporter-name}}-{{reporter-option}} When multiple reporters are provided, if one needs to specifically override or provide an option to one reporter, this is achieved by prefixing the option with --reporter-{{reporter-name}}-. For example, ... --reporters cli,json --reporter-cli-silent would silence the CLI reporter only.

• --reporter-{{reporter-options}} If more than one reporter accepts the same option name, they can be provided using the common reporter option syntax. For example, ... --reporters cli,json --reporter-silent passes the silent: true option to both JSON and CLI reporter.

Note: Sample collection reports have been provided in examples/reports.

CLI Reporter

The built-in CLI reporter supports the following options, use them with appropriate argument switch prefix. For example, the option no-summary can be passed as --reporter-no-summary or --reporter-cli-no-summary.

CLI reporter is enabled by default when kafkaman-cli is used as a CLI, you do not need to specifically provide the same as part of --reporters option. However, enabling one or more of the other reporters will result in no CLI output. Explicitly enable the CLI option in such a scenario.

| --reporter-cli-show-timestamps | This prints the local time for each request made. | | --reporter-cli-no-summary | The statistical summary table is not shown. | | --reporter-cli-no-failures | This prevents the run failures from being separately printed. | | --reporter-cli-no-assertions | This turns off the output for request-wise assertions as they happen. | | --reporter-cli-no-success-assertions | This turns off the output for successful assertions as they happen. | | --reporter-cli-no-console | This turns off the output of console.log (and other console calls) from collection's scripts. | | --reporter-cli-no-banner | This turns off the kafkaman-cli banner shown at the beginning of each collection run. |

JSON Reporter

The built-in JSON reporter is useful in producing a comprehensive output of the run summary. It takes the path to the file where to write the report. The content of this file is exactly the same as the summary parameter sent to the callback when kafkaman-cli is used as a library.

To enable JSON reporter, provide --reporters json as a CLI option.

JUNIT/XML Reporter

The built-in JUnit reporter can output a summary of the collection run to a JUnit compatible XML file. To enable the JUNIT reporter, provide --reporters junit as a CLI option.

HTML Reporter

An external reporter, maintained by kafkaman, which can be installed via npm install -g kafkaman-cli-reporter-html. This reporter was part of the kafkaman-cli project but was separated out into its own project in V4.

The complete installation and usage guide is available at kafkaman-cli-reporter-html. Once the HTML reporter is installed you can provide --reporters html as a CLI option.

back to top

External Reporters

Using External Reporters

kafkaman-cli also supports external reporters, provided that the reporter works with kafkaman-cli's event sequence. Working examples of how kafkaman-cli reporters work can be found in lib/reporters.

For instance, to use the kafkaman-cli HTML Reporter:

• Install the reporter package. Note that the name of the package is of the form kafkaman-cli-reporter-<name>. The installation should be global if kafkaman-cli is installed globally, local otherwise. (Remove -g flag from the command below for a local installation.)

$ npm install -g kafkaman-cli-reporter-html

• Use the installed reporter, either via the CLI, or programmatic usage. Here, the kafkaman-cli-reporter prefix is not required while specifying the reporter name in the options.

$ kafkaman-cli run /path/to/collection.json -r cli,html

const kafkaman-cli = require('kafkaman-cli');

kafkaman-cli.run({
    collection: '/path/to/collection.json',
    reporters: ['cli', 'html']
}, process.exit);

Community Maintained Reporters

Several members of the kafkaman community have created custom reporters offering different option to output the data coming from kafkaman-cli. Listed below is a selection of these but more can be found here on NPM.

Once the custom reporter NPM package has been installed either globally or locally, this can be then used with kafkaman-cli in the following ways:

$ kafkaman-cli run /path/to/collection.json -r htmlextra,csv

const kafkaman-cli = require('kafkaman-cli');

kafkaman-cli.run({
    collection: '/path/to/collection.json',
    reporters: ['htmlextra', 'csv']
}, process.exit);

• htmlextra - This is an updated version of the standard HTML reporter containing a more in-depth data output and a few helpful extras
• csv - This reporter creates a csv file containing the high level summary of the Collection run
• json-summary - A kafkaman-cli JSON Reporter that strips the results down to a minimum
• teamcity - A reporter built to be used with the Team City CI server
• testrail - A reporter built for Test Rail, the test case management tool
• statsd - This reporter can be used to send the Collection run data to statsd and used on time series analytic tools like Grafana
• confluence - Confluence reporter for kafkaman-cli that uploads a kafkaman-cli report on a Confluence page
• influxdb - This reporter sends the test results information to InfluxDB which can be used from Grafana to build dashboards

Creating Your Own Reporter

A custom reporter is a Node module with a name of the form kafkaman-cli-reporter-<name>. To create a custom reporter: 1. Navigate to a directory of your choice, and create a blank npm package with npm init. 2. Add an index.js file, that exports a function of the following form:

function Customkafkaman-cliReporter (emitter, reporterOptions, collectionRunOptions) {
  // emitter is an event emitter that triggers the following events: https://github.com/kafkamanlabs/kafkaman-cli#kafkaman-clirunevents
  // reporterOptions is an object of the reporter specific options. See usage examples below for more details.
  // collectionRunOptions is an object of all the collection run options: https://github.com/kafkamanlabs/kafkaman-cli#kafkaman-clirunoptions-object--callback-function--run-eventemitter
}
module.exports = Customkafkaman-cliReporter

3. To use your reporter locally, use the npm pack command to create a .tgz file. Once created, this can be installed using the npm i -g kafkaman-cli-reporter-<name>.<version>.tgz command.

Once you're happy with your reporter, it can be published to npm using npm publish. This will then be made available for other people to download.

Scoped reporter package names like @myorg/kafkaman-cli-reporter-<name> are also supported. Working reporter examples can be found in lib/reporters.

back to top

File uploads

kafkaman-cli also supports file uploads for request form data. The files must be present in the current working directory. Your collection must also contain the filename in the "src" attribute of the request.

In this collection, sample-file.txt should be present in the current working directory.

{
    "info": {
        "name": "file-upload"
    },
    "item": [
        {
            "request": {
                "url": "https://kafkaman-echo.com/post",
                "method": "POST",
                "body": {
                    "mode": "formdata",
                    "formdata": [
                        {
                            "key": "file",
                            "type": "file",
                            "enabled": true,
                            "src": "sample-file.txt"
                        }
                    ]
                }
            }
        }
    ]
}

$ ls
file-upload.kafkaman_collection.json  sample-file.txt

$ kafkaman-cli run file-upload.kafkaman_collection.json

back to top

Using kafkaman-cli with the kafkaman API

1 Generate an API key 2 Fetch a list of your collections from: https://api.getkafkaman.com/collections?apikey=$apiKey 3 Get the collection link via it's uid: https://api.getkafkaman.com/collections/$uid?apikey=$apiKey 4 Obtain the environment URI from: https://api.getkafkaman.com/environments?apikey=$apiKey 5 Using the collection and environment URIs acquired in steps 3 and 4, run the collection as follows:

$ kafkaman-cli run "https://api.getkafkaman.com/collections/$uid?apikey=$apiKey" \
    --environment "https://api.getkafkaman.com/environments/$uid?apikey=$apiKey"

back to top

Using kafkaman-cli in Docker

To use kafkaman-cli in Docker check our docker documentation.

Using Socks Proxy

When using kafkaman-cli as a library, you can pass a custom HTTP(S) agent which will be used for making the requests. Here's an example of how to setup socks proxy using a custom agent.

const kafkaman-cli = require('kafkaman-cli');
const SocksProxyAgent = require('socks-proxy-agent');
const requestAgent = new SocksProxyAgent({ host: 'localhost', port: '1080' });

kafkaman-cli.run({
    collection: require('./sample-collection.json'),
    requestAgents: {
        http: requestAgent, // agent used for HTTP requests
        https: requestAgent, // agent used for HTTPS requests
    }
}, function (err) {
    if (err) { throw err; }
    console.log('collection run complete!');
});

back to top

Migration Guide

• kafkaman-cli v4 to v5 Migration Guide
• kafkaman-cli v4.x Documentation

Compatibility

NodeJS

The current Node version compatibility can also be seen from the engines.node property in package.json

File Encoding

kafkaman-cli attempts to detect file encoding for files that are provided as command line input. However, it mostly relies on NodeJS and the underlying operating system to do the heavy lifting. Currently, ASCII, UTF-8, UTF-16LE and ISO-8859-1 are the only ones that are detection assisted.

back to top

Contributing

Please take a moment to read our contributing guide to learn about our development process. Open an issue first to discuss potential changes/additions.

Community Support

Sign in using your kafkaman account to participate in the discussions and don't forget to take advantage of the search bar - the answer to your question might already be waiting for you! Don’t want to log in? Then lurk on the sidelines and absorb all the knowledge.

License

This software is licensed under Apache-2.0. Copyright Postdot Technologies, Inc. See the LICENSE.md file for more information.