Creating your own reporter

I don't have the space to show you how to use all these reporters, but I think the htmlextra reporter is a useful one, so I will walk you through how to install and use it. You should be able to use what you will learn next to install any of the reporters that you need.

Generating reports with htmlextra Similar to installing Newman, you can install htmlextra with npm. Call the following command to globally install htmlextra:

npm install -g newman-reporter-htmlextra

Once it has downloaded and installed, you can specify it by passing in htmlextra to the -r option. For example, to use it with the data-driven test mentioned earlier in this chapter, you could call the following command:

newman run TestCollection.json -e NewmanTestEnvironment.json -d DataDrivenInputs.csv –r htmlextra

Once the requests have run, you can go to the newman folder in your working directory, and you will see an .html file in there that you can open in a web browser. This will give you a nice dashboard summarizing the results of your run. The default dashboard is useful, but if you want, you can also customize it. For example, you can change the title to My Test Newman Report by adding the following to your command:

--reporter-htmlextra-title "My Test Newman Report"

There are several other options that allow you to customize parts of the report. You can check those out in the documentation here: https://github.com/DannyDainton/

newman-reporter-htmlextra.

Even with the number of community supported reporters out there, you might not be able to find one that does exactly what you need. In that case, you could just make your own! Doing this requires some JavaScript knowledge, but let's walk through an example so that you can see how it would work. Unless you are fairly proficient with JavaScript, you will probably want to stick to reporters that others have made, but understanding how something works behind the scenes is still helpful. To make your own reporter, follow these steps:

1. On your hard drive, create a new directory called MyReporter. 2. Open a Command Prompt and use the cd command to navigate into that directory.

3. Create a blank npm package by calling npm init.

You will be prompted for a few things. First, you will be asked what name you want your package to have. The default name is set to myreporter, but this will not work. A Newman reporter must have a name that starts with newman-

reporter-. 4. Type in newman-reporter-myreporter and hit Enter to accept the new name. 5. Hit Enter again to accept the default version number. 6. Type in a short description and hit Enter. 7. Leave the entry point as its default of index.js by hitting Enter again. 8. We won't bother with a test command, Git repository, or keywords, so you can just hit Enter to skip past each of those options as they come up. 9. Put in your name as the author and hit Enter. 10. Since this is just a test package that you are playing around with, you don't need to worry about the license too much and can just hit Enter to accept the default one. 11. Once you've gone through all those options, npm will show you the package. json file that it is going to create for you, which has all those options in it. You can tell it to create that file by hitting Enter to send the default response of yes to the question.

Now that you have a blank npm package, you can create a reporter. 12. Add a file called index.js to the folder you've created and open that file in a code or text editor.

This file is where you will put the JavaScript code that you will use to create your custom reporter. As I mentioned previously, creating a custom reporter will be difficult if you only have a beginner's understanding of JavaScript. I can't go into the depth of JavaScript that you will need for this process in this book, but I will show you a simple example so that you can see, in very broad terms, what it takes to do this. Newman emits events while it is running that the reporters can listen for and then perform actions based on receiving them. The following code shows a couple of examples of using those events:

function MyCustomNewmanReporter (newman, reporterOptions, collectionRunOptions) { newman.on('start', function (err) { if (err) { return; } console.log('Collection run starting')

}); newman.on('item', function (err,args) { console.log(Ran: '+args.item.name) }); newman.on('done', function () { console.log('all done!') }); }; module.exports = MyCustomNewmanReporter

The file needs to include a function (in this case, I have called it MyCustomNewmanReporter) and then it needs to export that function with module. exports at the bottom of the file. Once you have done that, you can do anything you want to inside the function. In this case, I am showing three different examples of how you can use Newman events.

The first event I'm looking at is the start event:

newman.on('start', function (err) { if (err) { return; } console.log('Collection run starting') });

This event is sent whenever Newman starts running a new collection. You can see that I listen for that event with the newman.on method. I then tell it what event I am listening for ('start') and give it a callback that can take in two arguments. The first argument is the error object and, in this case, this is the only argument I need to specify. I then check whether there is an error and if so, stop execution. If there isn't one, I merely log out the fact that the collection run has started.

The second example in my code is listening for the item event:

newman.on('item', function (err,args) { console.log(Ran: '+args.item.name) });

In this case, I have specified both arguments in the callback. The first one, as shown previously, is the error object, which will only happen if there is an error. The second argument is an object that contains summary information about the event that I am listening for. In this case, that object is the item object since this is an item event. This object has several properties, but in this example, I am accessing the name property and printing that out. The item event is emitted when a test has completed. The final example in my code is listening for the done event, which is emitted when a collection run has completed:

newman.on('done', function () { console.log('all done!') });

This example shows how the callback arguments are optional. In this case, I am not accessing any of the properties of the summary object and I'm not worrying about the errors, so I don't bother specifying those things. One other thing that should be noted in this example is that the MyCustomNewmanReporter function takes in three arguments. The newman argument is the class that emits the events and these examples have shown how to use it, but I did not show you how to use the other two inputs to that function. The reporterOptions argument will include things such as the silent option or other reporter options that you might want to support. collectionRunOptions includes information about all the command-line options that were passed in. This example is obviously very simple and there is a lot more complexity to creating your own reporter. If you want to figure out more, I would suggest that you go to the

Newman GitHub repository (https://github.com/postmanlabs/newman) and look through the documentation there. While you are there, you can also check out how the built-in reporters work. They use the same approach that you would need to use to create your own reporter. You can see the code for them here: https://github.com/

postmanlabs/newman/tree/develop/lib/reporters. Another great example can be found in Deepak Pathania's neman-reporter-debug GitHub repository. If you

look at the DebugReporter.js file (https://github.com/deepakpathania/ newman-reporter-debug/blob/master/lib/DebugReporter.js), you will see a number of different examples showing how to use many of the Newman events and options. Now that you know how to create your own custom reporters, we will take a look at how to use Newman in Continuous Integration (CI) builds in more detail.