Added github sponsor buttons

- add make target test-integration and run it in reusable CI workflow
- add integration unittest covering _page_warnings stderr output + deduplication
- surface Matomo installer warnings during Playwright flow (stderr only)

https://chatgpt.com/share/694c1371-365c-800f-bdf8-ede2e850e648

.github/workflows/publish-image.yml

@@ -3,16 +3,19 @@ name: publish-image
 on:
   push:
     tags:
-      - "*"
+      - "v*.*.*"
+
+  workflow_run:
+    workflows: ["Stable Tag"]   # MUST match stable-tag.yml -> name: Stable Tag
+    types: [completed]
 
 jobs:
-  tests:
-    uses: ./.github/workflows/reusable-test.yml
-
   build-and-push:
-    needs: tests
-    runs-on: ubuntu-latest
+    if: |
+      (github.event_name == 'push') ||
+      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
 
+    runs-on: ubuntu-latest
     permissions:
       contents: read
       packages: write
@@ -20,6 +23,10 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          # push: checks out the tag ref
+          # workflow_run: checks out the exact commit that the Stable Tag workflow ran on
+          ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.ref }}
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
@@ -27,48 +34,34 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Extract tag
-        id: meta
-        run: |
-          echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
-
-      - name: Check semver tag
-        id: semver
-        run: |
-          if [[ "${GITHUB_REF_NAME}" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "is_semver=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "is_semver=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Log in to GHCR
+      - name: Login to GHCR
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build and push (tag)
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: ./Dockerfile
-          push: true
-          platforms: linux/amd64,linux/arm64
-          tags: |
-            ghcr.io/${{ github.repository }}:${{ steps.meta.outputs.tag }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+      - name: Compute tags
+        id: meta
+        shell: bash
+        run: |
+          set -euo pipefail
+          IMAGE="ghcr.io/${{ github.repository }}"
 
-      - name: Build and push (latest)
-        if: steps.semver.outputs.is_semver == 'true'
+          if [ "${{ github.event_name }}" = "push" ]; then
+            TAG="${{ github.ref_name }}"     # e.g. v1.1.0
+            echo "tags=$IMAGE:$TAG,$IMAGE:latest" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=$IMAGE:stable" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push
         uses: docker/build-push-action@v6
         with:
           context: .
           file: ./Dockerfile
           push: true
           platforms: linux/amd64,linux/arm64
-          tags: |
-            ghcr.io/${{ github.repository }}:latest
+          tags: ${{ steps.meta.outputs.tags }}
           cache-from: type=gha
           cache-to: type=gha,mode=max

.github/workflows/reusable-test.yml

@@ -52,6 +52,21 @@ jobs:
           ruff check .
           ruff format --check .
 
+  integration:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Integration tests
+        run: make test-integration
+
   e2e:
     runs-on: ubuntu-latest
     timeout-minutes: 30

CHANGELOG.md

@@ -1,3 +1,13 @@
+## [1.1.2] - 2025-12-24
+
+* **Improved error visibility during Matomo installation**: When the setup fails (for example due to an invalid admin email or missing required fields), the installer now **prints the actual Matomo error messages to the logs**, instead of failing with a generic error.
+
+
+## [1.1.1] - 2025-12-24
+
+* Improved Docker image publishing: automatic `vX.Y.Z`, `latest`, and `stable` tags for releases.
+
+
 ## [1.1.0] - 2025-12-23
 
 * Implemented bootstrap docker image to auto install matomo in docker compose

Makefile

@@ -34,6 +34,7 @@ COMPOSE_STACK := docker compose -f $(COMPOSE_STACK_FILE)
 
 .PHONY: help \
         venv deps-e2e playwright-install e2e-up e2e-install e2e-test e2e-down e2e logs clean \
+        test-integration \
         image-build image-run image-shell image-push image-clean \
         stack-up stack-down stack-logs stack-ps stack-bootstrap stack-rebootstrap stack-clean stack-reset
 
@@ -49,6 +50,7 @@ help:
 	@echo "  e2e                Full cycle: up → install → test → down"
 	@echo "  logs               Show Matomo logs (E2E compose)"
 	@echo "  clean              Stop E2E containers + remove venv"
+	@echo "  test-integration   Run integration tests (unittest)"
 	@echo ""
 	@echo "Container image targets:"
 	@echo "  image-build        Build matomo-bootstrap container image"
@@ -129,6 +131,13 @@ logs:
 clean: e2e-down
 	rm -rf $(VENV_DIR)
 
+# ----------------------------
+# Integration tests
+# ----------------------------
+
+test-integration:
+	PYTHONPATH=src $(PYTHON) -m unittest discover -s tests/integration -v
+
 # ----------------------------
 # Container image workflow
 # ----------------------------

README.md

@@ -1,4 +1,6 @@
 # matomo-bootstrap
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
+
 
 Headless bootstrap tooling for **Matomo**. Automates **first-time installation** and **API token provisioning** for fresh Matomo instances.
 ---

flake.nix

@@ -20,7 +20,7 @@
       rec {
         matomo-bootstrap = python.pkgs.buildPythonApplication {
           pname = "matomo-bootstrap";
-          version = "1.1.0"; # keep in sync with pyproject.toml
+          version = "1.1.2"; # keep in sync with pyproject.toml
           pyproject = true;
           src = self;
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "matomo-bootstrap"
-version = "1.1.0"
+version = "1.1.2"
 description = "Headless bootstrap tooling for Matomo (installation + API token provisioning)"
 readme = "README.md"
 requires-python = ">=3.10"

src/matomo_bootstrap/installers/web.py

@@ -33,6 +33,100 @@ def _log(msg: str) -> None:
     print(msg, file=sys.stderr)
 
 
+def _page_warnings(page, *, prefix: str = "[install]") -> list[str]:
+    """
+    Detect Matomo installer warnings/errors on the current page.
+
+    - Does NOT change any click logic.
+    - Prints found warnings/errors to stderr (stdout stays clean).
+    - Returns a de-duplicated list of warning/error texts (empty if none found).
+    """
+
+    def _safe(s: str | None) -> str:
+        return (s or "").strip()
+
+    # Helpful context (doesn't spam much, but makes failures traceable)
+    try:
+        url = page.url
+    except Exception:
+        url = "<unknown-url>"
+    try:
+        title = page.title()
+    except Exception:
+        title = "<unknown-title>"
+
+    selectors = [
+        # your originals
+        ".warning",
+        ".alert.alert-danger",
+        ".alert.alert-warning",
+        ".notification",
+        ".message_container",
+        # common Matomo / UI patterns seen across versions
+        "#notificationContainer",
+        ".system-check-error",
+        ".system-check-warning",
+        ".form-errors",
+        ".error",
+        ".errorMessage",
+        ".invalid-feedback",
+        ".help-block.error",
+        ".ui-state-error",
+        ".alert-danger",
+        ".alert-warning",
+        "[role='alert']",
+    ]
+
+    texts: list[str] = []
+
+    for sel in selectors:
+        loc = page.locator(sel)
+        try:
+            n = loc.count()
+        except Exception:
+            n = 0
+        if n <= 0:
+            continue
+
+        # collect all matches (not only .first)
+        for i in range(min(n, 50)):  # avoid insane spam if page is weird
+            try:
+                t = _safe(loc.nth(i).inner_text())
+            except Exception:
+                t = ""
+            if t:
+                texts.append(t)
+
+    # Also catch HTML5 validation bubbles / inline field errors
+    # (Sometimes Matomo marks invalid inputs with aria-invalid + sibling text)
+    try:
+        invalid = page.locator("[aria-invalid='true']")
+        n_invalid = invalid.count()
+    except Exception:
+        n_invalid = 0
+
+    if n_invalid > 0:
+        texts.append(f"{n_invalid} field(s) marked aria-invalid=true.")
+
+    # De-duplicate while preserving order
+    seen: set[str] = set()
+    out: list[str] = []
+    for t in texts:
+        if t not in seen:
+            seen.add(t)
+            out.append(t)
+
+    if out:
+        print(
+            f"{prefix} page warnings/errors detected @ {url} ({title}):",
+            file=sys.stderr,
+        )
+        for idx, t in enumerate(out, 1):
+            print(f"{prefix}  {idx}) {t}", file=sys.stderr)
+
+    return out
+
+
 def wait_http(url: str, timeout: int = 180) -> None:
     """
     Consider Matomo 'reachable' as soon as the HTTP server answers - even with 500.
@@ -102,7 +196,6 @@ class WebInstaller(Installer):
         wait_http(base_url)
 
         if is_installed(base_url):
-            if config.debug:
             _log("[install] Matomo already looks installed. Skipping installer.")
             return
 
@@ -120,10 +213,6 @@ class WebInstaller(Installer):
             page.set_default_navigation_timeout(PLAYWRIGHT_NAV_TIMEOUT_MS)
             page.set_default_timeout(PLAYWRIGHT_NAV_TIMEOUT_MS)
 
-            def _dbg(msg: str) -> None:
-                if config.debug:
-                    _log(f"[install] {msg}")
-
             def click_next() -> None:
                 """
                 Matomo installer mixes link/button variants and sometimes includes '»'.
@@ -149,13 +238,11 @@ class WebInstaller(Installer):
                 for role, name in candidates:
                     loc = page.get_by_role(role, name=name)
                     if loc.count() > 0:
-                        _dbg(f"click_next(): {role} '{name}'")
                         loc.first.click()
                         return
 
                 loc = page.get_by_text("Next", exact=False)
                 if loc.count() > 0:
-                    _dbg("click_next(): fallback text 'Next'")
                     loc.first.click()
                     return
 
@@ -164,6 +251,7 @@ class WebInstaller(Installer):
                 )
 
             page.goto(base_url, wait_until="domcontentloaded")
+            _page_warnings(page)
 
             def superuser_form_visible() -> bool:
                 return page.locator("#login-0").count() > 0
@@ -174,6 +262,7 @@ class WebInstaller(Installer):
                 click_next()
                 page.wait_for_load_state("domcontentloaded")
                 page.wait_for_timeout(200)
+                _page_warnings(page)
             else:
                 raise RuntimeError(
                     "Installer did not reach superuser step (login-0 not found)."
@@ -191,12 +280,17 @@ class WebInstaller(Installer):
 
             page.locator("#email-0").click()
             page.locator("#email-0").fill(config.admin_email)
+            _page_warnings(page)
 
             if page.get_by_role("button", name="Next »").count() > 0:
                 page.get_by_role("button", name="Next »").click()
             else:
                 click_next()
 
+            page.wait_for_load_state("domcontentloaded")
+            page.wait_for_timeout(200)
+            _page_warnings(page)
+
             if page.locator("#siteName-0").count() > 0:
                 page.locator("#siteName-0").click()
                 page.locator("#siteName-0").fill(DEFAULT_SITE_NAME)
@@ -205,26 +299,38 @@ class WebInstaller(Installer):
                 page.locator("#url-0").click()
                 page.locator("#url-0").fill(DEFAULT_SITE_URL)
 
+            _page_warnings(page)
+
             try:
                 page.get_by_role("combobox").first.click()
                 page.get_by_role("listbox").get_by_text(DEFAULT_TIMEZONE).click()
             except Exception:
-                _dbg("Timezone selection skipped (not found / changed UI).")
+                _log("Timezone selection skipped (not found / changed UI).")
 
             try:
                 page.get_by_role("combobox").nth(2).click()
                 page.get_by_role("listbox").get_by_text(DEFAULT_ECOMMERCE).click()
             except Exception:
-                _dbg("Ecommerce selection skipped (not found / changed UI).")
+                _log("Ecommerce selection skipped (not found / changed UI).")
+
+            _page_warnings(page)
 
             click_next()
             page.wait_for_load_state("domcontentloaded")
+            page.wait_for_timeout(200)
+            _page_warnings(page)
 
             if page.get_by_role("link", name="Next »").count() > 0:
                 page.get_by_role("link", name="Next »").click()
+                page.wait_for_load_state("domcontentloaded")
+                page.wait_for_timeout(200)
+                _page_warnings(page)
 
             if page.get_by_role("button", name="Continue to Matomo »").count() > 0:
                 page.get_by_role("button", name="Continue to Matomo »").click()
+                page.wait_for_load_state("domcontentloaded")
+                page.wait_for_timeout(200)
+                _page_warnings(page)
 
             context.close()
             browser.close()

tests/integration/test_web_installer_warnings.py

@@ -0,0 +1,128 @@
+import io
+import unittest
+from contextlib import redirect_stderr
+
+
+# Import the function under test.
+# This keeps the test close to real integration behavior without requiring Playwright.
+from matomo_bootstrap.installers.web import _page_warnings
+
+
+class _FakeLocatorNth:
+    def __init__(self, text: str):
+        self._text = text
+
+    def inner_text(self) -> str:
+        return self._text
+
+
+class _FakeLocator:
+    def __init__(self, texts: list[str]):
+        self._texts = texts
+
+    def count(self) -> int:
+        return len(self._texts)
+
+    def nth(self, i: int) -> _FakeLocatorNth:
+        return _FakeLocatorNth(self._texts[i])
+
+
+class _FakePage:
+    """
+    Minimal Playwright-like page stub:
+    - locator(selector) -> object with count() / nth(i).inner_text()
+    - url, title()
+    """
+
+    def __init__(self, *, url: str, title: str, selector_texts: dict[str, list[str]]):
+        self.url = url
+        self._title = title
+        self._selector_texts = selector_texts
+
+    def title(self) -> str:
+        return self._title
+
+    def locator(self, selector: str) -> _FakeLocator:
+        return _FakeLocator(self._selector_texts.get(selector, []))
+
+
+class TestWebInstallerWarningsIntegration(unittest.TestCase):
+    def test_detects_bootstrap_alert_warning_block(self) -> None:
+        """
+        Matomo installer commonly renders validation errors like:
+          <div class="alert alert-warning"> ... <ul><li>...</li></ul> ... </div>
+        We must detect and print those messages to stderr.
+        """
+        page = _FakePage(
+            url="http://matomo/index.php?action=setupSuperUser&module=Installation",
+            title="Superuser",
+            selector_texts={
+                # The key selector from the observed DOM
+                ".alert.alert-warning": [
+                    "Please fix the following errors:\n"
+                    "Password required\n"
+                    "Password (repeat) required\n"
+                    "The email doesn't have a valid format."
+                ],
+            },
+        )
+
+        buf = io.StringIO()
+        with redirect_stderr(buf):
+            warnings = _page_warnings(page, prefix="[install]")
+
+        # Function must return the warning text
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("Please fix the following errors:", warnings[0])
+        self.assertIn("The email doesn't have a valid format.", warnings[0])
+
+        # And it must print it to stderr (stdout must remain token-only in the app)
+        out = buf.getvalue()
+        self.assertIn("[install] page warnings/errors detected", out)
+        self.assertIn("Superuser", out)
+        self.assertIn("The email doesn't have a valid format.", out)
+
+    def test_deduplicates_repeated_warning_blocks(self) -> None:
+        """
+        Some Matomo versions repeat the same alert in multiple containers.
+        We must return/log each unique text only once.
+        """
+        repeated = (
+            "Please fix the following errors:\nThe email doesn't have a valid format."
+        )
+        page = _FakePage(
+            url="http://matomo/index.php?action=setupSuperUser&module=Installation",
+            title="Superuser",
+            selector_texts={
+                ".alert.alert-warning": [repeated, repeated],
+            },
+        )
+
+        buf = io.StringIO()
+        with redirect_stderr(buf):
+            warnings = _page_warnings(page, prefix="[install]")
+
+        self.assertEqual(warnings, [repeated])
+
+        out = buf.getvalue()
+        # Only a single numbered entry should be printed
+        self.assertIn("[install]  1) ", out)
+        self.assertNotIn("[install]  2) ", out)
+
+    def test_no_output_when_no_warnings(self) -> None:
+        page = _FakePage(
+            url="http://matomo/",
+            title="Welcome",
+            selector_texts={},
+        )
+
+        buf = io.StringIO()
+        with redirect_stderr(buf):
+            warnings = _page_warnings(page, prefix="[install]")
+
+        self.assertEqual(warnings, [])
+        self.assertEqual(buf.getvalue(), "")
+
+
+if __name__ == "__main__":
+    unittest.main()