PipelineLib/Tutorial/TestingHelloNode

Welcome to Testing Hello Node, a simple PipelineLib tutorial.
= Prerequisites =
* Some familiarity with Blubber through prior experience or by following its tutorials.
* Access to Gerrit as a trusted contributor and your SSH key authorized for your account.
The HelloWorldOid example project introduced in the Hello Node Blubber tutorial is used by this tutorial. While it's not a requirement to have followed the tutorial, you may want to review it before continuing.
= Learning objectives =
At the end of this tutorial, you will:
# Know how to configure an existing project repo to run unit tests for each change submitted to Gerrit for review.
# Understand the basic structure of .pipeline/config.yaml file and how our CI system executes containerized tasks based on this configuration.
= Tutorial =
The basic steps to this tutorial will be to:
# Clone the example repo.
# Define a single-stage test pipeline that builds and runs a containerized version of the repo's test suite.
# Submit the new .pipeline/config.yaml file to Gerrit.
# Observe how Jenkins executes the project's test pipeline job according to your configuration.
# Clean up.
== Clone the example repo ==
dev@laptop:~$ git clone ssh://gerrit.wikimedia.org:29418/blubber-doc/example/helloworldoid blubber-doc/example/helloworldoid
dev@laptop:~$ cd blubber-doc/example/helloworldoid
== Look for a test image variant ==
Let's take a look at the project's .pipeline/blubber.yaml to see what kinds of images it supports building. Specifically, we're looking for a variant that runs its unit tests.
dev@laptop:helloworldoid$ cat .pipeline/blubber.yaml
version: v4
base: docker-registry.wikimedia.org/nodejs-slim
runs:
 environment:
 HELLO_WORLD: Hi, I’d like to add you to my professional network on LinkedIn.
variants:
 build:
 base: docker-registry.wikimedia.org/nodejs-devel
 copies: [local]
 node: { requirements: [package.json] }
 test:
 includes: [build]
 entrypoint: [npm, test]
 prep:
 includes: [build]
 node: { env: production }
 production:
 copies: [prep]
 entrypoint: [node, index.js]
Looks like there's a variant named test that (surprise!) runs the program's unit tests via npm test. Excellent. Let's move on.
== Define the test pipeline ==
Now we could just build the test variant using Blubber and run a container locally to verify that our tests pass, but what we're really trying to accomplish in this tutorial is to make that process automated for each patchset we (or others) send to Gerrit for this repo.
In other words, we now need to orchestrate our CI system and tell it to build and run this test variant. We do that by defining a simple test pipeline and stage in .pipeline/config.yaml.
dev@laptop:helloworldoid$ vim .pipeline/config.yaml # or use emacs, nano; whatever
pipelines:
 test:
 blubberfile: blubber.yaml
 stages:
 - name: run-test
 build: test
 run: true
Not a whole lot of configuration here, but let's go through it line by line.
Defines a new pipeline named test.
Tells CI where our image variants are defined.
Defines a new stage in our pipeline called run-test.
Specifies which image variant we'd like CI to build during this stage.
Tells CI to run the image built during this stage, test.
== Submit our change to Gerrit ==
Folks already familiar with Gerrit will know this, but we need to install a local commit-msg hook so a Change-Id can be automatically generated and included in our commit message.
dev@laptop:helloworldoid$ curl -o .git/hooks/commit-msg https://gerrit.wikimedia.org/r/tools/hooks/commit-msg
dev@laptop:helloworldoid$ chmod +x .git/hooks/commit-msg
Great. That's out of the way. Let's commit our code and submit our change!
Once our change is submitted, Zuul should see it and kick off our new test pipeline in Jenkins.
dev@laptop:helloworldoid$ git add .pipeline/config.yaml
dev@laptop:helloworldoid$ git commit -m 'tutorial: Configure CI to run unit tests'
dev@laptop:helloworldoid$ git push origin HEAD:refs/for/master
== Watch CI execute the pipeline ==
Head over to the helloworldoid-pipeline-test job to see its progress.