diff --git a/.github/workflows/toc.yaml b/.github/workflows/toc.yaml new file mode 100644 index 0000000..44389a8 --- /dev/null +++ b/.github/workflows/toc.yaml @@ -0,0 +1,13 @@ +name: TOC Generator + +on: + push: + branches: + - "master" + +jobs: + generateTOC: + name: TOC Generator + runs-on: ubuntu-latest + steps: + - uses: technote-space/toc-generator@v4 diff --git a/README.md b/README.md index abd787d..027f202 100644 --- a/README.md +++ b/README.md @@ -11,25 +11,31 @@ This kind of test is the ultimate set of verifications to run for a project, lon ## Table of Contents -* [Objectives](#objectives) -* [Examples](#examples) - * [Test files and result](#test-files-and-result) - * [Working with Kubectl or OC commands](#working-with-kubectl-or-oc-commands) - * [Other Examples](#other-examples) -* [Usage](#usage) - * [Setup](#setup) - * [Executing tests by hand](#executing-tests-by-hand) - * [Continuous Integration](#continuous-integration) -* [Syntax Reference](#syntax-reference) - * [Counting Resources](#counting-resources) - * [Verifying Property Values](#verifying-property-values) - * [Property Names](#property-names) -* [Errors](#errors) - * [Error Codes](#error-codes) - * [Debugging Tests](#debugging-tests) - * [Linting](#linting) - * [Tips](#tips) -* [Beyond K8s assertions](#beyond-k8s-assertions) + + + + +- [Objectives](#objectives) +- [Examples](#examples) + - [Test files and result](#test-files-and-result) + - [Working with Kubectl or OC commands](#working-with-kubectl-or-oc-commands) + - [Other Examples](#other-examples) +- [Usage](#usage) + - [Manual Setup](#manual-setup) + - [Docker Setup](#docker-setup) + - [Continuous Integration](#continuous-integration) +- [Syntax Reference](#syntax-reference) + - [Counting Resources](#counting-resources) + - [Verifying Property Values](#verifying-property-values) + - [Property Names](#property-names) +- [Errors](#errors) + - [Error Codes](#error-codes) + - [Debugging Tests](#debugging-tests) + - [Linting](#linting) + - [Tips](#tips) +- [Beyond K8s assertions](#beyond-k8s-assertions) + + ## Objectives @@ -123,7 +129,7 @@ Since this project works with BATS, you can use **setup** and **teardown** functions to prepare and clean after every test in a file. -## Working with Kubectl or OC commands +### Working with Kubectl or OC commands If you are working with a native Kubernetes cluster. @@ -177,7 +183,7 @@ verify "there are 2 pods named 'nginx'" ``` -## Other Examples +### Other Examples Examples are available under [the eponym directory](examples/ci). It includes... @@ -278,11 +284,14 @@ verify "there are named ''" *resource-type* is one of the K8s ones (e.g. `pods`, `po`, `services`, `svc`...). See [https://kubernetes.io/docs/reference/kubectl/overview/#resource-types](https://kubernetes.io/docs/reference/kubectl/overview/#resource-types) for a complete reference. -This simple assertion may fail sometimes. -As an example, if you count the number of PODs, run your test and then kill the POD, they will still -be listed, with the TERMINATING state. So, most of the time, you will want to verify the number of instances -with a given property value. Example: count the number of PODs with a given name pattern and having the `started` status. -Hence this additional syntax. + +> :warning: This simple assertion may fail sometimes. +> +> As an example, if you count the number of PODs, run your test and then kill the POD, they will still be listed, with the `TERMINATING` state. +> +> So, most of the time, you will want to verify the number of instances with a given property value. Example: count the number of PODs with a given name pattern and having the `started` status. + +Hence this additional syntax (using [next section](#verifying-property-values) documentation to verify additionnal properties): ```bash # Expecting a given number of instances @@ -291,14 +300,14 @@ try "at most times every s \ with '' being ''" ``` -This is a checking loop. +:pushpin: This assertion is useful for PODs, whose life cycle changes take time. +For services, you may directly use the simple count assertions. + +This is a checking loop. It breaks the loop if as soon as the assertion is verified. If it reaches the end of the loop without having been verified, an error is thrown. Please, refer to [this section](#property-names) for details about the property names. -This assertion is useful for PODs, whose life cycle changes take time. -For services, you may directly use the simple count assertions. - ### Verifying Property Values @@ -321,13 +330,13 @@ It breaks the loop if as soon as the assertion is verified. If it reaches the en without having been verified, an error is thrown. Please, refer to [this section](#property-names) for details about the property names. -This assertion verifies all the instances have this property value. -But unlike the assertion type to count resources, you do not verify how many instances have this value. Notice however that **if it finds 0 item verifying the property, the assertion fails**. +:memo: This assertion verifies _all the instances_ have this property value. +But unlike the assertion type to [count resources](#counting-resources), you do not verify _how many instances_ have this value. Notice however that **if it finds 0 item verifying the property, the assertion fails**. ### Property Names -In all assertions, *property-name* if one of the column names supported by K8s. +In all assertions, *property-name* is one of the column names supported by K8s. See https://kubernetes.io/docs/reference/kubectl/overview/#custom-columns You can also find column names by using `kubectl get -o custom-columns=ALL:*`.