Merge pull request #120 from serenity-js/docs/integration-docker

Docs/integration docker

Author: jan-molak

src/components/DynamicCodeBlock/index.tsx

@@ -0,0 +1,69 @@
+import React, { useEffect, useRef, useState } from 'react';
+import CodeBlock from '@theme/CodeBlock';
+
+/**
+ * Usage example:
+ *
+ * ```mdx
+ * <DynamicCodeBlock
+ *   lang="bash"
+ *   title="Install from the command line"
+ *   highlight="1"
+ * >
+ * {`docker pull ghcr.io/serenity-js/playwright:v`}<PlaywrightVersion />{`-noble`}
+ * </DynamicCodeBlock>
+ * ```
+ *
+ * @param children
+ * @param lang
+ * @param title
+ * @param highlight
+ * @constructor
+ */
+export default function DynamicCodeBlock({ children, lang, title, highlight }) {
+    const tempRef = useRef(null);
+    const [ plainText, setPlainText ] = useState('');
+
+    useEffect(() => {
+        if (tempRef.current) {
+            // Extract innerText after slight delay to ensure children fully rendered
+            const timer = setTimeout(() => {
+                setPlainText(tempRef.current.innerText || '');
+            }, 0);
+            return () => clearTimeout(timer);
+        }
+    }, [ children ]);
+
+    const metastring = highlight ? `{${ highlight }}` : '';
+
+    return (
+        <>
+            {/* Offscreen positioned container to render and extract text */ }
+            <div
+                ref={ tempRef }
+                style={ {
+                    position: 'absolute',
+                    left: -9999,
+                    top: 0,
+                    whiteSpace: 'pre-wrap',
+                    pointerEvents: 'none',
+                    userSelect: 'text',
+                    height: 0,
+                    overflow: 'hidden',
+                } }
+                aria-hidden="true"
+            >
+                { children }
+            </div>
+
+            {/* Render the extracted plainText in CodeBlock */ }
+            <CodeBlock
+                className={ lang ? `language-${ lang }` : undefined }
+                title={ title }
+                metastring={ metastring }
+            >
+                { plainText }
+            </CodeBlock>
+        </>
+    );
+}

src/components/SupportedIntegrationVersion/index.tsx

@@ -0,0 +1,37 @@
+import React from 'react'
+import { usePluginData } from '@docusaurus/core/lib/client/exports/useGlobalData';
+
+export interface SupportedIntegrationVersionProps {
+    format?: 'exact' | 'original';
+    name?: string;
+}
+
+export default function SupportedIntegrationVersion({ format = 'original', name }: SupportedIntegrationVersionProps) {
+
+    const pluginData = usePluginData('docusaurus-plugin-serenity-js-presets') as {
+        integrationsOfInterest?: string[];
+        integrations?: Record<string, string>;
+        packages?: Record<string, string>;
+    };
+
+    // const integrationsOfInterest = pluginData?.integrationsOfInterest || [];
+    const integrations = pluginData?.integrations || {};
+
+    if (! name) {
+        console.warn('SupportedIntegrationVersion: name prop is required when format="version"');
+        return <span>N/A</span>;
+    }
+    const originalVersion = integrations[name];
+    if (! originalVersion) {
+        return <span>N/A</span>;
+    }
+
+    if (format === 'exact') {
+        // Extract the version number from the range (e.g., "^1.56.1" -> "1.56.1")
+        const versionMatch = originalVersion.match(/[\d.]+/);
+        return <span>{ versionMatch ? versionMatch[0] : originalVersion }</span>;
+    }
+
+    return <span>{ originalVersion }</span>;
+}
+

src/docs/handbook/integration/docker.mdx

@@ -0,0 +1,57 @@
+---
+title: Docker
+---
+export const PlaywrightVersion = () => <SupportedIntegrationVersion name="playwright-core" format="exact" />;
+
+# Docker
+
+Serenity/JS Docker images enable you to run Serenity/JS tests in containerised environments,
+including CI/CD pipelines, cloud development environments, and local development setups.
+
+## Using Serenity/JS Docker Images
+
+Learn how to integrate Serenity/JS Docker images with your workflow:
+
+- [GitHub Actions](/handbook/integration/github-actions/)
+- [GitHub Codespaces](/handbook/integration/github-codespaces/)
+- [GitLab CI](/handbook/integration/gitlab-ci/)
+
+## Available Images
+
+The Serenity/JS Docker images are maintained in the [serenity-js/serenity-js-docker](https://github.com/serenity-js/serenity-js-docker) repository
+and published through the [Serenity/JS GitHub Container Registry](https://github.com/orgs/serenity-js/packages).
+
+### Serenity/JS Playwright
+
+**Recommended for**: [Playwright Test](/handbook/test-runners/playwright-test/),
+[Cucumber.js with Playwright](/handbook/test-runners/cucumber/), and [WebdriverIO](/handbook/test-runners/webdriverio/) projects using modern browsers.
+
+The Serenity/JS Playwright Docker image provides a complete testing environment with all **Playwright browser engines**, plus the latest stable **Chrome** and **Edge** browsers.
+Image versions follow Playwright's versioning convention to ensure compatibility.
+
+<DynamicCodeBlock lang="bash" title="Install from the command line" >
+{`docker pull ghcr.io/serenity-js/playwright:v`}<PlaywrightVersion />{`-noble`}
+</DynamicCodeBlock>
+
+**📦 [View all versions](https://github.com/serenity-js/serenity-js-docker/pkgs/container/playwright)**
+
+#### What's Included
+
+**Browsers:**
+- Microsoft Edge (Stable)
+- Google Chrome (Stable)
+- Playwright Chromium Engine
+- Playwright Chromium Headless Shell
+- Playwright Firefox Engine
+- Playwright WebKit Engine
+
+**Runtimes:**
+- Node.js 24
+- OpenJDK Java Runtime Environment
+
+**Operating System:**
+- Ubuntu 24.04 LTS (Noble Numbat)
+- Git
+- cURL
+- OpenSSH Client
+- Playwright system dependencies

src/docs/handbook/integration/github-codespaces.mdx

@@ -0,0 +1,7 @@
+---
+title: GitHub Codespaces
+---
+
+# GitHub Codespaces
+
+<ArticleComingSoon />

src/plugins/presets/index.ts

@@ -37,6 +37,55 @@ export default async function pluginPresets(
     return {
         name: 'docusaurus-plugin-serenity-js-presets',
 
+        async loadContent() {
+            // module-manager preset
+            const paths = await glob(input, { onlyFiles: false, globstar: true, absolute: true });
+
+            const packages = {};
+            let integrations = {};
+
+            for (const pathToPackageJSON of paths) {
+                const serenityPackage = JSON.parse(fs.readFileSync(pathToPackageJSON).toString('utf8'));
+
+                const dependencies = {
+                    ...serenityPackage.dependencies,
+                    ...serenityPackage.peerDependencies,
+                };
+
+                const packageIntegrations = Object.keys(dependencies)
+                    .filter(dependency => options.integrationsOfInterest.includes(dependency))
+                    .reduce((acc, key) => {
+                        acc[key] = dependencies[key];
+                        return acc;
+                    }, {});
+
+                integrations = {
+                    ...integrations,
+                    ...packageIntegrations,
+                }
+
+                packages[serenityPackage.name] = serenityPackage.version;
+            }
+
+            return {
+                engines: rootPackageJson.engines,
+                packages,
+                integrations,
+                integrationsOfInterest: options.integrationsOfInterest,
+                caching,
+                sampling,
+            };
+        },
+
+        async contentLoaded({ content, actions }) {
+            const { setGlobalData } = actions;
+            setGlobalData({
+                integrationsOfInterest: content.integrationsOfInterest,
+                integrations: content.integrations,
+                packages: content.packages,
+            });
+        },
+
         async postBuild({ siteConfig, routesPaths, outDir, head }) {
 
             // module-manager preset

src/theme/MDXComponents.ts

@@ -3,10 +3,12 @@ import ArticleComingSoon from '@site/src/components/ArticleComingSoon'
 import BrowserWindow from '@site/src/components/BrowserWindow'
 import CurrentNodeVersion from '@site/src/components/CurrentNodeVersion'
 import DependencyTypeDescription from '@site/src/components/DependencyTypeDescription'
+import DynamicCodeBlock from '@site/src/components/DynamicCodeBlock';
 import Figure from '@site/src/components/Figure'
 import NpmLink from '@site/src/components/NpmLink'
 import SupportedNodeVersions from '@site/src/components/SupportedNodeVersions'
 import SemanticVersionRangeDescription from '@site/src/components/SemanticVersionRangeDescription'
+import SupportedIntegrationVersion from '@site/src/components/SupportedIntegrationVersion';
 import CodeBlock from '@theme/CodeBlock';
 import Image from '@theme/IdealImage';
 import MDXComponents from '@theme-original/MDXComponents'
@@ -22,11 +24,13 @@ export default {
     CurrentNodeVersion,
     CodeBlock,
     DependencyTypeDescription,
+    DynamicCodeBlock,
     Image,
     NpmLink,
     Tabs,
     TabItem,
     SemanticVersionRangeDescription,
+    SupportedIntegrationVersion,
     SupportedNodeVersions,
     Figure
 }