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.