ci: sync e2e/README.md to docs

.woodpecker.star

@@ -279,7 +279,7 @@ def main(ctx):
         print("Errors detected. Review messages above.")
         return []
 
-    after = pipelinesDependsOn(afterPipelines(ctx), pnpmCache(ctx)) + designSystemDocs(ctx)
+    after = pipelinesDependsOn(afterPipelines(ctx), pnpmCache(ctx)) + designSystemDocs(ctx) + e2eTestingDocs(ctx)
 
     pipelines = release + before + stages + after
 
@@ -1223,6 +1223,52 @@ def designSystemDocs(ctx):
         "workspace": web_workspace,
     }]
 
+def e2eTestingDocs(ctx):
+    return [{
+        "name": "e2e-testing-docs",
+        "steps": [
+            {
+                "name": "build",
+                "image": OC_CI_NODEJS,
+                "commands": [
+                    "node tests/e2e/scripts/generate-docs.mjs",
+                    # add dummy woodpecker config to disable CI on push to the docs branch
+                    "printf 'def main(ctx):\n    return [{\n        \"name\":\"dummy-pipeline\",\n" +
+                    "        \"steps\":[{\"name\":\"dummy-step\",\"image\":\"alpine:latest\"}],\n" +
+                    "        \"when\":[{\"branch\":[\"main\"]}],\n    }]\n' > tests/e2e/.docs-dist/.woodpecker.star",
+                ],
+            },
+            {
+                "name": "publish",
+                "image": PLUGINS_GH_PAGES,
+                "settings": {
+                    "username": {
+                        "from_secret": "github_username",
+                    },
+                    "password": {
+                        "from_secret": "github_token",
+                    },
+                    "pages_directory": "tests/e2e/.docs-dist/",
+                    "copy_contents": True,
+                    "target_branch": "web-testing-docs",
+                    "delete": True,
+                },
+                "when": [
+                    {
+                        "event": ["push"],
+                        "branch": "${CI_REPO_DEFAULT_BRANCH}",
+                        "path": "tests/e2e/README.md",
+                    },
+                ],
+            },
+        ],
+        "when": [
+            event["pull_request"],
+            event["main_branch"],
+        ],
+        "workspace": web_workspace,
+    }]
+
 def pipelineDependsOn(pipeline, dependant_pipelines):
     if "depends_on" in pipeline.keys():
         pipeline["depends_on"] = pipeline["depends_on"] + getPipelineNames(dependant_pipelines)

tests/e2e/.gitignore

@@ -9,3 +9,6 @@ node_modules/
 
 # Playwright-BDD
 /.features-gen/
+
+# Generated docs page (published to the web-testing-docs branch by CI)
+/.docs-dist/

tests/e2e/README.md

@@ -25,7 +25,7 @@ Feature files (`tests/e2e/features/**/*.feature`) are compiled into Playwright s
 files with [playwright-bdd](https://github.com/vitalets/playwright-bdd):
 
 ```bash
-(cd tests/e2e pnpm bddgen)
+(cd tests/e2e && pnpm bddgen)
 ```
 
 > [!IMPORTANT]

tests/e2e/scripts/generate-docs.mjs

@@ -0,0 +1,89 @@
+// Transforms tests/e2e/README.md into a Docusaurus-ready markdown page and
+// writes it to tests/e2e/.docs-dist/index.md. CI publishes that directory to
+// the `web-testing-docs` branch, which the docs site (opencloud-eu/docs) pulls
+// into docs/dev/web/testing/running-tests via git-batch (.batchfile).
+//
+// Run locally with: node tests/e2e/scripts/generate-docs.mjs
+
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const E2E_DIR = path.resolve(HERE, '..')
+const REPO_ROOT = path.resolve(E2E_DIR, '../..')
+const INPUT = path.join(E2E_DIR, 'README.md')
+const OUT_DIR = path.join(E2E_DIR, '.docs-dist')
+const OUTPUT = path.join(OUT_DIR, 'index.md')
+
+// tests/e2e, relative to the repo root, used to resolve README-relative links.
+const E2E_REL = path.relative(REPO_ROOT, E2E_DIR).split(path.sep).join('/')
+const GH_BLOB = 'https://github.com/opencloud-eu/web/blob/main'
+
+const FRONT_MATTER = `---
+title: 'Running E2E Tests'
+sidebar_position: 1
+id: running-tests
+---
+`
+
+// GitHub alert syntax -> Docusaurus admonitions.
+const ALERT_TYPES = {
+  NOTE: 'note',
+  TIP: 'tip',
+  IMPORTANT: 'info',
+  WARNING: 'warning',
+  CAUTION: 'danger'
+}
+
+function stripTitleAndToc(md) {
+  // Docusaurus renders the title from front matter, so drop the leading H1.
+  md = md.replace(/^#\s+.*\r?\n+/, '')
+  // Drop the hand-maintained "Table of Contents" section (auto-generated by Docusaurus).
+  md = md.replace(/^##\s+Table of Contents\s*\r?\n[\s\S]*?(?=^##\s)/m, '')
+  return md
+}
+
+function convertAlerts(md) {
+  const lines = md.split('\n')
+  const out = []
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^>\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*$/)
+    if (!match) {
+      out.push(lines[i])
+      continue
+    }
+    const type = ALERT_TYPES[match[1]]
+    const body = []
+    while (i + 1 < lines.length && lines[i + 1].startsWith('>')) {
+      i++
+      body.push(lines[i].replace(/^>\s?/, ''))
+    }
+    out.push(`:::${type}`, ...body, ':::')
+  }
+  return out.join('\n')
+}
+
+function rewriteRelativeLinks(md) {
+  // ](./foo) or ](../foo) -> absolute GitHub blob URL, resolved against tests/e2e.
+  return md.replace(/\]\((\.{1,2}\/[^)]+)\)/g, (_full, rel) => {
+    const repoRelative = path.posix.join(E2E_REL, rel)
+    return `](${GH_BLOB}/${repoRelative})`
+  })
+}
+
+async function main() {
+  const readme = await readFile(INPUT, 'utf8')
+  const body = rewriteRelativeLinks(convertAlerts(stripTitleAndToc(readme)))
+  const page = `${FRONT_MATTER}\n${body.replace(/^\n+/, '')}`
+
+  await rm(OUT_DIR, { recursive: true, force: true })
+  await mkdir(OUT_DIR, { recursive: true })
+  await writeFile(OUTPUT, page, 'utf8')
+  console.log(`Wrote ${path.relative(REPO_ROOT, OUTPUT)}`)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})