ci(docs): spread test documentation

.github/workflows/spread-docs.yaml

@@ -0,0 +1,45 @@
+name: Spread tests for docs
+on:
+  pull_request:
+    paths:
+      - spread.yaml
+      - docs/**/code/**
+  push:
+    branches:
+      - main
+    paths:
+      - spread.yaml
+      - docs/**/code/**
+  schedule:
+    - cron: "0 0 * * 0" # Midnight UTC on Sundays
+
+jobs:
+  docs-tests:
+    runs-on: spread-installed
+    steps:
+      - name: Cleanup job workspace
+        run: |
+          rm -rf "${{ github.workspace }}"
+          mkdir "${{ github.workspace }}"
+
+      - name: Checkout charmcraft
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: true
+
+      - name: Download snap from store
+        run: |
+          snap download --edge charmcraft
+
+      - name: Run spread
+        run: |
+          spread google:docs/howto/code/ google:docs/tutorial/code/
+
+      - name: Discard spread workers
+        if: always()
+        run: |
+          shopt -s nullglob
+          for r in .spread-reuse.*.yaml; do
+            spread -discard -reuse-pid="$(echo "$r" | grep -o -E '[0-9]+')"
+          done

docs/howto/code/flask-async/task.yaml

@@ -11,6 +11,10 @@ kill-timeout: 90m
 
 environment:
 
+prepare: |
+  juju destroy-model flask-async-app --destroy-storage --no-prompt --force || true
+  juju destroy-controller --force --destroy-all-models --destroy-storage --no-prompt --no-wait dev-controller || true
+
 execute: |
   # Move everything to $HOME so that Juju deployment works
   mv *.yaml *.py *.txt $HOME
@@ -89,8 +93,6 @@ execute: |
   charmcraft init --profile flask-framework --name flask-async-app
   # [docs:charm-init-end]
 
-  sed -i "s/paas-charm.*/https:\/\/github.com\/canonical\/paas-charm\/archive\/async-workers.tar.gz/g" requirements.txt
-
   # [docs:charm-pack]
   charmcraft pack
   # [docs:charm-pack-end]
@@ -160,7 +162,8 @@ execute: |
   end_time=$(date +%s)
   overall_passtime=$((end_time - overall_start_time))
   echo "Total pass time: $overall_passtime"
-  if [ $((3 < overall_passtime)) -eq 1 ]; then
+  # If this takes more than 60 seconds we probably have an issue.
+  if [ $((60 < overall_passtime)) -eq 1 ]; then
     echo "Error!"
     ASYNC_RESULT='FALSE'
     exit 2
@@ -176,7 +179,14 @@ execute: |
   rm -rf charm .venv __pycache__
   # delete all the files created during the tutorial
   rm flask-async-app_0.1_$(dpkg --print-architecture).rock rockcraft.yaml app.py \
-    requirements.txt migrate.py
+    requirements.txt
   # Remove the juju model
   juju destroy-model flask-async-app --destroy-storage --no-prompt --force
   # [docs:clean-environment-end]
+
+restore: |
+  # Destroy the model on restore just in case the test failed.
+  juju destroy-model flask-async-app --destroy-storage --no-prompt --force || true
+
+  # Destroy the controller
+  juju destroy-controller --force --destroy-all-models --destroy-storage --no-prompt --no-wait dev-controller || true

docs/tutorial/code/flask/task.yaml

@@ -21,19 +21,6 @@ execute: |
   unset CHARMCRAFT_UPLOAD_URL
   unset CHARMCRAFT_REGISTRY_URL
 
-  # Add setup instructions
-  # (Ran into issues in prepare section)
-  # (don't install charmcraft)
-  snap install rockcraft --classic
-  snap install lxd
-  lxd init --auto
-  snap install microk8s --channel=1.31-strict/stable
-  snap refresh juju --channel=3.5/stable --amend
-
-  # Juju config setup
-  lxc network set lxdbr0 ipv6.address none
-  mkdir -p ~/.local/share
-
   # MicroK8s config setup
   microk8s status --wait-ready
   microk8s enable hostpath-storage

spread.yaml

@@ -5,8 +5,8 @@
   PROJECT_PATH: /charmcraft
   SNAPD_TESTING_TOOLS: $PROJECT_PATH/tools/external/tools
   PATH: /snap/bin:$PATH:$SNAPD_TESTING_TOOLS
-  CRAFT_DEBUG: 1  # Show exception tracebacks.
-  CRAFT_VERBOSITY_LEVEL: debug  # Show debugging output when failing.
+  CRAFT_DEBUG: 1 # Show exception tracebacks.
+  CRAFT_VERBOSITY_LEVEL: debug # Show debugging output when failing.
   # Use the staging store for tests:
   CHARMCRAFT_STORE_API_URL: https://api.staging.charmhub.io
   CHARMCRAFT_UPLOAD_URL: https://storage.staging.snapcraftcontent.com
@@ -33,6 +33,7 @@
           storage: 40G
       - ubuntu-22.04-64:
           workers: 6
+          memory: 8G
           storage: 40G
 
   multipass:
@@ -134,12 +135,37 @@
   docs/howto/code/:
     summary: tests howto from the docs
     systems:
-      - ubuntu-24.04-64
+      - ubuntu-22.04-64
+    manual: true
+    prepare: |
+      juju_channel=3.5/stable
+      microk8s_channel=1.31-strict/stable
+
+      mkdir -p ~/.local/share  # Workaround for Juju not being able to create the directory
+
+      #shellcheck source=tests/spread/tools/prepare.sh
+      . "/charmcraft/tests/spread/tools/prepare.sh"
+
+      refresh_or_install_snap juju "$juju_channel"
+      refresh_or_install_snap microk8s "$microk8s_channel"
+      refresh_or_install_snap rockcraft latest/stable --classic
   docs/tutorial/code/:
     summary: tests tutorial from the docs
     systems:
       - ubuntu-22.04-64
     manual: true
+    prepare: |
+      juju_channel=3.5/stable
+      microk8s_channel=1.31-strict/stable
+
+      mkdir -p ~/.local/share  # Workaround for Juju not being able to create the directory
+
+      #shellcheck source=tests/spread/tools/prepare.sh
+      . "/charmcraft/tests/spread/tools/prepare.sh"
+
+      refresh_or_install_snap juju "$juju_channel"
+      refresh_or_install_snap microk8s "$microk8s_channel"
+      refresh_or_install_snap rockcraft latest/stable --classic
   tests/spread/commands/:
     summary: simple charmcraft commands
   tests/spread/charms/:
@@ -174,8 +200,8 @@
     summary: test charm dependencies
     systems:
       - ubuntu-22.04-64
-    kill-timeout: 60m  # Setting up Juju can take a while.
-    priority: 50  # Because setting up Juju takes a while, do these first.
+    kill-timeout: 60m # Setting up Juju can take a while.
+    priority: 50 # Because setting up Juju takes a while, do these first.
     prepare: |
       snap install juju --channel=3.2/stable
       # Set up Juju controllers for the charms

tests/spread/tools/prepare.sh

@@ -9,3 +9,13 @@ install_charmcraft()
         exit 1
     fi
 }
+
+refresh_or_install_snap()
+{
+  # Refresh a snap or, if it's not installed, install it.
+  # args:
+  #  1. snap name
+  #  2. Channel
+  #  3?. Extra arguments to snap install
+  snap refresh "$1" --channel="$2" || snap install "$1" --channel="$2" "${@:3}"
+}