Add envtest testing docs to extend cronjob example

docs/book/src/SUMMARY.md

@@ -26,6 +26,8 @@
 
     - [Deploying the cert manager](./cronjob-tutorial/cert-manager.md)
     - [Deploying webhooks](./cronjob-tutorial/running-webhook.md)
+
+  - [Writing tests](./cronjob-tutorial/writing-tests.md)
 
   - [Epilogue](./cronjob-tutorial/epilogue.md)
 
@@ -73,7 +75,7 @@
   - [Artifacts](./reference/artifacts.md)
   - [Writing controller tests](./reference/writing-tests.md)
 
-    - [Using envtest in integration tests](./reference/testing/envtest.md)
+  - [Using envtest in integration tests](./reference/envtest.md)
 
   - [Metrics](./reference/metrics.md)
 

docs/book/src/cronjob-tutorial/epilogue.md

@@ -1,8 +1,8 @@
 # Epilogue
 
 By this point, we've got a pretty full-featured implementation of the
-CronJob controller, and have made use of most of the features of
-KubeBuilder.
+CronJob controller, made use of most of the features of
+KubeBuilder, and written tests for the controller using envtest.
 
 If you want more, head over to the [Multi-Version
 Tutorial](/multiversion-tutorial/tutorial.md) to learn how to add new API
@@ -11,9 +11,6 @@ versions to a project.
 Additionally, you can try the following steps on your own -- we'll have
 a tutorial section on them Soon™: 
 
-- writing unit/integration tests (check out [envtest][envtest])
 - adding [additional printer columns][printer-columns] `kubectl get`
 
-[envtest]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest
-
 [printer-columns]: /reference/generating-crd.md#additional-printer-columns

docs/book/src/cronjob-tutorial/testdata/project/controllers/cronjob_controller_test.go

@@ -0,0 +1,205 @@
+/*
+Ideally, we should have one `<kind>_conroller_test.go` for each controller scaffolded and called in the `test_suite.go`.
+So, let's write our example test for the CronJob controller (`cronjob_controller_test.go.`)
+*/
+
+/*
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+// +kubebuilder:docs-gen:collapse=Apache License
+
+/*
+As usual, we start with the necessary imports. We also define some utility variables.
+*/
+package controllers
+
+import (
+	"context"
+	"reflect"
+	"time"
+
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+	batchv1 "k8s.io/api/batch/v1"
+	batchv1beta1 "k8s.io/api/batch/v1beta1"
+	v1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+
+	cronjobv1 "tutorial.kubebuilder.io/project/api/v1"
+)
+
+// +kubebuilder:docs-gen:collapse=Imports
+
+/*
+The first step to writing a simple integration test is to actually create an instance of CronJob you can run tests against.
+Note that to create a CronJob, you’ll need to create a stub CronJob struct that contains your CronJob’s specifications.
+
+Note that when we create a stub CronJob, the CronJob also needs stubs of its required downstream objects.
+Without the stubbed Job template spec and the Pod template spec below, the Kubernetes API will not be able to
+create the CronJob.
+*/
+var _ = Describe("CronJob controller", func() {
+
+	// Define utility constants for object names and testing timeouts/durations and intervals.
+	const (
+		CronjobName      = "test-cronjob"
+		CronjobNamespace = "test-cronjob-namespace"
+		JobName          = "test-job"
+
+		timeout  = time.Second * 10
+		duration = time.Second * 10
+		interval = time.Millisecond * 250
+	)
+
+	Context("When updating CronJob Status", func() {
+		It("Should increase CronJob Status.Active count when new Jobs are created", func() {
+			By("By creating a new CronJob")
+			ctx := context.Background()
+			cronJob := &cronjobv1.CronJob{
+				TypeMeta: metav1.TypeMeta{
+					APIVersion: "batch.tutorial.kubebuilder.io/v1",
+					Kind:       "CronJob",
+				},
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      CronjobName,
+					Namespace: CronjobNamespace,
+				},
+				Spec: cronjobv1.CronJobSpec{
+					Schedule: "1 * * * *",
+					JobTemplate: batchv1beta1.JobTemplateSpec{
+						Spec: batchv1.JobSpec{
+							// For simplicity, we only fill out the required fields.
+							Template: v1.PodTemplateSpec{
+								Spec: v1.PodSpec{
+									// For simplicity, we only fill out the required fields.
+									Containers: []v1.Container{
+										{
+											Name:  "test-container",
+											Image: "test-image",
+										},
+									},
+									RestartPolicy: v1.RestartPolicyOnFailure,
+								},
+							},
+						},
+					},
+				},
+			}
+			Expect(k8sClient.Create(ctx, cronJob)).Should(Succeed())
+
+			/*
+				After creating this CronJob, let's check that the CronJob's Spec fields match what we passed in.
+				Note that, because the k8s apiserver may not have finished creating a CronJob after our `Create()` call from earlier, we will use Gomega’s Eventually() testing function instead of Expect() to give the apiserver an opportunity to finish creating our CronJob.
+
+				`Eventually()` will repeatedly run the function provided as an argument every interval seconds until
+				(a) the function’s output matches what’s expected in the subsequent `Should()` call, or
+				(b) the number of attempts * interval period exceed the provided timeout value.
+
+				In the examples below, timeout and interval are Go Duration values of our choosing.
+			*/
+
+			cronjobLookupKey := types.NamespacedName{Name: CronjobName, Namespace: CronjobNamespace}
+			createdCronjob := &cronjobv1.CronJob{}
+
+			// We'll need to retry getting this newly created CronJob, given that creation may not immediately happen.
+			Eventually(func() bool {
+				err := k8sClient.Get(ctx, cronjobLookupKey, createdCronjob)
+				if err != nil {
+					return false
+				}
+				return true
+			}, timeout, interval).Should(BeTrue())
+			Expect(createdCronjob.Spec.Schedule).Should(Equal("1 * * * *"))
+			/*
+				Now that we've created a CronJob in our test cluster, the next step is to write a test that actually tests our CronJob controller’s behavior.
+				Let’s test the CronJob controller’s logic responsible for updating CronJob.Status.Active with actively running jobs.
+				We’ll verify that when a CronJob has a single active downstream Job, its CronJob.Status.Active field contains a reference to this Job.
+
+				First, we should get the test CronJob we created earlier, and verify that it currently does not have any active jobs.
+				We use Gomega's `Consistently()` check here to ensure that the active job count remains 0 over a duration of time.
+			*/
+			By("By checking the CronJob has zero active Jobs")
+			Consistently(func() (int, error) {
+				err := k8sClient.Get(ctx, cronjobLookupKey, createdCronjob)
+				if err != nil {
+					return -1, err
+				}
+				return len(createdCronjob.Status.Active), nil
+			}, duration, interval).Should(Equal(0))
+			/*
+				Next, we actually create a stubbed Job that will belong to our CronJob, as well as its downstream template specs.
+				We set the Job's status's "Active" count to 2 to simulate the Job running two pods, which means the Job is actively running.
+
+				We then take the stubbed Job and set its owner reference to point to our test CronJob.
+				This ensures that the test Job belongs to, and is tracked by, our test CronJob.
+				Once that’s done, we create our new Job instance.
+			*/
+			By("By creating a new Job")
+			testJob := &batchv1.Job{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      JobName,
+					Namespace: CronjobNamespace,
+				},
+				Spec: batchv1.JobSpec{
+					Template: v1.PodTemplateSpec{
+						Spec: v1.PodSpec{
+							// For simplicity, we only fill out the required fields.
+							Containers: []v1.Container{
+								{
+									Name:  "test-container",
+									Image: "test-image",
+								},
+							},
+							RestartPolicy: v1.RestartPolicyOnFailure,
+						},
+					},
+				},
+				Status: batchv1.JobStatus{
+					Active: 2,
+				},
+			}
+
+			// Note that your CronJob’s GroupVersionKind is required to set up this owner reference.
+			kind := reflect.TypeOf(cronjobv1.CronJob{}).Name()
+			gvk := cronjobv1.GroupVersion.WithKind(kind)
+
+			controllerRef := metav1.NewControllerRef(createdCronjob, gvk)
+			testJob.SetOwnerReferences([]metav1.OwnerReference{*controllerRef})
+			Expect(k8sClient.Create(ctx, testJob)).Should(Succeed())
+			/*
+				Adding this Job to our test CronJob should trigger our controller’s reconciler logic.
+				After that, we can write a test that evaluates whether our controller eventually updates our CronJob’s Status field as expected!
+			*/
+			By("By checking that the CronJob has one active Job")
+			Eventually(func() ([]string, error) {
+				err := k8sClient.Get(ctx, cronjobLookupKey, createdCronjob)
+				if err != nil {
+					return nil, err
+				}
+
+				names := []string{}
+				for _, job := range createdCronjob.Status.Active {
+					names = append(names, job.Name)
+				}
+				return names, nil
+			}, timeout, interval).Should(ConsistOf(JobName), "should list our active job %s in the active jobs list in status", JobName)
+		})
+	})
+
+})
+
+/*
+	After writing all this code, you can run `go test ./...` in your `controllers/` directory again to run your new test!
+*/

docs/book/src/cronjob-tutorial/testdata/project/controllers/suite_test.go

@@ -0,0 +1,154 @@
+/*
+When we created the CronJob API with `kubebuilder create api` in a [previous chapter](/cronjob-tutorial/new-api.md), Kubebuilder already did some test work for you.
+Kubebuilder scaffolded a `controllers/suite_test.go` file that does the bare bones of setting up a test environment.
+
+First, it will contain the necessary imports.
+*/
+
+/*
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+// +kubebuilder:docs-gen:collapse=Apache License
+
+package controllers
+
+import (
+	"path/filepath"
+	"testing"
+
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+	"k8s.io/client-go/kubernetes/scheme"
+	"k8s.io/client-go/rest"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/envtest"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+	"sigs.k8s.io/controller-runtime/pkg/log/zap"
+
+	batchv1 "tutorial.kubebuilder.io/project/api/v1"
+	// +kubebuilder:scaffold:imports
+)
+
+// These tests use Ginkgo (BDD-style Go testing framework). Refer to
+// http://onsi.github.io/ginkgo/ to learn more about Ginkgo.
+
+// +kubebuilder:docs-gen:collapse=Imports
+
+/*
+Now, let's go through the code generated.
+*/
+
+var cfg *rest.Config
+var k8sClient client.Client // You'll be using this client in your tests.
+var testEnv *envtest.Environment
+
+var _ = BeforeSuite(func(done Done) {
+	logf.SetLogger(zap.LoggerTo(GinkgoWriter, true))
+
+	/*
+		First, the envtest cluster is configured to read CRDs from the CRD directory Kubebuilder scaffolds for you.
+	*/
+	By("bootstrapping test environment")
+	testEnv = &envtest.Environment{
+		CRDDirectoryPaths: []string{filepath.Join("..", "config", "crd", "bases")},
+	}
+
+	/*
+		Then, we start the envtest cluster.
+	*/
+	var err error
+	cfg, err = testEnv.Start()
+	Expect(err).ToNot(HaveOccurred())
+	Expect(cfg).ToNot(BeNil())
+
+	/*
+		The autogenerated test code will add the CronJob Kind schema to the default client-go k8s scheme.
+		This ensures that the CronJob API/Kind will be used in our test controller.
+	*/
+	err = batchv1.AddToScheme(scheme.Scheme)
+	Expect(err).NotTo(HaveOccurred())
+	/*
+		After the schemas, you will see the following marker.
+		This marker is what allows new schemas to be added here automatically when a new API is added to the project.
+	*/
+
+	// +kubebuilder:scaffold:scheme
+
+	/*
+		A client is created for our test CRUD operations.
+	*/
+	k8sClient, err = client.New(cfg, client.Options{Scheme: scheme.Scheme})
+	Expect(err).ToNot(HaveOccurred())
+	Expect(k8sClient).ToNot(BeNil())
+
+	/*
+		One thing that this autogenerated file is missing, however, is a way to actually start your controller.
+		The code above will set up a client for interacting with your custom Kind,
+		but will not be able to test your controller behavior.
+		If you want to test your custom controller logic, you’ll need to add some familiar-looking manager logic
+		to your BeforeSuite() function, so you can register your custom controller to run on this test cluster.
+
+		You may notice that the code below runs your controller with nearly identical logic to your CronJob project’s main.go!
+		The only difference is that the manager is started in a separate goroutine so it does not block the cleanup of envtest
+		when you’re done running your tests.
+
+		Once you've added the code below, you can actually delete the k8sClient above, because you can get k8sClient from the manager
+		(as shown below).
+	*/
+
+	k8sManager, err := ctrl.NewManager(cfg, ctrl.Options{
+		Scheme: scheme.Scheme,
+	})
+	Expect(err).ToNot(HaveOccurred())
+
+	err = (&CronJobReconciler{
+		Client: k8sManager.GetClient(),
+		Log:    ctrl.Log.WithName("controllers").WithName("CronJob"),
+	}).SetupWithManager(k8sManager)
+	Expect(err).ToNot(HaveOccurred())
+
+	go func() {
+		err = k8sManager.Start(ctrl.SetupSignalHandler())
+		Expect(err).ToNot(HaveOccurred())
+	}()
+
+	k8sClient = k8sManager.GetClient()
+	Expect(k8sClient).ToNot(BeNil())
+
+	close(done)
+}, 60)
+
+/*
+Kubebuilder also generates boilerplate functions for cleaning up envtest and actually running your test files in your controllers/ directory.
+You won't need to touch these.
+*/
+
+var _ = AfterSuite(func() {
+	By("tearing down the test environment")
+	err := testEnv.Stop()
+	Expect(err).ToNot(HaveOccurred())
+})
+
+func TestAPIs(t *testing.T) {
+	RegisterFailHandler(Fail)
+
+	RunSpecsWithDefaultAndCustomReporters(t,
+		"Controller Suite",
+		[]Reporter{envtest.NewlineReporter{}})
+}
+
+/*
+Now that you have your controller running on a test cluster and a client ready to perform operations on your CronJob, we can start writing integration tests!
+*/