Skip to content

Commit

Permalink
Merge pull request #54 from przemeklal/unittests_doc
Browse files Browse the repository at this point in the history 
Document unit testing in README.md
  • Loading branch information
@garyloug
garyloug authored Oct 14, 2020
2 parents 163a160 + 06559c0 commit c491716
Showing 1 changed file with 150 additions and 0 deletions.
150 changes: 150 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,9 @@
* [1. Build the image to be used](#1-build-the-image-to-be-used)
* [2. Create pod with multiple vhostuser interfaces](#2-create-pod-with-multiple-vhostuser-interfaces)
* [3. Open terminal to pod and start testpmd](#3-open-terminal-to-pod-and-start-testpmd)
* [Unit Testing](#unit-testing)
* [Unit Tests Overview](#unit-tests-overview)
* [Unit Tests Inside Container](#unit-tests-inside-container)

# Summary
The Userspace CNI is a Container Network Interface (CNI) plugin
Expand Down Expand Up @@ -1027,3 +1030,150 @@ To exit:
Pktgen:/> stop 0
Pktgen:/> quit
```

# Unit Testing

## Unit Tests Overview

The Userspace CNI networking plugin is written in [GO](https://golang.org/) and
it uses [GO Testing](https://golang.org/pkg/testing) package for unit testing.
In order to simplify unit test code, a [testify](https://github.com/stretchr/testify)
toolkit is also used for [assertions](https://godoc.org/github.com/stretchr/testify/assert).
Unit test files have suffix *_test.go* and they are located at the same directory
as the production code.

For example *userspace* package have one source file and one file with unit tests:

```bash
userspace/userspace.go
userspace/userspace_test.go
```

In the file `userspace_test.go` you can find a set of test functions with the same
name as functions from `userspace.go` with prefix `Test`. Each test function
implements a set of tests to test production code thoroughly with different
input data, etc.

Testing binary is built and tests executed by `go test` command at directory
with test files.

For example, unit tests for userspace package with verbose output can be executed
as follows:

```bash
cd userspace
go test -v
```

An example of verbose output of userspace unit tests:

```bash
=== RUN TestPrintVersionString
=== RUN TestPrintVersionString/verify_version_string
--- PASS: TestPrintVersionString (0.00s)
--- PASS: TestPrintVersionString/verify_version_string (0.00s)
=== RUN TestLoadNetConf
=== RUN TestLoadNetConf/fail_to_parse_netConf_1
=== RUN TestLoadNetConf/fail_to_parse_netConf_2
=== RUN TestLoadNetConf/fail_to_parse_netConf_3
=== RUN TestLoadNetConf/fail_to_parse_netConf_4
=== RUN TestLoadNetConf/fail_to_parse_netConf_5
=== RUN TestLoadNetConf/fail_to_parse_netConf_6
=== RUN TestLoadNetConf/fail_to_set_default_logging_level
=== RUN TestLoadNetConf/fail_to_set_log_file
=== RUN TestLoadNetConf/load_correct_netConf
--- PASS: TestLoadNetConf (0.00s)
--- PASS: TestLoadNetConf/fail_to_parse_netConf_1 (0.00s)
--- PASS: TestLoadNetConf/fail_to_parse_netConf_2 (0.00s)
--- PASS: TestLoadNetConf/fail_to_parse_netConf_3 (0.00s)
--- PASS: TestLoadNetConf/fail_to_parse_netConf_4 (0.00s)
--- PASS: TestLoadNetConf/fail_to_parse_netConf_5 (0.00s)
--- PASS: TestLoadNetConf/fail_to_parse_netConf_6 (0.00s)
--- PASS: TestLoadNetConf/fail_to_set_default_logging_level (0.00s)
--- PASS: TestLoadNetConf/fail_to_set_log_file (0.00s)
--- PASS: TestLoadNetConf/load_correct_netConf (0.00s)
...
```

It is possible to execute unit tests directly from the host where the code is
being developed. However it is strongly recommended to execute them from within
a container. It will assure that unit tests will be isolated from the host
and thus avoid any collision with the host environment (e.g. k8s or OVS).
Another advantage is a possibility to easily execute unit tests at various Linux
OS distributions. Support of unit test execution inside containers is implemented
by project Makefile and described in following paragraphs.

## Unit Tests Inside Container

Project `Makefile` defines a set of targets suitable for unit testing inside
containers. In order to build and use testing containers, both `docker` and
`gcc` (C preprocessor is used to assemble Dockerfiles) have to be installed
at the host.

Example of tools installation at Ubuntu:

```bash
apt install docker.io gcc
```

After the installation is completed, then any of unit test specific targets
can be executed in order to:

* build test containers and update them in case that new commit is detected
* execute unit tests
* calculate code coverage
* cleanup unit test container images and generated docker files

Targets for container building, unit testing and code coverage calculation
are prepared in three different versions to be executed at:

* Linux OS distribution defined by `UT_OS` environment variable

e.g. execute build of container image for CentOS8

```bash
export UT_OS=centos8
make test-build
```

* Linux OS distribution specified by target suffix

e.g. calculate code coverage at Ubuntu 20.04

```bash
make coverage-ubuntu20.04
```

* all supported OS distributions

e.g. execute unit tests at all supported OS distros:

```bash
make test-all
```

The list of supported `make` targets is also documented as part of `make help`
as follows:

```
Make Targets for unit testing inside containers:
make test-clean - Remove test container images and generated Dockerfiles.
make test-build - Build container image for unit tests with OS defined by UT_OS: UT_OS=ubuntu20.04
make test - Run unit tests inside container with OS defined by UT_OS: UT_OS=ubuntu20.04
make coverage - Calculate code coverage in container with OS defined by UT_OS: UT_OS=ubuntu20.04
make test-build-<os> - Build container image for unit tests with <os>, e.g. make test-build-centos8
make test-<os> - Run unit tests inside container with <os>, e.g. make test-centos8
make coverage-<os> - Calculate code coverage inside container with <os>, e.g. make coverage-centos8
make test-build-all - Build container images for unit tests for all supported OS distributions
e.g. make -j 5 test-build-all
make test-all - Run unit tests inside container for all supported OS distributions
e.g. make -j 5 test-all
make coverage-all - Calculate code coverage inside container for all supported OS distributions.
e.g. make -j 5 coverage-all
```

Following Linux OS distributions are supported for unit testing inside containers:

* CentOS 7, 8
* Fedora 31, 32
* Ubuntu 16.04, 18.04, 20.04

0 comments on commit c491716

Please sign in to comment.