-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Remove documentation advocating for test builders
Instead, recommend that users not use them, and link to the bug with more information/discussion.
- Loading branch information
Showing
5 changed files
with
12 additions
and
250 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,14 +1,3 @@ | ||
| # Builder package for tests | ||
| # PLEASE AVOID USING THIS PACKAGE | ||
|
|
||
| This package holds `Builder` functions that can be used to create struct in | ||
| tests with less noise. | ||
|
|
||
| One of the most important characteristic of a unit test (and any type of test | ||
| really) is **readability**. This means it should be easy to read but most | ||
| importantly it should clearly show the intent of the test. The setup (and | ||
| cleanup) of the tests should be as small as possible to avoid the noise. Those | ||
| builders exists to help with that. | ||
|
|
||
| There is currently two versionned builder supported: | ||
| - [`v1alpha1`](./v1alpha1) | ||
| - [`v1beta1`](./v1beta1) | ||
| See https://github.com/tektoncd/pipeline/issues/3178 for more information |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,119 +1,3 @@ | ||
| # Builder package for tests | ||
| # PLEASE AVOID USING THIS PACKAGE | ||
|
|
||
| This package holds `Builder` functions that can be used to create struct in | ||
| tests with less noise. | ||
|
|
||
| One of the most important characteristic of a unit test (and any type of test | ||
| really) is **readability**. This means it should be easy to read but most | ||
| importantly it should clearly show the intent of the test. The setup (and | ||
| cleanup) of the tests should be as small as possible to avoid the noise. Those | ||
| builders exists to help with that. | ||
|
|
||
| There is two types of functions defined in that package : | ||
|
|
||
| * *Builders*: create and return a struct | ||
| * *Modifiers*: return a function | ||
| that will operate on a given struct. They can be applied to other | ||
| Modifiers or Builders. | ||
|
|
||
| Most of the Builder (and Modifier) that accepts Modifiers defines a type | ||
| (`TypeOp`) that can be satisfied by existing function in this package, from | ||
| other package _or_ inline. An example would be the following. | ||
|
|
||
| ```go | ||
| // Definition | ||
| type TaskRunOp func(*v1alpha1.TaskRun) | ||
| func TaskRun(name, namespace string, ops ...TaskRunOp) *v1alpha1.TaskRun { | ||
| // […] | ||
| } | ||
| func TaskRunOwnerReference(kind, name string) TaskRunOp { | ||
| return func(t *v1alpha1.TaskRun) { | ||
| // […] | ||
| } | ||
| } | ||
| // Usage | ||
| t := TaskRun("foo", "bar", func(t *v1alpha1.TaskRun){ | ||
| // Do something with the Task struct | ||
| // […] | ||
| }) | ||
| ``` | ||
|
|
||
| The main reason to define the `Op` type, and using it in the methods signatures | ||
| is to group Modifier function together. It makes it easier to see what is a | ||
| Modifier (or Builder) and on what it operates. | ||
|
|
||
| By convention, this package is import with the "tb" as alias. The examples make | ||
| that assumption. | ||
|
|
||
| ## Example | ||
|
|
||
| Let's look at a non-exhaustive example. | ||
|
|
||
| ```go | ||
| package builder_test | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "testing" | ||
|
|
||
| "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1" | ||
| tb "github.com/tektoncd/pipeline/internal/builder/v1alpha1" | ||
| corev1 "k8s.io/api/core/v1" | ||
| ) | ||
|
|
||
| func MyTest(t *testing.T) { | ||
| // You can declare re-usable modifiers | ||
| myStep := tb.Step("my-step", "myimage") | ||
| // … and use them in a Task definition | ||
| myTask := tb.Task("my-task", "namespace", tb.TaskSpec( | ||
| tb.Step("simple-step", "myotherimage", tb.Command("/mycmd")), | ||
| myStep, | ||
| )) | ||
| // … and another one. | ||
| myOtherTask := tb.Task("my-other-task", "namespace", | ||
| tb.TaskSpec(myStep, | ||
| tb.TaskInputs(tb.InputsResource("workspace", v1alpha1.PipelineResourceTypeGit)), | ||
| ), | ||
| ) | ||
| myClusterTask := tb.ClusterTask("my-task", tb.ClusterTaskSpec( | ||
| tb.Step("simple-step", "myotherimage", tb.Command("/mycmd")), | ||
| )) | ||
| // A simple definition, with a Task reference | ||
| myTaskRun := tb.TaskRun("my-taskrun", "namespace", tb.TaskRunSpec( | ||
| tb.TaskRunTaskRef("my-task"), | ||
| )) | ||
| // … or a more complex one with inline TaskSpec | ||
| myTaskRunWithSpec := tb.TaskRun("my-taskrun-with-spec", "namespace", tb.TaskRunSpec( | ||
| tb.TaskRunInputs( | ||
| tb.TaskRunInputsParam("myarg", "foo"), | ||
| tb.TaskRunInputsResource("workspace", tb.TaskResourceBindingRef("git-resource")), | ||
| ), | ||
| tb.TaskRunTaskSpec( | ||
| tb.TaskInputs( | ||
| tb.InputsResource("workspace", v1alpha1.PipelineResourceTypeGit), | ||
| tb.InputsParam("myarg", tb.ParamDefault("mydefault")), | ||
| ), | ||
| tb.Step("mycontainer", "myimage", tb.Command("/mycmd"), | ||
| tb.Args("--my-arg=$(inputs.params.myarg)"), | ||
| ), | ||
| ), | ||
| )) | ||
| // Pipeline | ||
| pipeline := tb.Pipeline("tomatoes", "namespace", | ||
| tb.PipelineSpec(tb.PipelineTask("foo", "banana")), | ||
| ) | ||
| // … and PipelineRun | ||
| pipelineRun := tb.PipelineRun("pear", "namespace", | ||
| tb.PipelineRunSpec("tomatoes", tb.PipelineRunServiceAccount("inexistent")), | ||
| ) | ||
| // And do something with them | ||
| // […] | ||
| if _, err := c.PipelineClient.Create(pipeline); err != nil { | ||
| t.Fatalf("Failed to create Pipeline `%s`: %s", "tomatoes", err) | ||
| } | ||
| if _, err := c.PipelineRunClient.Create(pipelineRun); err != nil { | ||
| t.Fatalf("Failed to create PipelineRun `%s`: %s", "pear", err) | ||
| } | ||
| // […] | ||
| } | ||
| ``` | ||
| See https://github.com/tektoncd/pipeline/issues/3178 for more information |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,119 +1,3 @@ | ||
| # Builder package for tests | ||
| # PLEASE AVOID USING THIS PACKAGE | ||
|
|
||
| This package holds `Builder` functions that can be used to create struct in | ||
| tests with less noise. | ||
|
|
||
| One of the most important characteristic of a unit test (and any type of test | ||
| really) is **readability**. This means it should be easy to read but most | ||
| importantly it should clearly show the intent of the test. The setup (and | ||
| cleanup) of the tests should be as small as possible to avoid the noise. Those | ||
| builders exists to help with that. | ||
|
|
||
| There is two types of functions defined in that package : | ||
|
|
||
| * *Builders*: create and return a struct | ||
| * *Modifiers*: return a function | ||
| that will operate on a given struct. They can be applied to other | ||
| Modifiers or Builders. | ||
|
|
||
| Most of the Builder (and Modifier) that accepts Modifiers defines a type | ||
| (`TypeOp`) that can be satisfied by existing function in this package, from | ||
| other package _or_ inline. An example would be the following. | ||
|
|
||
| ```go | ||
| // Definition | ||
| type TaskRunOp func(*v1beta1.TaskRun) | ||
| func TaskRun(name, namespace string, ops ...TaskRunOp) *v1beta1.TaskRun { | ||
| // […] | ||
| } | ||
| func TaskRunOwnerReference(kind, name string) TaskRunOp { | ||
| return func(t *v1beta1.TaskRun) { | ||
| // […] | ||
| } | ||
| } | ||
| // Usage | ||
| t := TaskRun("foo", "bar", func(t *v1beta1.TaskRun){ | ||
| // Do something with the Task struct | ||
| // […] | ||
| }) | ||
| ``` | ||
|
|
||
| The main reason to define the `Op` type, and using it in the methods signatures | ||
| is to group Modifier function together. It makes it easier to see what is a | ||
| Modifier (or Builder) and on what it operates. | ||
|
|
||
| By convention, this package is import with the "tb" as alias. The examples make | ||
| that assumption. | ||
|
|
||
| ## Example | ||
|
|
||
| Let's look at a non-exhaustive example. | ||
|
|
||
| ```go | ||
| package builder_test | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "testing" | ||
|
|
||
| "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1" | ||
| tb "github.com/tektoncd/pipeline/internal/builder/v1beta1" | ||
| corev1 "k8s.io/api/core/v1" | ||
| ) | ||
|
|
||
| func MyTest(t *testing.T) { | ||
| // You can declare re-usable modifiers | ||
| myStep := tb.Step("my-step", "myimage") | ||
| // … and use them in a Task definition | ||
| myTask := tb.Task("my-task", "namespace", tb.TaskSpec( | ||
| tb.Step("simple-step", "myotherimage", tb.Command("/mycmd")), | ||
| myStep, | ||
| )) | ||
| // … and another one. | ||
| myOtherTask := tb.Task("my-other-task", "namespace", | ||
| tb.TaskSpec(myStep, | ||
| tb.TaskInputs(tb.InputsResource("workspace", v1beta1.PipelineResourceTypeGit)), | ||
| ), | ||
| ) | ||
| myClusterTask := tb.ClusterTask("my-task", tb.ClusterTaskSpec( | ||
| tb.Step("simple-step", "myotherimage", tb.Command("/mycmd")), | ||
| )) | ||
| // A simple definition, with a Task reference | ||
| myTaskRun := tb.TaskRun("my-taskrun", "namespace", tb.TaskRunSpec( | ||
| tb.TaskRunTaskRef("my-task"), | ||
| )) | ||
| // … or a more complex one with inline TaskSpec | ||
| myTaskRunWithSpec := tb.TaskRun("my-taskrun-with-spec", "namespace", tb.TaskRunSpec( | ||
| tb.TaskRunInputs( | ||
| tb.TaskRunInputsParam("myarg", "foo"), | ||
| tb.TaskRunInputsResource("workspace", tb.TaskResourceBindingRef("git-resource")), | ||
| ), | ||
| tb.TaskRunTaskSpec( | ||
| tb.TaskInputs( | ||
| tb.InputsResource("workspace", v1beta1.PipelineResourceTypeGit), | ||
| tb.InputsParam("myarg", tb.ParamDefault("mydefault")), | ||
| ), | ||
| tb.Step("mycontainer", "myimage", tb.Command("/mycmd"), | ||
| tb.Args("--my-arg=$(inputs.params.myarg)"), | ||
| ), | ||
| ), | ||
| )) | ||
| // Pipeline | ||
| pipeline := tb.Pipeline("tomatoes", "namespace", | ||
| tb.PipelineSpec(tb.PipelineTask("foo", "banana")), | ||
| ) | ||
| // … and PipelineRun | ||
| pipelineRun := tb.PipelineRun("pear", "namespace", | ||
| tb.PipelineRunSpec("tomatoes", tb.PipelineRunServiceAccount("inexistent")), | ||
| ) | ||
| // And do something with them | ||
| // […] | ||
| if _, err := c.PipelineClient.Create(pipeline); err != nil { | ||
| t.Fatalf("Failed to create Pipeline `%s`: %s", "tomatoes", err) | ||
| } | ||
| if _, err := c.PipelineRunClient.Create(pipelineRun); err != nil { | ||
| t.Fatalf("Failed to create PipelineRun `%s`: %s", "pear", err) | ||
| } | ||
| // […] | ||
| } | ||
| ``` | ||
| See https://github.com/tektoncd/pipeline/issues/3178 for more information |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters