gitee.com/leisunstar/runtime@v0.0.0-20200521203717-5cef3e7b53f9/pkg/katatestutils/README.md (about) 1 # Kata test utilities 2 3 * [Test Constraints](#test-constraints) 4 * [Usage](#usage) 5 * [Displaying the `TestConstraint`](#displaying-the-testconstraint) 6 * [Associating an issue with a constraint](#associating-an-issue-with-a-constraint) 7 * [Examples](#examples) 8 * [Skip tests based on user](#skip-tests-based-on-user) 9 * [Skip tests based on distro](#skip-tests-based-on-distro) 10 * [Skip tests based on kernel version](#skip-tests-based-on-kernel-version) 11 * [Full details](#full-details) 12 13 This package provides a small set of test utilities. See the 14 [GoDoc](https://godoc.org/github.com/kata-containers/runtime/pkg/katatestutils) 15 for full details. 16 17 ## Test Constraints 18 19 This package provides helper functions that accept user-specified constraints 20 that allow you to skip tests. 21 22 ### Usage 23 24 Create a `TestConstraint` object using the `NewTestConstraint()` constructor. 25 This takes a single boolean parameter that specifies if debug output is generated. 26 27 In each test that has particular test constraints, call the `NotValid()` 28 method on the `TestConstraint` object, passing one or more constraints that 29 you want to be valid. 30 31 The `NotValid()` function returns `true` if any of the specified constraints 32 are not available. This allows for a more natural way to code an arbitrarily 33 complex test skip as shown in the following example. 34 35 The main object is created in the `init()` function to make it available for 36 all tests: 37 38 ```go 39 40 import ktu "katatestutils" 41 42 var tc ktu.TestConstraint 43 44 func init() { 45 tc = NewTestConstraint(true) 46 } 47 48 func TestFoo(t *testing.T) { 49 50 // Specify one or more constraint functions. If not satisfied, the test 51 // will be skipped. 52 if tc.NotValid(...) { 53 t.Skip("skipping test") 54 } 55 56 // Test code ... 57 } 58 ``` 59 60 #### Displaying the `TestConstraint` 61 62 Note that you could add the `TestConstraint` object to the `Skip()` call as it 63 will provide details of why the skip occurred: 64 65 ```go 66 if tc.NotValid(...) { 67 t.Skipf("skipping test as requirements not met: %v", tc) 68 } 69 ``` 70 71 #### Associating an issue with a constraint 72 73 You can add a constraint which specifies an issue URL for the skip. No 74 checking is performed on the issue but if specified, it will be added to the 75 `TestConstraint` and recorded in error messages and when that object is 76 displayed: 77 78 ```go 79 if tc.NotValid(WithIssue("https://github.com/kata-containers/runtime/issues/1586"), ...) { 80 t.Skipf("skipping test as requirements not met: %v", tc) 81 } 82 ``` 83 84 ### Examples 85 86 #### Skip tests based on user 87 88 Use the `NeedRoot()` constraint to skip a test unless running as `root`: 89 90 ```go 91 func TestOnlyRunWhenRoot(t *testing.T) { 92 93 if tc.NotValid(ktu.NeedRoot()) { 94 t.Skip("skipping test as not running as root user") 95 } 96 97 // Test code to run as root user ... 98 } 99 ``` 100 101 Use the `NeedNonRoot()` constraint to skip a test unless running as a 102 non-`root` user: 103 104 ```go 105 func TestOnlyRunWhenNotRoot(t *testing.T) { 106 107 if tc.NotValid(ktu.NeedNonRoot()) { 108 t.Skip("skipping test as running as root user") 109 } 110 111 // Test code to run as non-root user ... 112 } 113 ``` 114 115 #### Skip tests based on distro 116 117 Use the `NeedDistro()` constraint to skip a test unless running on a 118 particular Linux distribution: 119 120 ```go 121 func TestOnlyRunOnUbuntu(t *testing.T) { 122 123 if tc.NotValid(ktu.NeedDistro("ubuntu")) { 124 t.Skip("skipping test as not running on ubuntu") 125 } 126 127 // Test code to run on Ubuntu only ... 128 } 129 ``` 130 131 Use the `NeedDistroNotEquals()` constraint to skip a test unless running 132 on a Linux distribution other than the one specified: 133 134 ```go 135 func TestDontRunOnFedora(t *testing.T) { 136 137 if tc.NotValid(ktu.NeedDistroNotEquals("fedora")) { 138 t.Skip("skipping test as running on fedora") 139 } 140 141 // Test code to run on any distro apart from Fedora ... 142 } 143 ``` 144 145 #### Skip tests based on kernel version 146 147 Use the `NeedKernelVersionGE()` constraint to skip a test unless running on a 148 system with at least the specified kernel version: 149 150 ```go 151 func TestNewKernelVersion(t *testing.T) { 152 153 if tc.NotValid(ktu.NeedKernelVersionGE("5.0.10")) { 154 t.Skip("skipping test as kernel is too old") 155 } 156 157 // Test code to run on specified kernel version (or newer) ... 158 } 159 ``` 160 161 Use the `NeedKernelVersionLT()` constraint to skip a test unless running on a 162 system whose kernel is older than the specified kernel version: 163 164 ```go 165 func TestOldKernelVersion(t *testing.T) { 166 167 if tc.NotValid(ktu.NeedKernelVersionLT("4.14.114")) { 168 t.Skip("skipping test as kernel is too new") 169 } 170 171 // Test code to run on specified kernel version (or newer) ... 172 } 173 ``` 174 175 ### Full details 176 177 The public API is shown in [`constraints_api.go`](constraints_api.go) or 178 the [GoDoc](https://godoc.org/github.com/kata-containers/runtime/pkg/katatestutils).