Skip to content

Commit 6eb3129

Browse files
doc: add base doc that clarifies how users can test their projects (#3823)
**Description of the change:** doc: add base doc to clarifies how users can test their projects **Motivation for the change:** Many users have raised these questions. The goal of this doc is to provide the basic information and the links/references for they are able to move forward. It can be improved by the community and/or in the post 1.0 doc plans. Closes: #3511
1 parent 1254d83 commit 6eb3129

File tree

5 files changed

+46
-5
lines changed

5 files changed

+46
-5
lines changed
42.3 MB
Binary file not shown.

website/content/en/docs/building-operators/golang/advanced-topics.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Advanced Topics
33
linkTitle: Advanced Topics
4-
weight: 70
4+
weight: 80
55
---
66

77
### Manage CR status conditions

website/content/en/docs/building-operators/golang/migration.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -230,11 +230,11 @@ test: generate fmt vet manifests
230230
231231
## Migrate your tests
232232
233-
For the new layout, you will see that `controllers/suite_test.go` is created. This file contains boilerplate for executing integration tests using [envtest][envtest] with [ginkgo](https://onsi.github.io/ginkgo/) and [gomega](https://onsi.github.io/gomega/).
233+
For the new layout, you will see that `controllers/suite_test.go` is created when a controller is scaffolded by the tool. This file contains boilerplate for executing integration tests using [envtest][envtest] with [ginkgo](https://onsi.github.io/ginkgo/) and [gomega][gomega].
234234
235235
Operator SDK 1.0.0+ removes support for the legacy test framework and no longer supports the `operator-sdk test` subcommand. All affected tests should be migrated to use `envtest`.
236236
237-
The Operator SDK project recommends controller-runtime's [envtest][envtest] because it has a more active contributor community, it has become more mature than Operator SDK's test framework, and it does not require an actual cluster to run tests, which can be a huge benefit in CI scenarios.
237+
The Operator SDK project recommends using controller-runtime's [envtest][envtest] to write tests for your Operators projects. Envtest has a more active contributor community, it is more mature than Operator SDK's test framework, and it does not require an actual cluster to run tests which can be a huge benefit in CI scenarios.
238238
239239
To learn more about how you can test your controllers, see the documentation about [writing controller tests][writing-controller-tests].
240240
@@ -371,4 +371,5 @@ E.g `kubectl logs deployment.apps/memcached-operator-controller-manager -n memca
371371
[migration-guide-main-section]: /docs/building-operators/golang/migration/#migrate-maingo
372372
[kustomize]: https://github.com/kubernetes-sigs/kustomize
373373
[ctrl-options]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/manager#Options
374-
[envtest]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest
374+
[envtest]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest
375+
[gomega]: https://onsi.github.io/gomega/

website/content/en/docs/building-operators/golang/references/envtest-setup.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,5 @@ test: generate fmt vet manifests
1919
If using `git`, it is recommended to add `testbin/*` to your `.gitignore` file to avoid committing these binaries.
2020

2121
[envtest]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest
22-
[controller-test]: https://book.kubebuilder.io/reference/writing-tests.html
22+
[controller-test]: https://book.kubebuilder.io/cronjob-tutorial/writing-tests.html
2323
[script]: https://raw.githubusercontent.com/kubernetes-sigs/controller-runtime/master/hack/setup-envtest.sh
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Testing your Operator project
3+
linkTitle: Testing with EnvTest
4+
description: Learn how to ensure the quality of your Operator project
5+
weight: 70
6+
---
7+
8+
## Overview
9+
10+
The Operator SDK project recommends using controller-runtime's [envtest][envtest] to write tests for your Operators projects. Envtest has a more active contributor community, it is more mature than Operator SDK's test framework, and it does not require an actual cluster to run tests which can be a huge benefit in CI scenarios.
11+
12+
## Using EnvTest
13+
14+
You will see that `controllers/suite_test.go` is created when a controller is scaffolded by the tool. This file contains boilerplate for executing integration tests using [envtest][envtest] with [ginkgo](https://onsi.github.io/ginkgo/) and [gomega][gomega].
15+
16+
17+
It means that you will implement your controller's tests in go using this stack and it will be called by the `suite_test.go` via go tool such as:
18+
19+
```shell
20+
go test controllers/ -v -ginkgo.v
21+
```
22+
23+
The projects generated by using the SDK tool have a Makefile which contains the target tests which executes when you run `make test`. Note that this target will also execute when you run `make docker-build IMG=<some-registry>/<project-name>:<tag>`.
24+
25+
Operator SDK adopted this stack to write tests for its operators. It might be useful to check [writing controller tests][writing-controller-tests] documentation and examples to learn how to better write tests for your operator. See, for example, that [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) is covered by tests using the same stack as well.
26+
27+
## Other Options
28+
29+
Also you can write tests for your operator in a declarative using the [kuttl][kuttl]. Via kuttl, you can define YAML manifests that specify the expected before and after statues of a cluster when your operator is used. For more info see [Writing Kuttl Scorecard Tests][writing-kuttl-scorecard-tests].
30+
31+
To implement application-specific tests, the SDK's test harness, [scorecard][scorecard], provides the ability to ship custom code in container images as well, which can be referenced in the test suite. Because this test suite definition metadata travels with the Operator Bundle, it allows for functional testing of the Operator without the source code or the project layout being available. See [Writing Custom Scorecard Tests][writing-custom-scorecard-tests].
32+
33+
[envtest]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest
34+
[writing-controller-tests]: https://book.kubebuilder.io/cronjob-tutorial/writing-tests.html
35+
[envtest-setup]: /docs/building-operators/golang/references/envtest-setup
36+
[writing-kuttl-scorecard-tests]: /docs/advanced-topics/scorecard/kuttl-tests
37+
[writing-custom-scorecard-tests]: /docs/advanced-topics/scorecard/custom-tests
38+
[scorecard]: /docs/advanced-topics/scorecard/scorecard
39+
[gomega]: https://onsi.github.io/gomega/
40+
[kuttl]: https://kuttl.dev/

0 commit comments

Comments
 (0)