Merge branch 'release/v2.1.2'

.travis.yml

@@ -5,16 +5,11 @@ node_js:
 services:
   - docker
 
-before_install:
-  - docker build -t postman/newman_ubuntu1404 ./ubuntu_1404
-
 install:
   - npm install
 
 script:
   - npm test
-  - docker run -v $PWD/tests/data:/etc/newman -t postman/newman_ubuntu1404 -c HTTPBinNewmanTest.json.postman_collection -e HTTPBinNewmanTestEnv.json.postman_environment --exitCode
-  - docker run -t postman/newman_ubuntu1404 -u https://www.getpostman.com/collections/8a0c9bc08f062d12dcda --exitCode
 
 after_success:
   - echo "All done!"

CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing to newman-docker
+
+## tl;dr
+
+Use [git-flow](http://nvie.com/posts/a-successful-git-branching-model/).
+
+- Create a feature branch off of `develop`
+
+```bash
+git checkout develop
+git checkout -b feature/my-feature
+```
+
+- Make your changes, and run tests to ensure that everything works
+
+```bash
+npm test
+```
+
+- If all checks out, push your code and create a pull with `develop` as the target
+
+```bash
+git push feature/my-feature
+```
+
+## Branching and Tagging Policy
+
+This repository uses standard `git-flow` branch management policy/strategy. If you want to learn more on `git-flow`, refer  to [tutorial from Atlassian](https://www.atlassian.com/git/workflows#!workflow-gitflow) and more details at [http://nvie.com/posts/a-successful-git-branching-model/](http://nvie.com/posts/a-successful-git-branching-model/).
+
+
+## Preferred IDE
+The preferred IDE for this project is SublimeText. You can download it from [http://www.sublimetext.com](http://www.sublimetext.com).
+
+The repository has a sublime project file included in `develop/` directory. This project is configured with the best practices recommended for `xt-edge`. Things like using 120 character ruler, addition of end-of-file newline, cleaning up of trailing whitespace has been configured in this project.
+
+There are a number of SublimeText Plugins that you can use to make your life simpler. One of them is the `jsDoc` autocompletion plugin. Download it from [https://github.com/spadgos/sublime-jsdocs](https://github.com/spadgos/sublime-jsdocs).
+
+> *It is expected that changes to the file `/postman-documentator.sublime-project` is not committed back in the repository without proper discussion with all primary contributors of this project.*
+
+### Generic IDE Settings
+
+Most IDE settings for Sublime Text resides within the project configuration file `./develop/xt-edge.sublime-project`. In case you are using any other IDE, (not recommended,) setting the following defaults of the IDE should help.
+
+1. Set to true to ensure the last line of the file ends in a newline character when saving.
+2. Use 120the columns to display vertical ruler.
+3. The number of spaces a tab is considered equal should be 4.
+4. Insert spaces when tab is pressed.
+5. Remove trailing white space on save.
+6. Always use UTF-8 character encoding for reading and writing files.
+7. Set IDE to not change file permissions upon editing.
+
+
+## Commit Guidelines
+
+The following best practices, coupled with a pinch of common-sense will keep the repository clean and usable in future. The idea is that everything that goes into the repository is not for an individual, but someone else who will be directly or indirectly affected by it.
+
+### Check for errors before committing
+
+Checking for errors should be done for each commit whether it is being pushed to remote or not.
+
+First, you don't want to submit any whitespace errors. Git provides an easy way to check for this — before you commit, run `git diff --check`, which identifies possible whitespace errors and lists them for you. If you run that command before committing, you can tell if you're about to commit whitespace issues that may annoy other developers.
+
+Secondly, you should ensure that your commit does not break builds. Run `npm test` on the repository to execute all sanity and smoke tests. If any test fail, do not change the test to pass your commit. The tests were there with a purpose. Discuss within your team to ensure that the changes that you do to test specs are valid. If you are adding a new feature, accompanying them with new tests are a good practice.
+
+### Atomic commits
+
+Try to make each commit a logically separate changeset. If you can, try to make your changes digestible — don't code for a whole weekend on five different issues and then submit them all as one massive commit on Monday. Even if you don't commit during the weekend, use the staging area on Monday to split your work into at least one commit per issue, with a useful message per commit. If some of the changes modify the same file, try to use `git add --patch` to partially stage files. The project snapshot at the tip of the branch is identical whether you do one commit or five, as long as all the changes are added at some point, so try to make things easier on your fellow developers when they have to review your changes. This approach also makes it easier to pull out or revert one of the changesets if you need to later. There are a number of useful Git tricks for rewriting history and interactively staging files — use these tools to help craft a clean and understandable history.
+
+### Clean commit message
+
+*More detailed explanation include your motivation for the change and contrast its implementation with previous behavior — this is a good guideline to follow.*
+
+Getting in the habit of creating quality commit messages makes using and collaborating with Git a lot easier. As a general rule, your messages should start with a single line that’s no more than about 50 characters and that describes the changeset concisely, followed by a blank line, followed by a more detailed explanation.
+
+It's also a good idea to use the imperative present tense in these messages. In other words, use commands. Instead of "I added tests for" or "Adding tests for," use "Add tests for."
+
+You should see if your commit message answers the following questions:
+Answer the following questions:
+
+1. **Why is this change necessary?**
+2. **How does it address the issue?**
+3. **What side effects does this change have?**
+
+The first question tells reviewers of your pull request what to expect in the commit, allowing them to more easily identify and point out unrelated changes.
+
+The second question describes, at a high level, what was done to affect change. If your change is obvious, you may be able to omit addressing this question.
+
+The third is the most important question to answer, as it can point out problems where you are making too many changes in one commit or branch. One or two bullet points for related changes may be okay, but five or six are likely indicators of a commit that is doing too many things.
+
+A good commit message template
+
+```
+Short (50 chars or less) summary of changes with relevant project management issue ID.
+
+More detailed explanatory text, if necessary.  Wrap it to about 72 characters or so.  In some contexts, the first line is treated as the subject of an email and the rest of the text as the body.  The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
+
+Further paragraphs come after blank lines.
+
+ - Bullet points are okay, too
+
+ - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here
+```
+
+Run `git log --no-merges` to see what a nicely formatted project-commit history looks like.
+
+## Documentation guidelines
+
+~~ to be documented further ~~
+
+## The CI Platform
+
+The CI system is built as a bunch of bash scripts to execute a set of tasks. These scripts are meant to execute tasks that can run on every local machine. In general, knowledge about these scripts are not necessary for development.
+
+**The scripts are to be only accessed using `npm run-script script name`.** This ensures that the execution point of the scripts (`pwd`) is always the repository root.
+
+### Ensuring your commits will not fail build
+
+> `npm test`
+
+The script associated with `npm test` will run all tests that ensures that your commit does not break anything in the repository. As such run `npm test` before you push.
+
+---
+*Sections of this document uses excerpts from various books and the Internet. [http://git-scm.com/book/](http://git-scm.com/book/) is one of the dominating influencers.*

images/alpine33/Dockerfile

@@ -0,0 +1,34 @@
+FROM alpine:3.3
+MAINTAINER Postman Labs <help@getpostman.com>
+
+# Set node version
+ENV NODE_VERSION 4.3.0
+
+# Install node
+RUN apk add --update nodejs=${NODE_VERSION}-r0;
+
+# Set newman version
+ENV NEWMAN_VERSION 2.1.2
+
+# Install newman
+RUN npm install -g newman@${NEWMAN_VERSION};
+
+# Set workdir to /etc/newman
+# When running the image, mount the directory containing your collection to this location
+#
+# docker run -v <path to collections directory>:/etc/newman ...
+#
+# In case you mount your collections directory to a different location, you will need to give absolute paths to any
+# collection, environment files you want to pass to newman, and if you want newman reports to be saved to your disk.
+# Or you can change the workdir by using the -w or --workdir flag
+
+WORKDIR /etc/newman
+
+# Set newman as the default container command
+# Now you can run the container via
+#
+# docker run -v /home/collections:/etc/newman -t postman/newman_alpine33 -c YourCollection.json.postman_collection \
+#                                                                        -e YourEnvironment.postman_environment \
+#                                                                        -H newman_report.html
+
+ENTRYPOINT ["newman"]

images/alpine33/README.md

@@ -0,0 +1,38 @@
+# newman_alpine33
+
+This image runs newman 2.1.2 on node 4.3.0 on Alpine 3.3
+
+Build the image,
+
+```terminal
+docker build -t postman/newman_alpine33 .
+```
+
+Or get it from [docker hub](https://registry.hub.docker.com/u/postman/newman_alpine33/)
+
+```terminal
+docker pull postman/newman_alpine33:2.1.2
+```
+
+then run it
+
+```terminal
+docker --volume="/home/postman/collections:/etc/newman" -t postman/newman_alpine33 --collection="JSONBlobCoreAPI.json.postman_collection" --html="newman-report.html"
+```
+For newman-docker to be able to use collections and environment files saved on the host machine, and to save reports generated by newman, a directory containing the collection and environment needs to be mounted on to the docker instance on run time, preferably at `/etc/newman`, which is the default working directory. If you mount to a different location, then
+  - You can either pass the full path to your collection and environment files to newman. For instance, if you mount to `/var/newman`,
+
+```terminal
+docker --volume="/home/postman/collection:/var/newman" -t postman/newman_alpine33 --collection="/var/newman/JSONBlobCoreAPI.json.postman_collection" --html="/var/newman/newman-report.html"
+```
+  - You can change the working directory while running the image to the location you mounted to, using the `-w` or `--workdir` flag.
+
+```terminal
+docker run --volume="/home/postman/collections:/var/newman" --workdir="/var/newman" -t postman/newman_alpine33 --collection="JSONBlobCoreAPI.json.postman_collection" --html="newman-report.html"
+```
+
+In case you don't need to save newmans report to the host, and your collection is available online and it does not require any environment, then you can forgo mounting your collections directory, and directly pass the collection url to newman
+
+```terminal
+docker run -t postman/newman_alpine33 --url="https://www.getpostman.com/collections/df0a40ef41d570c48154"
+```

ubuntu_1404/Dockerfile → images/ubuntu1404/Dockerfile

@@ -9,12 +9,14 @@ RUN apt-get update && apt-get install -y \
 # Set node version
 ENV NODE_VERSION 4.3.0
 
-# Set newman version
-ENV NEWMAN_VERSION 2.1.1
-
-# Install node and newman
+# Install node
 RUN npm install -g n;
 RUN n ${NODE_VERSION};
+
+# Set newman version
+ENV NEWMAN_VERSION 2.1.2
+
+# Install newman
 RUN npm install -g newman@${NEWMAN_VERSION};
 
 # Set workdir to /etc/newman

ubuntu_1404/README.md → images/ubuntu1404/README.md

@@ -1,6 +1,6 @@
 # newman_ubuntu1404
 
-This image runs newman 2.1.1 on node 4.3.0 on Ubuntu 14.04.2
+This image runs newman 2.1.2 on node 4.3.0 on Ubuntu 14.04.2
 
 Build the image,
 
@@ -11,7 +11,7 @@ docker build -t postman/newman_ubuntu1404 .
 Or get it from [docker hub](https://registry.hub.docker.com/u/postman/newman_ubuntu1404/)
 
 ```terminal
-docker pull postman/newman_ubuntu1404:1.3.2
+docker pull postman/newman_ubuntu1404:2.1.2
 ```
 
 then run it

package.json

@@ -1,9 +1,13 @@
 {
   "name": "newman-docker",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "This repository contains the Dockerfiles and tests for the Newman Docker images.",
   "scripts": {
-    "test": "mocha tests/*-spec.js"
+    "docker-build": "./scripts/docker/docker-build.sh",
+    "docker-test": "./scripts/docker/docker-test.sh",
+    "test": "./scripts/test/test.sh",
+    "test-docker": "./scripts/test/test-docker.sh",
+    "test-infra": "./scripts/test/test-infra.sh"
   },
   "repository": {
     "type": "git",

scripts/docker/docker-build.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+set -e;
+
+IMAGES_BASE_PATH="./images";
+
+function build_docker_image {
+    TAG=$(grep -oP "(?<=ENV\ NEWMAN_VERSION\ ).+" ${1}/Dockerfile);
+    BASENAME=$(basename $1);
+    docker build -t postman/newman_${BASENAME}:${TAG} ${1};
+}
+
+if [ -z "$1" ]; then
+    for image in $IMAGES_BASE_PATH/*; do
+        if [ -d "${image}" ] && [ -f "${image}/Dockerfile" ]; then
+            build_docker_image ${image};
+        fi
+    done
+else
+    if [ -d "${IMAGES_BASE_PATH}/${1}" ] && [ -f "${IMAGES_BASE_PATH}/${1}/Dockerfile" ]; then
+        build_docker_image ${IMAGES_BASE_PATH}/${1};
+    else
+        echo "Invalid image";
+        exit 1;
+    fi
+fi

scripts/docker/docker-test.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+set -e;
+
+IMAGES_BASE_PATH="./images";
+
+function test_docker_image {
+    TAG=$(grep -oP "(?<=ENV\ NEWMAN_VERSION\ ).+" ${1}/Dockerfile);
+    BASENAME=$(basename $1);
+
+    docker run -v $PWD/test/data:/etc/newman -t postman/newman_${BASENAME}:${TAG} \
+        -c HTTPBinNewmanTest.json.postman_collection \
+        -e HTTPBinNewmanTestEnv.json.postman_environment \
+        --exitCode;
+
+    docker run -t postman/newman_${BASENAME}:${TAG} \
+        -u https://www.getpostman.com/collections/8a0c9bc08f062d12dcda \
+        --exitCode;
+}
+
+if [ -z "$1" ]; then
+    for image in $IMAGES_BASE_PATH/*; do
+        if [ -d "${image}" ] && [ -f "${image}/Dockerfile" ]; then
+            test_docker_image ${image};
+        fi
+    done
+else
+    if [ -d "${IMAGES_BASE_PATH}/${1}" ] && [ -f "${IMAGES_BASE_PATH}/${1}/Dockerfile" ]; then
+        test_docker_image ${IMAGES_BASE_PATH}/${1};
+    else
+        echo "Invalid image";
+        exit 1;
+    fi
+fi

scripts/test/test-docker.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# stop on first error
+set -e;
+
+echo -e "\n\n\033[93mBuilding docker images...\033[0m";
+npm run docker-build;
+
+echo -e "\n\n\033[93mTesting docker images...\033[0m";
+npm run docker-test;

scripts/test/test-infra.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# stop on first error
+set -e;
+
+echo -e "\n\n\033[93mRunning infrastructure tests...\033[0m";
+echo -e "\033[0m\033[2mmocha `mocha --version`\033[0m";
+
+# run mocha tests
+mocha test/infra/**/*.test.js --recursive;

scripts/test/test.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+set -e;
+
+echo    "";
+echo    "      ,-————,";
+echo    "     / _____ \\";
+echo    "    ( | >   | )";
+echo    "     \\   —   /";
+echo    "      \`—————‘";
+echo    "";
+
+echo "Newman Docker Tests";
+
+# run infra tests
+npm run test-infra;
+
+# run docker tests
+npm run test-docker;

tests/dockerfiles-spec.js → test/infra/dockerfiles.test.js

@@ -9,17 +9,21 @@ var expect = require('expect.js'),
 
 /* global describe, it */
 describe('Validate Dockerfiles', function () {
-    var versions = ['ubuntu_1404'],
+    var imagesBaseDirectory = path.join(__dirname, '../../images'),
+        versions = fs.readdirSync(imagesBaseDirectory).filter(function (item) {
+            return fs.statSync(path.join(imagesBaseDirectory, item)).isDirectory();
+        }),
         rules = fs.readFileSync(path.join(__dirname, 'dockerfile_rules.yml')),
-        validator = new DockerFileValidator(rules); // TODO: Decide how we want to automatically load versions.
+        validator = new DockerFileValidator(rules);
 
     versions.map(function (version) {
-        var dockerFilePath = path.join(__dirname, '..', version, 'Dockerfile'),
+        var dockerFilePath = path.join(imagesBaseDirectory, version, 'Dockerfile'),
             dockerFileContent = fs.readFileSync(dockerFilePath);
 
         it('Docker file for "' + version + '" must be valid', function () {
             var result = validator.validate(dockerFileContent.toString()),
                 numBadThings = result.error.count + result.warn.count;
+
             if (!(numBadThings == 0)) {
                 console.log(JSON.stringify(result, null, 4)); // Helps debugging on the CI
             }