![\"@lopidio\"](\"https://avatars0.githubusercontent.com/u/862212?s=60&v=4\")
\n![\"\"](\"https://github.githubassets.com/images/spinners/octocat-spinner-32.gif\")
\n ![\"npm\"](\"https://img.shields.io/npm/dt/enqueuer.svg\")
![\"Build](\"https://travis-ci.org/enqueuer-land/enqueuer.svg?branch=master\")
![\"Greenkeeper](\"https://badges.greenkeeper.io/enqueuer-land/enqueuer.svg\")
![\"Known](\"https://snyk.io/test/npm/enqueuer/badge.svg\"){kind=icon}
![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
![\"enqueuerlogo\"](\"https://raw.githubusercontent.com/enqueuer-land/enqueuer/master/docs/images/fullLogo1.png\" "\\"Enqueuer")
Want to ensure that a user journey which involves several steps with different protocols is working properly?\nHave you ever struggled with testing multi protocol flows?\nDepending services have become a pain?\nDon't you worry anymore. Enqueuer is what you're looking for.
\nWhat it is
\nIt's not just an integration testing tool. It is a platform that provides the following capabilities:
- \n
- Support for many protocols out of the box \n
- Chainable message flows \n
- Easily mock numerous services to alleviate the headaches of functional and integration tests \n
- Friendly for developers and non developers \n
- Built in assertion library to verify response data coming from/going to your services \n
- Easily extensible behavior through third party plugins, including your own custom ones \n
- CLI is easy to add to your team's existing CI pipelines \n
- Act and react on your system under test \n
- Place tests front and center \n
Welcome to the enqueuer world.
\ninstall it
\nFirst things first, let's get the enqueuer installed on your machine.
\n$ npm install --global enqueuer\nAlright, it's time to create a requisition file.\nSomething like:
\n#enqueuer-repo-hit.yml\npublishers:\n- type: http\n url: https://github.com/enqueuer-land/enqueuer\n onMessageReceived:\n assertions:\n - expect: statusCode\n toBeEqualTo: 200\nPretty simple, hum? Small and concise, how it should be!\nRun it:
\n$ enqueuer enqueuer-repo-hit.yml\nWhat if I want to mock a http server and hit it at the same time, you may ask. Not a big deal for enqueuer lovers:
\nname: readme self-test\npublishers:\n- type: http\n url: http://localhost:9085/readme-example\n method: POST\n payload: does enqueuer rock?\n onMessageReceived:\n script: doubleStatus = statusCode * 2\n assertions:\n - expect: body\n toBeEqualTo: `mock response`\n - expect: doubleStatus\n toBeGreaterThan: 300\nsubscriptions:\n- type: http\n name: mock endpoint\n endpoint: /readme-example\n port: 9085\n method: POST\n response:\n status: 200\n payload: mock response\n onMessageReceived:\n assertions:\n - expect: message.body\n toContain: `enqueuer`\n - name: failing test\n expectToBeTruthy: false\nNote that the second subscription assertion is a failing one. By running this example, we get this:
\n$ nqr http-self-test.yml\n [FAIL] readme self-test 6 tests passing of 7 (85.71%) ran in 37ms\n [FAIL] enqueuer 6 tests passing of 7 (85.71%) ran in 42ms\n enqueuer › readme self-test › mock endpoint › failing test\n Expecting 'false' to be true. Received: false\nI told you it was simple.\nNow, let's say you want to mix different protocols to test a bit more complex flow.\nHow about publishing an amqp message and making sure that, once a service consumes that message an endpoint of your is hit?\nIn order to achieve that, we have to make use of a plugin, given that amqp support is provided by a plugin.\nIn this scenario, we're talking about the amqp plugin.\nOnce we get this plugin installed we are able to create and run files like this:
\npublishers:\n- type: amqp\n payload: 123456\n exchange: enqueuer.exchange\n routingKey: enqueuer.readme.routing.key\nsubscriptions:\n- type: http\n endpoint: /polyglot-flow\n port: 8080\n method: GET\n response:\n status: 200\n payload: polyglot message\n onMessageReceived:\n assertions:\n - expect: message.body\n toContain: 123456\nNow go nuts!\nIt's all yours. Have fun.\nIf you want more examples about http, consider looking at this test.\nCheck this out, you'll find countless examples.\nCertainly one is what you need.
if you need more
\n$ nqr -h\nUsage: nqr [options] <test-file> [other-test-files...]\n\nTake a look at the full documentation: https://enqueuer.com\n\nOptions:\n -v, --version output the version number\n -b, --verbosity <level> set verbosity (default: \"warn\")\n -c, --config-file <path> set configurationFile\n -e, --parsers-list [parser] list available object parsers\n -f, --formatters-description [formatter] describe report formatters\n -o, --stdout-requisition-output add stdout as requisition output\n -m, --max-report-level-print <level> set max report level print\n -p, --protocols-description [protocol] describe protocols\n -u, --loaded-modules-list list loaded modules\n -t, --tests-list list available tests assertions\n -s, --store [store] add variables values to this session (default: [])\n -l, --add-plugin [plugin] add plugin (default: [])\n -a, --add-file <file> add file to be tested (default: [])\n -A, --add-file-and-ignore-others <file> add file to be tested and ignore others (default: [])\n -h, --help output usage information\n\nExamples:\n $ nqr --config-file config-file.yml --verbosity error --store key=value\n $ enqueuer -c config-file.yml test-file.yml --add-file another-test-file.yml -b info\n $ enqueuer test-file.yml --store someKey=true --store someOtherKey=false\n $ nqr --protocols-description -s key=value\n $ nqr -t expect\n $ nqr -l my-enqueuer-plugin-name -p plugin-protocol\n $ nqr -p http\n $ nqr --formatters-description json\n\n
Components
\nIn order to accomplish more than just hitting enqueuer's repo or doing a quick self http hit, there are a few things that you'll probably need to know.\nDon't worry, it's not too much and, as mentioned earlier, there is a lot of examples here, just in case.\nThere are only three important component concepts: requisitions, publishers and subscriptions.\nThey work along with each other and are responsible for the full behavior of enqueuer.
\nrequisition
\nTest scenario description. It tells what, when, and how test your applications and services.\nPicture it as if it was a collection of publishers, subscriptions and other requisitions.\nIt helps because this is exactly what it is.\nAs the others components, it has some attributes. All of them are optionals. And it supports multi-level test scenarios out of the box. Yeap, go as recursive as you want.\nEvery test file is a requisition.\nYou don't know some of these attributes values yet? Don't worry, just put a variable there and let enqueuer replace it with the value you set later.\nVariable replacements are available through the entire requisition.
\nrequisition attributes
\nThese are the requisition attributes:
\nname
\nDescribes what the requisition is suppose to do.\nDefaults to requisition index.
name: requisition action\ntimeout
\nDefaults to 5000.\nSets in milliseconds how long the requisition waits to expire.\nSet to zero or less than zero to run it endlessly.
timeout: 3000\ndelay
\nDefaults to 0. Sets in milliseconds how long the test waits before starting. Check this to get the full idea.
delay: 0\niterations
\nDefaults to 1. Sets how many times this test will be executed. Check this and this to get the full idea.
iterations: 3\nignore
\nDefaults to false. Tells to enqueuer that this requisitions should be skipped. Check this to see it working.
ignore: true\nparallel
\nDefaults to false. Immediate children requisitions should be executed in parallel mode.\nTake a look at this to see it working.
parallel: true\nimport
\nAllows requisition to be dynamically defined, be it by loading an external file or creating dynamically by other requisitions. Want to reuse the same requisition multiple times? This is you you need.\nTake a look at this to behold this feature.
import: path/to/another/requisition/file\npublishers
\nList of publishers
publishers:\n- name: some publisher name\n type: http\n- type: tcp\nsubscriptions
\nList of subscriptions
subscriptions:\n- name: some subscription name\n type: udp\n- name: another subscription name\n type: file\nrequisitions
\nA list of child scenarios. List of requisitions.\nCheck this example, it may help.
requisitions:\n- name: some requisition name\n iterations: 2\n- name: another requisition name\n delay: 200\nevents
\nAvailable events are described here. A requisition object is available to access and change its attributes.
name: my name\nonInit:\n script: requisition.delay = 3000;\n assertions:\n - expectToBeDefined: requisition.name\nonFinish: \n assertions:\n - expectToBeDefined: requisition.name\npublisher
\nA publisher action is triggered by enqueuer itself. It acts whereas a subscription reacts.\nIt publishes something, it writes, it enqueues, hits and endpoint... These kinds of actions.
\npublisher attributes
\nEvery publisher has its own properties, depending on its protocol and implementation.\nThe built-in http publisher implementation, for instance, demands a url, a method, and a payload, if the method is not a GET.\nOn the other hand, the built-in tcp publisher implementation requires a serverAddress and a port.\nThese are the publisher attributes:
name
\nDefaults to publisher index.\nDescribes what the publisher is supposed to do.
name: publisher action\ntype
\nMandatory. Key tag to identify which publisher will be instantiated
type: http\npayload
\nSince a publisher usually publishes something, it's very likely you have to set a value here.\nThe message itself that will be send through this protocol. Be it a string, a number, a boolean value or even whole objects.
payload: value\nignore
\nDefaults to false. Tells to enqueuer that this publisher should be skipped. Check this to see it working.
ignore: true\nevents
\nAvailable events are described here. A publisher object is available to access and change its attributes.\nDepending on the protocol and its implementation, such as http and tcp, there may exist a onMessageReceived event and a special object given message.\nOn the other hand, an asynchronous protocol, like: udp and amqp, usually does not provide it.
onInit:\n script: publisher.ignore = false\n assertions:\n - expectToBeDefined: publisher.type\nonMessageReceived: #Provided in synchronous protocols \n assertions:\n - expectToBeDefined: message\nonFinish: \n assertions:\n - expectToBeDefined: publisher.type\nsubscription
\nA subscription is an \"under demand\" event. It reacts whereas a publisher acts.\nIt consumes something, it reads, it dequeues, gets hit... These kinds of actions.\nThis means that it is not triggered by enqueuer itself.\nRather than that, enqueuer waits on an external event to be triggered and then it asserts against the message that was passed to the subscription.
\nsubscription attributes
\nEvery subscription has its own properties, depending on its protocol and implementation.\nThe built-in http subscription implementation, for instance, demands an endpoint, a method, and a port, if the method is not a GET.\nOn the other hand, the built-in tcp subscription implementation requires only a port.
These are the subscription attributes:
\nname
\nDefaults to subscription index.\nDescribes what the subscription is supposed to do.
name: subscription action\ntype
\nMandatory. Key tag to identify which subscription will be instantiated
type: http\navoid
\nIdentifies whether or not this subscription should not receive any message. Defaults to false.\nIf set and a message is received a failing test will be generated.\nTake a look at this to see it working.\nOn the other hand, when it's false and no message is received in a given timeout. The subscription is valid.
avoid: false\ntimeout
\nSets in milliseconds how long the subscription waits to expire. Defaults to 3000.\nSet to zero or less than zero to run it endlessly.
timeout: 3000\nignore
\nDefaults to false. Tells to enqueuer that this subscription should be skipped. Check this to see it working.
ignore: true \nevents
\nAvailable events are described here. A subscription object is available to access and change its attributes.
onInit:\n script: subscription.avoid = false;\n assertions:\n - expectToBeDefined: subscription.type\nonMessageReceived: \n assertions:\n - expectToBeDefined: message\nonFinish: \n assertions:\n - expectToBeDefined: subscription.type\n\n
Event
\nEvents are hook methods executed by enqueuer when an action occurs on publishers, subscriptions or requisitions.\nThis is where you'll write your tests. In its assertions field.\nDepending on the event's owner, there may be a variable called publisher, subscription or requisition.\nYou're free to explore them however you want, even doing things like this:
publisher.parent.subscriptions[0].timeout = 1000;\nhooks
\nThere are three hook events available:
\nonInit
\nAvailable in requisitions, publishers and subscriptions. It gets executed as soon as the test is initialized.
onFinish
\nAvailable in requisitions, publishers and subscriptions. It gets executed when the test is about to finish.\nAs available parameter, an elapsedTime variable is given, counting every milliseconds since the instantiation of this component.
onMessageReceived
\nAvailable in every subscription and in publishers that provide synchronous properties.\nIt gets executed when the subscription or publisher receives a message.\nA message object is available having all of attributes returned from the received message.\nDepending on the protocol implementation, there'll be additional objects to this hook.\nFor instance, in the built-in http publisher implementation, there's a statusCode, headers and a body among others, and the subscription implementation has body, query, params and headers , among other variables.\nelapsedTime is also available here, counting every milliseconds since the instantiation of this component.
fields
\nEvery hook object has 3 properties:
\nscript
\nJavascript code snippet executed when the event is triggered.\nYeah, I mean it. See it it by yourself.\nBut be careful, with great power comes great responsibility.
store
\nData to be persisted across requisitions.
assertions
\nArray of assertions.\nRun $ nqr -t to see available ones.\nConsider looking at this test example.\nOf course, just like almost everything else in enqueuer world, you can extend this available list using some plugin.\nYou can check them out or even write your own.
onInit:\n script: variableIdentifier = 'string value'\n\n assertions:\n - expect: variableIdentifier\n toBeEqualTo: `string value`\n\nonMessageReceived:\n script: |-\n message += 3;\n console.log(`Message received plus 3 is: ${message}`);\n\n store:\n key: message\n\n assertions:\n - name: anyValue #optional\n expect: message\n toBeEqualTo: store.key\n - expect: message + 3\n toBeGreaterThan: 3\nevent example
\nCheck this test file to see it in practice.
\n\n
Requisition Flow
\nNow that you know what are requisitions, publishers, subscriptions and events. How about seeing how they interact with each other in a fancier way?
\n![\"enqueuerInstanceFlow\"](\"https://raw.githubusercontent.com/enqueuer-land/enqueuer/master/docs/images/nqrFlow.png\" "\\"Enqueuer")
\n
Configuration File
\nTo save yourself some time, a configuration file may be used.\nConfiguration files tell enqueuer which tests will be executed, log-level, and which output test report files should be generated.\nThis file tells how enqueuer should be executed.\nTo run enqueuer with the configuration:
\n$ nqr -c path/to/configuration/file.yml\nor
\n$ nqr --config-file path/to/configuration/file.yml\nattributes
\nThese are the configuration file attributes:
\nfiles
\nRequisition file names or glob. Enqueuer runs every file that matches an element value.
files:\n- 1.yml\n- 2.yml\n- *.json\nparallel
\nDefaults to false. Requisition files should be executed in parallel mode. The requisition file itself is still sequential, but the files are executes in parallel.
parallel: true\nlog-level
\nDefaults to warning. Defines how information are logged in the console. Accepted values are: trace; debug; info; warning (default); error; and fatal.
log-level: trace\nmax-report-level-print
\nDefaults to 1. The deepest level of report to be printed to the console.
max-report-level-print: 2\nplugins
\nList of in plugins used by the test scenarios. You can check them out or write your own.
plugins:\n- enqueuer-plugin-amqp \n- enqueuer-plugin-ws \n- enqueuer-plugin-mqtt\n- enqueuer-plugin-html-report\noutputs
\nOnce enqueuer runs every execution, it compiles a summary and sends it to every publisher listed in output.\nAn important thing to note is that every available report publisher is available here.\nYes, it means that you are able to send this report through http, tcp, etc. or through a plugin one or a custom one.\nYou can run $ nqr -p to check available report publishers installed.\nAnother important thing to note is the format value. By default a json summary is generated, but you can change it to whatever format you would like, such as: Xunit, html\nYou can run $ nqr -f to check available installed formats or even write your own
outputs:\n- type: file\n format: json (default)\n filename: output/examples.json\n- type: file\n format: yml\n filename: output/examples.yml\n- type: standard-output (default)\n format: console\nstore
\nValues defined here use the 'key: value' pattern and are available to every test scenario throughout the entire execution
store:\n variableKey: \"my value\" # Defines 'variableKey' key and its value 'my value'. \n \n 'separated key': 6\n \n object: # You can even define whole objects here:\n first: first value\n second:\n nested: thing\nexample
\nHere's a complete example of a configuration file.
\n\n
Variables
\nProviding power and flexibility, enqueuer allows you to use variables placeholder replacement.\nThat's why there is a store field and you'll see a lot of << and {{ being used in the examples files.\nIt works as simple as this:
name: my name is <<variableKey>>\nEvery time enqueuer sees these kind of notations, it searches in its store for a key/value pair like:
\nvariableKey: `enqueuer`\nThen, when enqueuer parses the original map, it gets translated to this:
\nname: my name is enqueuer\nBy default, every ENV_VAR set is loaded automatically to the store. Check this example.
\nset a variable
\nThere are a few ways to set a value in the store.
\nconfiguration file
\nConfiguration file store object. Set it as you wish, as you can see here
\ncommand line
\nA command line argument using the key=value format. This way:
$ nqr --store key=value -s anotherVariable=true\nevent
\nDynamically set it through any event.\nBe it in its script field or straight through its store field.\nBoth ways work:
\nonInit:\n script: store.key = 123;\n store:\n anotherKey: `another Value` \nuse a variable
\nThere are two ways two use a variable:
\nnon js code snippet
\nThe easiest one is to type <<variableKey>> or {{variableKey}} where you want it to be replaced in a test file, as you can see here
js code snippet
\nUsing the store object. It's attributes are the keys and their values are their respective values.\nTherefore, you're free to use store.variableKey, console.log(store.variableKey); or console.log(2 * store['separated key']); and get them.\nLike this one.
variables example
\nCheck out this test example test to see it working.
\n\n
Content File Injection
\nYou are able to inject file content into a requisition/publisher/subscription field.
\nfile: <<file://path/to/file.txt>>\nOther than that, enqueuer can read it and parse its content as an object using this familiar syntax: <<tag://path/to/file?query=value&other=true>>.
requisition:\n json: <<json://path/to/file.json>>\n yml: <<yml://path/to/file.yml>>\n csv: <<csv://path/to/file.csv?header=true&delimiter=;>>\n file: <<file://path/to/file.txt>>\nOnce the object is parsed, your free to use it as a regular object in any event
\nonInit:\n script: console.log(requisition.yml.deep.field);\nonFinish:\n assertions:\n - expect: json.key\n toBeEqualTo: csv[0].key\nIt get's event better.\nDue its fantastic plugin architecture design, you can extend its default modules and use any of these plugins or event write your own to parse however you want.\nThe built-in modules for object parsers are: json, yml, csv and file.\nRun $ nqr -e to see available ones.
example
\nCheck out this test example test to get a full picture of it.
\n\n
Plugins
\nYou're probably aware by now but it doesn't hurt do emphasize it: enqueuer provides an amazingly powerful plugin extensible architecture.\nIt has several plugins available, but if none of them pleases you, you're free to create your own.\nAlbeit you don't have to share the one you created, we encourage you to do so. Then go ahead and publish yours to npm and add it to our plugins list.
\nplugin types
\nSo far, you're able to extend enqueuer default behavior in four ways. Using a protocol plugin, an object parser plugin, an asserter plugin and using a report formatter plugin.
\nprotocol
\nA protocol plugin enables you to use a different publisher/subscription types.\nRun $ nqr -p [protocol-name] to get the full available list:
publishers: \n- name: custom\n- name: file\n- name: http\n messageReceivedParams: statusCode, statusMessage, body\n- name: stdout\n- name: tcp\n- ...\nsubscriptions: \n- name: custom\n- name: file\n messageReceivedParams: content, name, size, modified, created\n- name: http\n messageReceivedParams: headers, params, query, body\n- name: stdin\n- name: tcp\n messageReceivedParams: payload, stream\n- ...\nEach one listed above has a respective example in the examples folder.\nThis one, for instance, provides support for amqp protocol, so you can create this publisher and subscription:
\npublishers:\n- type: amqp\n payload: enqueuermaniac\n exchange: enqueuer.exchange\n routingKey: enqueuer.integration.test.routing.key\nsubscriptions:\n- type: amqp\n exchange: enqueuer.exchange\n routingKey: enqueuer.integration.test.routing.#\n onMessageReceived:\n assertions:\n - expect: payload\n toBeEqualTo: `enqueuermaniac`\nobject parser
\nAn object parser plugin enables you to read and parse files as you wish.\nThis test example demonstrates how to use it,\nRun $ nqr -e [object-parser-name] to check available ones:
parsers: \n- yml, yaml\n- json\n- file\n- csv\nThis one, for example, provides the ability to read xml files and inject their values like this:
\nxmlContent: <<xml://path/to/xml/file.xml>>\nasserter
\nAn asserter plugin provides you a nicely way to use different assertions than these built-in ones.
\nasserters: \n- expect: \n required: true\n type: string, array\n description: actual value\n not: \n required: false\n type: null\n description: negates\n toContain: \n required: true\n type: string, any\n description: element\nLooking at the asserter above, we can create assertions like these:
\nassertions:\n- expect: [`a`, 1, true]\n not:\n toContain: `b`\n- expect: [`a`, 1, true]\n toContain: 1\nRun $ nqr -t to get the full available list.\nConsider looking at this test example.
report formatter
\nA report formatter plugin gives you the ability to export enqueuer reports the way you want.\nRun $ nqr -f [formatter-name] to list available report formatters:
formatters: \n- console, stdout\n- json\n- yml, yaml\nConsider looking at the example of configuration file to see it in use.\nThis one, for instance, generates xUnit like reports from enqueuer's output.
\nplugin installation
\nIn order to enqueuer get awareness that you want to use a plugin, you have to tell it, right?\nYou can tell enqueuer to use a plugin in three different ways: using it as a command line argument, through the configuration file or letting enqueuer finding it in a default location.
\ncommand line
\nTell enqueuer to use your plugin through command line this way $ nqr -l <plugin-folder> -l <another-plugin-folder>.\nWhere plugin-folder and another-plugin-folder are the directories where the plugins are installed in.
configuration file
\nTell enqueuer to use your plugin through configuration file this way:
\nplugins: \n- plugin-folder\n- another-plugin-folder\nWhere plugin-folder and another-plugin-folder are the directories where the plugins are installed in.
\nimplicitly
\nWhen enqueuer runs, it looks for modules in .nqr folder in the home directory, a.k.a. ~/ folder in linux distributions.\nTherefore, if you run:
$ npm install --global enqueuer\n$ mkdir ~/.nqr\n$ cd ~/.nqr\n$ npm install enqueuer-plugin-amqp\n$ nqr -p amqp\nYou'll see that the enqueuer-plugin-amqp plugin will be loaded.\nEvery enqueuer compatible module gets implicitly loaded.\nIn order to be enqueuer compatible, a module has to have an entryPoint exported function in its main file and, in its package.json file, it has to have either 'enqueuer' or 'nqr' as keywords.
Stacker
\nLooking for a really really good looking an human error proof solution way of writing these requisition files?
\nConsider taking a look at stacker: open source, cross-platform, multi protocol client testing tool.\nThe official enqueuer's best friend forever. Do amazing things and change the world with enqueuer’s GUI!\nWith them, you create, manage and run requisitions and and see their results in a really nice way.\nSee this amazing beauty with your own eyes to get an idea of how it works:
![\"screenshot-passing\"](\"https://raw.githubusercontent.com/lopidio/stacker/master/docs/img/http-passing-test.png\")
\n
Open source
\nWe (by 'we' we mean enqueuer's maintainers not the human race, unfortunately) are very opened to any kind of contributions in general.\nAs long as they make sense and add value to the product, you're free to go.\nWe mean it, do it. Even if it's a typo fix in this README file. Go ahead.\nIf you like it but don't want to waste time creating a pull request, no problem either.\nCreate an issue, or, even easier, give it a github star. It's cheap and it doesn't hurt anyone.\nYou know what? Just head up to enqueuer's github repo and keep staring at its repo.\nIt may help somehow.
\ncontributors
\nThank you. It sounds cliché, but this project wouldn't be the same without the massive contribution from everyone.
\ncode it
\nIn order to contribute with some code, you have to follow a few steps.\nFirst of all, get the code:
\n$ git clone git@github.com:enqueuer-land/enqueuer.git\n$ cd enqueuer\nGet its dependencies installed:
\n$ npm install\nBuild it:
\n$ npm run build\nGo for it. Make the changes you want.\nAfter everything is done:
\n$ npm run all\nCommit it:
\n$ npm run commit\nPush it:
\n$ git push\nfeedback
\nWe'd love to get your feedback!\nIf you have any comments, suggestions, etc. you can reach us here.
\n![\"NPM\"](\"https://nodei.co/npm/enqueuer.png?downloads=true&downloadRank=true&stars=true\")