Overview

The following sections describe how to build and test Minishift.

Prerequisites

  • Git

  • A recent Go distribution (>=1.8)

You should be able to develop Minishift on any operating system, such as GNU/Linux, macOS or Windows. The Windows operating system might require additional steps or have some limitations.

Setting Up the Development Environment

Creating the Go Workspace

We highly recommend to setup a default Go workspace. Even though it might require an adjustment in your work processes, the goal is to have a single workspace for all Go development.

  1. Create the following directories in the base directory you want to use, such as $HOME/work:

    /bin

    Contains executable commands

    /pkg

    Contains package objects

    /src

    Contains Go source files

  2. Add the path of the root workspace directory to the GOPATH environment variable. For example:

    $ export GOPATH=$HOME/work
  3. Add the workspace bin directory to the PATH environment variable:

    $ export PATH=$PATH:$GOPATH/bin
On Windows operating systems, you use the UI or use setx to set the environment variables.

Cloning the Repository

Get the Minishift sources from GitHub:

$ cd $GOPATH/src
$ git clone https://github.com/minishift/minishift.git github.com/minishift/minishift

Using an IDE

You can use any editor you want. However, most of the core maintainers of Minishift use IntelliJ IDEA with the latest Go plug-in. This IDE indexes your whole workspace and allows for easy navigation of the sources, and also integrates with the Go debugger Delve.

For instructions on setting up IDEA, see Setting up Go on IntelliJ.

Dependency Management

Minishift uses Glide for dependency management.

Installing Glide

Before you can use Glide you need to download and install it from GitHub:

$ go get github.com/Masterminds/glide

This will install the glide binary into $GOPATH/bin. Make sure to use Glide version 0.12.3 or later.

Bootstrapping Dependencies

After a clean checkout or after a make clean, there won’t be a vendor directory containing the needed Minishift dependencies.

To install the dependencies, you can run the following command:

$ make vendor

This command calls and runs Glide. Alternatively, you can run the Glide command directly.

$ glide install -v

Updating Dependencies

If your work requires a change to the dependencies, you need to update the Glide configuration.

  1. Edit glide.yaml to change the dependencies as needed.

  2. Delete glide.lock and re-create the vendor directory by running make vendor. Glide will recognize that there is no lock file and recalculate the required dependencies.

  3. Check-in the updated glide.yaml and glide.lock files.

  4. Test that everything still compiles with the new lock file in place by running make clean && make.

In some cases the Glide cache located under ~/.glide/cache can get corrupted. If you seeing Glide errors during make vendor, you can clear the Glide cache via glide cc.

Building Minishift

Building the Minishift Binary

Run the following command to create a platform-specific binary and copy it to $GOPATH/bin.

$ make
Use make cross to cross-compile for other platforms.

Running the Minishift Binary

Start the OpenShift cluster with your built minishift binary:

$ minishift start

This command will run Minishift from $GOPATH/bin/minishift, if you set up your Go workspace as described in the Creating the Go workspace section.

You can also execute the binaries directly from the out directory of the checkout. Depending on your operating system, the binary is in one of the following directories:

  • out/darwin-amd64

  • out/linux-amd64

  • out/windows-amd64

For more Minishift commands and flags, see the Minishift command reference documentation.

Unit Tests

Unit tests run on Travis before the code is merged. To run tests during the development cycle:

$ make test

To run specific tests, use one of the following methods:

  • Run all tests on a single package.

    # Eg: go test -v ./cmd/minikube/cmd
    $ go test -v <relative path of package>
  • Run a single test on a single package.

    $ go test -v <relative path of package> -run <Testcase Name>
  • Run tests that match a pattern.

    $go test -v <relative path of package> -run "Test<Regex pattern to match tests>"

For more information about test options, run the go test --help command and review the documentation.

Integration Tests

Integration tests utilize Godog, which uses Gherkin (Cucumber) to define sets of test cases, in Gherkin terminology known as features. The features are located in test/integration/features folder. Features for Minishift follow these basic concepts:

User stories

Features which follow a happy path of user. For example, basic.feature or coolstore.feature.

Feature and command coverage

Features which focuses on specific fields of Minishift functionality or individual commands. For example, proxy.feature or cmd-version.feature.

Running Integration Tests

By default, the tests are being run against the binary created by make build, which is $GOPATH/bin/minishift. To run the basic test, use the following command:

$ make integration
By default make integration only runs tests which are tagged as @basic.

To run all tests, use the following command:

$ make integration_all

There is also a make integration_pr target which is being run as part of pull request testing.

Additional Parameters

To provide more flexibility the default targets integration and integration_all can be further customized using several parameters.

MINISHIFT_BINARY

Parameter MINISHIFT_BINARY can be used to run integration tests against Minishift binary located in different directory:

$ make integration MINISHIFT_BINARY=<path-to-custom-binary>
TIMEOUT

Parameter TIMEOUT can be used to override the default timeout of 3600s. To run all the tests with timeout 7200s, use the following command:

$ make integration_all TIMEOUT=7200s
RUN_BEFORE_FEATURE

Parameter RUN_BEFORE_FEATURE specifies Minishift commands to be run before each feature. This provides ability to run integration tests against Minishift which is not in default state. When multiple commands are specified, they must be delimited by a semicolon. For example, tests can be run against stopped Minishift with image caching option turned on by running:

$ make integration_all RUN_BEFORE_FEATURE="start; stop; config set image-caching true"

Using GODOG_OPTS Parameter

Parameter GODOG_OPTS specifies additional arguments for Godog runner. The following options are available:

Tags

Use tags to ensure that scenarios and features containing at least one of the selected tags are executed.

Paths

Use paths to define paths to different feature files or folders containing feature files. This can be used to run feature files outside of the test/integration/features folder.

Format

Use format to change the format of Godog’s output. For example, you can set progress format instead of the default pretty.

Stop-on-failure

Set stop-on-failure to true to stop integration tests on failure.

No-colors

Set no-colors to true to disable ansi colors of Godog’s output.

Definitions

Set definitions to true to print all available step definitions.

Passing any value via GODOG_OPTS overrides the default tag definition on each integration target. Thus in this case --tags must be specified manually, otherwise all features will be run.

For example, to run integration tests on two specific feature files using only @basic and @openshift tags and without ansi colors, the following command can be used:

$ make integration GODOG_OPTS="-paths ~/tests/custom.feature,~/my.feature -tags basic,openshift -no-colors true"
When multiple values are used for options in GODOG_OPTS, then they have to be separated by a comma without whitespace. While -tags basic,openshift will be parsed properly by make, -tags basic, openshift will result in only @basic being used.

Viewing Results

Integration test logs its progress directly into a console with accent of providing additional useful information when failures of individual Gherkin steps happen. This information is often enough to find and debug the reason of failure.

However for cases which needs further investigation the integration test also logs more detailed progress into a log file. This file is located at $GOPATH/github.com/minishift/minishift/out/test-results/integration_YYYY-MM-DD_HH:MM:SS.log.

Formatting the Source Code

Minishift adheres to the Go formatting guidelines. Code with incorrect formatting will fail the CI builds. You can check whether any of your files violate the guidelines with the following command:

$ make fmtcheck

You can correct the formatting errors yourself or instruct the violations to be corrected automatically with the following command:

$ make fmt

You can also check for common coding mistakes by using:

$ make vet

Similar to make fmtcheck, failures in make vet will fail the CI builds.

Commit messages

Each commit message must meet two requirements:

  • the commit subject is strictly less than 90 characters (GitHub ellipsis length).

  • the commit subject matches the format Issue #[0-9]+ .*, meaning each commit must reference an issue.

The Makefile contains a validate_commits target which can be used to verify these requirements:

$ make validate_commits

Cleaning the workspace

To remove all generated artifacts and installed dependencies, run the following command:

$ make clean

Godoc

When developing Minishift, it is encouraged to use Godoc to document the source code. You can find guidelines on how to use godoc in this blog post. You can browse the Minishift Godoc documentation under https://godoc.org/github.com/minishift/minishift.