test: validate sh code-blocks in examples (#273)

Author: kangasta

.github/workflows/examples.yml

@@ -0,0 +1,31 @@
+name: Examples
+on:
+  pull_request:
+    paths:
+      - "**.go"
+      - "go.mod"
+      - "go.sum"
+      - "examples/**.md"
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout head
+        uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+      - name: Setup Go
+        uses: actions/setup-go@fac708d6674e30b6ba41289acaab6d4b75aa0753 # v4.0.1
+        with:
+          go-version-file: "go.mod"
+      - name: Install mdtest and upctl
+        run: |
+          go install github.com/UpCloudLtd/mdtest@latest
+          make build
+          echo "$GITHUB_WORKSPACE/bin" >> $GITHUB_PATH
+      - name: Test examples
+        env:
+          UPCLOUD_USERNAME: ${{ secrets.UPCLOUD_USERNAME }}
+          UPCLOUD_PASSWORD: ${{ secrets.UPCLOUD_PASSWORD }}
+        run: |
+          upctl version
+          mdtest examples/

.github/workflows/test.yml

@@ -6,8 +6,8 @@ on:
       - 'go.mod'
       - 'go.sum'
 jobs:
-  platform_tests:
-    name: Run platform tests
+  unit-tests:
+    name: Run unit-tests
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]

examples/README.md

@@ -1,3 +1,19 @@
 # Examples
 
 This directory contains examples on more complex `upctl` use-cases. As `upctl` is often used in scripts the examples also aim to parse values from machine readable outputs. This allows using the examples also as end-to-end test cases and makes them more copy-pasteable.
+
+## Testing
+
+The examples in this directory are validated with [mdtest](https://github.com/UpCloudLtd/mdtest). It parses `env` and `sh` code-blocks from the markdown files and executes those as scripts.
+
+The tool can be installed with go install.
+
+```sh
+go install github.com/UpCloudLtd/mdtest@latest
+```
+
+To test the examples, run `mdtest .`.
+
+```sh
+mdtest .
+```