serenity-js · jan-molak · Jul 11, 2025 · Jul 11, 2025 · Jul 11, 2025 · Jul 11, 2025
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
@@ -147,6 +147,7 @@ jobs:
     strategy:
       matrix:
         module:
+          - mcp
           - playwright-test
           - playwright-test-ct
           - playwright-web

diff --git a/integration/mcp/.gitignore b/integration/mcp/.gitignore
@@ -0,0 +1,9 @@
+# Node
+node_modules
+*.log
+
+# Build artifacts
+lib
+playwright-report
+test-results
+output
diff --git a/integration/mcp/package.json b/integration/mcp/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "@integration/mcp",
+  "version": "3.0.0",
+  "description": "Serenity/JS MCP integration tests",
+  "type": "module",
+  "author": {
+    "name": "Jan Molak",
+    "email": "jan.molak@smartcodeltd.co.uk",
+    "url": "https://janmolak.com"
+  },
+  "homepage": "https://serenity-js.org",
+  "license": "Apache-2.0",
+  "private": true,
+  "config": {
+    "access": "private"
+  },
+  "scripts": {
+    "clean": "rimraf playwright-report playwright/.cache",
+    "test": "playwright test --config playwright.config.ts",
+    "inspector": "mcp-inspector npx mcp-server-serenity-js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/serenity-js/serenity-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/serenity-js/serenity-js/issues"
+  },
+  "engines": {
+    "node": "^18.12 || ^20 || ^22"
+  },
+  "dependencies": {
+    "@integration/testing-tools": "workspace:*",
+    "@modelcontextprotocol/inspector": "0.15.0",
+    "@modelcontextprotocol/sdk": "1.15.0",
+    "@playwright/test": "1.54.1",
+    "@serenity-js/core": "workspace:*",
+    "@serenity-js/mcp": "workspace:*",
+    "@serenity-js/playwright": "workspace:*",
+    "@serenity-js/playwright-test": "workspace:*",
+    "c8": "10.1.3",
+    "tailwindcss": "3.4.17",
+    "typescript": "5.8.3"
+  }
+}
diff --git a/integration/mcp/playwright.config.ts b/integration/mcp/playwright.config.ts
@@ -0,0 +1,18 @@
+import { defineConfig } from '@playwright/test';
+
+import type { TestOptions } from './src/mcp-api.js';
+
+export default defineConfig<TestOptions>({
+    testDir: './spec',
+    fullyParallel: true,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 2 : 0,
+    workers: process.env.CI ? 1 : undefined,
+    reporter: 'list',
+    projects: [
+        // { name: 'msedge', use: { mcpBrowser: 'msedge' } },
+        { name: 'chromium', use: { mcpBrowser: 'chromium' } },
+        { name: 'firefox', use: { mcpBrowser: 'firefox' } },
+        { name: 'webkit', use: { mcpBrowser: 'webkit' } },
+    ],
+});
diff --git a/integration/mcp/spec/list_capabilities.spec.ts b/integration/mcp/spec/list_capabilities.spec.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from '../src/mcp-api.js';
+
+describe('List Capabilities', () => {
+
+    it('lists Serenity/JS capabilities', async ({ client }) => {
+        const response = await client.callTool({
+            name: 'serenity_list_capabilities',
+            arguments: {},
+        });
+
+        expect(response.structuredContent).toEqual({
+            'web': {
+                'activities': {
+                    'navigate': {
+                        'to': 'Navigate.to(url) - Navigate to a specific URL',
+                        'back': 'Navigate.back() - Navigate back in the browser history',
+                        'forward': 'Navigate.forward() - Navigate forward in the browser history',
+                        'reloadPage': 'Navigate.reloadPage() - Reload the current page'
+                    }
+                }
+            }
+        });
+    });
+});
diff --git a/integration/mcp/spec/navigate.spec.ts b/integration/mcp/spec/navigate.spec.ts
@@ -0,0 +1,164 @@
+import { trimmed } from '@serenity-js/core/lib/io/index.js';
+
+import { describe, expect, it } from '../src/mcp-api.js';
+
+describe('Navigate', () => {
+
+    describe('to', () => {
+
+        it('navigates to a url', async ({ client }) => {
+            const response = await client.callTool({
+                name: 'serenity_web_navigate_to',
+                arguments: {
+                    actorName: 'Alice',
+                    url: 'https://serenity-js.org',
+                },
+            });
+
+            expect(response.content[0].text).toEqual(trimmed`
+                | # Serenity/JS Code for serenity_web_navigate_to
+                | \`\`\`ts
+                | await actorCalled('Alice').attemptsTo(
+                |     Navigate.to(https://serenity-js.org),
+                | );
+                | \`\`\`
+                | 
+                | ## Required dependencies
+                | - \`@serenity-js/web\`
+                | 
+                | ## Required imports
+                | \`\`\`ts
+                | import { Navigate } from '@serenity-js/web';
+                | \`\`\`
+                |`
+            );
+
+            expect(response.structuredContent).toEqual({
+                code: trimmed`
+                    | await actorCalled('Alice').attemptsTo(
+                    |     Navigate.to(https://serenity-js.org),
+                    | );`,
+                imports: {
+                    '@serenity-js/web': [ 'Navigate' ],
+                }
+            });
+        });
+    });
+
+    describe('back', () => {
+        it('navigates back in the browser history', async ({ client }) => {
+            const response = await client.callTool({
+                name: 'serenity_web_navigate_back',
+                arguments: {
+                    actorName: 'Alice',
+                },
+            });
+
+            expect(response.content[0].text).toEqual(trimmed`
+                | # Serenity/JS Code for serenity_web_navigate_back
+                | \`\`\`ts
+                | await actorCalled('Alice').attemptsTo(
+                |     Navigate.back(),
+                | );
+                | \`\`\`
+                | 
+                | ## Required dependencies
+                | - \`@serenity-js/web\`
+                | 
+                | ## Required imports
+                | \`\`\`ts
+                | import { Navigate } from '@serenity-js/web';
+                | \`\`\`
+                |`
+            );
+
+            expect(response.structuredContent).toEqual({
+                code: trimmed`
+                    | await actorCalled('Alice').attemptsTo(
+                    |     Navigate.back(),
+                    | );`,
+                imports: {
+                    '@serenity-js/web': [ 'Navigate' ],
+                }
+            });
+        });
+    });
+
+    describe('forward', () => {
+        it('navigates forward in the browser history', async ({ client }) => {
+            const response = await client.callTool({
+                name: 'serenity_web_navigate_forward',
+                arguments: {
+                    actorName: 'Alice',
+                },
+            });
+
+            expect(response.content[0].text).toEqual(trimmed`
+                | # Serenity/JS Code for serenity_web_navigate_forward
+                | \`\`\`ts
+                | await actorCalled('Alice').attemptsTo(
+                |     Navigate.forward(),
+                | );
+                | \`\`\`
+                | 
+                | ## Required dependencies
+                | - \`@serenity-js/web\`
+                | 
+                | ## Required imports
+                | \`\`\`ts
+                | import { Navigate } from '@serenity-js/web';
+                | \`\`\`
+                |`
+            );
+
+            expect(response.structuredContent).toEqual({
+                code: trimmed`
+                    | await actorCalled('Alice').attemptsTo(
+                    |     Navigate.forward(),
+                    | );`,
+                imports: {
+                    '@serenity-js/web': [ 'Navigate' ],
+                }
+            });
+        });
+    });
+
+    describe('reloadPage', () => {
+        it('reloads the current page', async ({ client }) => {
+            const response = await client.callTool({
+                name: 'serenity_web_navigate_reload_page',
+                arguments: {
+                    actorName: 'Alice',
+                },
+            });
+
+            expect(response.content[0].text).toEqual(trimmed`
+                | # Serenity/JS Code for serenity_web_navigate_reload_page
+                | \`\`\`ts
+                | await actorCalled('Alice').attemptsTo(
+                |     Navigate.reloadPage(),
+                | );
+                | \`\`\`
+                | 
+                | ## Required dependencies
+                | - \`@serenity-js/web\`
+                | 
+                | ## Required imports
+                | \`\`\`ts
+                | import { Navigate } from '@serenity-js/web';
+                | \`\`\`
+                |`
+            );
+
+            expect(response.structuredContent).toEqual({
+                code: trimmed`
+                    | await actorCalled('Alice').attemptsTo(
+                    |     Navigate.reloadPage(),
+                    | );`,
+                imports: {
+                    '@serenity-js/web': [ 'Navigate' ],
+                }
+            });
+        });
+    });
+});