Developing Minishift

Overview

The following sections describe how to build and test Minishift.

Prerequisites

  • Git

  • Make

  • A recent Go distribution (>=1.8)

You should be able to develop Minishift on Linux or macOS.

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:

    1. $ export GOPATH=$HOME/work

  3. Add the workspace bin directory to the PATH environment variable:

    1. $ export PATH=$PATH:$GOPATH/bin

Cloning the Repository

Get the Minishift sources from GitHub:

  1. $ cd $GOPATH/src
  2. $ 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 Dep for dependency management.

Installing Dep

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

  1. $ go get github.com/golang/dep/cmd/dep

This will install the dep binary into $GOPATH/bin. Make sure to use Dep version 0.4.1 or later.

Updating Dependencies

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

  1. Edit Gopkg.toml to change the dependencies as needed.

  2. Run make vendor to fetch changed dependencies.

  3. Test that everything still compiles with changed files in place by running make clean && make.

Refer dep documents for more information.

  1. dep document about updating dependencies

  2. dep document about adding a dependency

Re-creating vendor Directory

If you delete vendor directory which contain the needed Minishift dependencies.

To recreate vendor directory, you can run the following command:

  1. $ make vendor

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

  1. $ dep ensure -v

The Dep cache located under $GOPATH/pkg/dep. If you see any Dep errors during make vendor, you can remove local cached directory and try again.

Building Minishift

Building the minishift Binary

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

  1. $ make

Use make cross to cross-compile for other platforms.

Running the minishift Binary

Start the OpenShift cluster with your built minishift binary:

  1. $ 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. Unit test coverage is then reported to Codecov which provides coverage information on the pull requests. Locally you can generate a HTML code coverage report by following steps:

  1. $ make coverage
  2. $ go tool cover -html=out/coverage.txt -o out/coverage.html

To run tests during the development cycle:

  1. $ make test

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

  • Run all tests on a single package.

    1. # Eg: go test -v ./cmd/minikube/cmd
    2. $ go test -v <relative path of package>

  • Run a single test on a single package.

    1. $ go test -v <relative path of package> -run <Testcase Name>

  • Run tests that match a pattern.

    1. $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. These test cases are known as features in Gherkin terminology. Features are located in the test/integration/features directory. Features for Minishift follow these basic concepts:

User stories

Features which follow a happy path of user. For example, the 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, tests are run against the binary created by make ($GOPATH/bin/minishift). To run the quick test, use the following command:

  1. $ make integration

By default, make integration only runs tests that are tagged as @quick. These tests contain multiple scenarios, but only start Minishift once.

To run all of the tests (except those tagged as @disabled), use the following command:

  1. $ make integration_all

There is also a make integration_pr target which is run as part of pull request testing. This target runs the test on all features tagged as @core, which covers the basic functionality of Minishift. This target is a compromise between total run time and coverage.

Additional Parameters

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

MINISHIFT_BINARY

The MINISHIFT_BINARY parameter can be used to run integration tests against a minishift binary located in a different directory:

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

TIMEOUT

The TIMEOUT parameter can be used to override the default timeout of 10800s. To run all the tests with a timeout of 7200s, use the following command:

  1. $ make integration_all TIMEOUT=7200s

RUN_BEFORE_FEATURE

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

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

COPY_OC_FROM

To test Minishift with a non-default oc binary you can use the COPY_OC_FROM parameter. This parameter specifies the path to the oc binary which will be copied into the $MINISHIFT_HOME folder before each feature run. Note that the oc binary must be contained in the same directory structure which Minishift uses for the storage of oc binaries, for example: <version>/<platform>/oc(.exe). For example, to test Minishift with locally stored oc v3.7.23 run:

  1. $ make integration COPY_OC_FROM=<path-to-oc-directory>/v3.7.23/<linux or windows or darwin>/oc RUN_BEFORE_FEATURE="config set openshift-version v3.7.23"

TEST_WITH_SHELL

  • About

    The majority of Minishift integration tests pass command line arguments directly to the minishift or oc binaries via Go’s os/exec package. However, some integration tests first start persistent instance of the shell to pass commands into later, for example: When user starts shell instance on host machine. Due to persistency of the shell instance all changes done in it will be present until its closure, for example, changed environmental variables. This allows testing of commands which are dependent on the shell they are being executed in. The steps using this approach have the shell keyword in their definition, for example: When executing "minishift oc-env" in host shell succeeds.

    Usage

    TEST_WITH_SPECIFIED_SHELL is an optional parameter. If nothing is passed with TEST_WITH_SPECIFIED_SHELL, then the shell type is automatically determined. By default, the shell will be PowerShell on Windows, Bash on macOS and Linux. The TEST_WITH_SPECIFIED_SHELL parameter can be used to run the tests with different shells. To run the tests using the Windows Command Prompt, for example, run make integration_all TEST_WITH_SPECIFIED_SHELL=cmd. The TEST_WITH_SPECIFIED_SHELL parameter supports the powershell, cmd, bash, tcsh and zsh options.

Using the GODOG_OPTS Parameter

The GODOG_OPTS parameter specifies additional arguments for the 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. To select particular feature, you can use its name as a tag. For example, the cmd-config.feature contains @cmd-config tag through which it can be selected and run with the following command: make integration GODOG_OPTS=--tags=cmd-config. There are also a few special tags used to indicate specific subsets of integration tests. These are the following:

  • @quick includes basic.feature along with several other features and scenarios which do not require a start of Minishift. Starting the tests with the @quick tag covers a variety of scenarios, but only starts Minishift once.

  • @core includes feature files which cover all of the essential functionality of Minishift. This tag is used to test pull requests to the Minishift repository.

  • @disabled indicates broken feature files. Any failures on these features are expected. All features, scenarios, and steps tagged as @disabled will not be run as part of pull request testing or nightly build testing.

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 the format to progress 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 colorization 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 the @basic and @cmd-addons tags and without ANSI colors, the following command can be used:

  1. $ make integration GODOG_OPTS="-paths ~/tests/custom.feature,~/my.feature -tags basic,cmd-addons -no-colors true"

Multiple values for a GODOG_OPTS option must be separated by a comma without whitespace. For example, -tags basic,cmd-openshift will be parsed properly by make, whereas -tags basic, cmd-openshift will result in only @basic being used.

Viewing Results

The integration test logs its progress directly into a console. This information is often enough to find and debug the reason for a failure.

However, for cases which require 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.

Writing features

Minishift integration testsuite offers a comprehensive set of implemented Gherkin steps which allow for comfortable writing of feature files. All available steps are defined in the file /test/integration/testsuite.go. Definitions of steps are simple and self-documenting, for example:

  1. s.Step(`^executing "minishift (.*)" (succeeds|fails)$`,
  2.     ExecutingMinishiftCommandSucceedsOrFails)

This defines a step which matches regular expression ^executing "minishift (.*)" (succeeds|fails)$. If matched, the two capturing groups are passed as parameters to the function ExecutingMinishiftCommandSucceedsOrFails(command string, expectedResult string), which implements the actual behaviour of the step.

To use the step in the feature file, you need to make sure it matches with the regular expression and prepend one of the Gherkin keywords: Given, When, Then, And or But, for example:

  1. Then executing "minishift config set memory 3gb" succeeds

See the Gherkin Reference for more general information about the structure of Gherkin, its features, scenarios, and steps.

Using Integration Tests as a Package

Integration tests can be also used as a package outside of the Minishift repository. You can import it as github.com/minishift/minishift/test/integration/testsuite. As a starting point for your project you can copy and use the test/integration/integration_test.go file. Its key parts are commented to help you to begin with the implementation.

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:

  1. $ make fmtcheck

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

  1. $ make fmt

You can also check for common coding mistakes by using:

  1. $ make vet

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

Commit Message Requirements

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:

Currently, only Circle CI validates the commit message as part of the CI build.

  1. $ make validate_commits

Cleaning the Workspace

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

  1. $ 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.