Jul 11, 2025 · Jul 11, 2025 · Jul 11, 2025 · Jul 11, 2025 · Jul 11, 2025 · Jul 11, 2025
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
    strategy:
      matrix:
        module:
          - mcp
          - playwright-test
          - playwright-test-ct
          - playwright-web
diff --git a/examples/webdriverio-cucumber/todo.md b/examples/webdriverio-cucumber/todo.md
diff --git a/integration/jasmine/spec/screenplay.spec.ts b/integration/jasmine/spec/screenplay.spec.ts
                }));

        it('fails when discarding an ability results in Error', () =>
            jasmine('examples/screenplay/ability-discard-error.spec.js')
            jasmine('examples/screenplay/ability-close-error.spec.js')
                .then(ifExitCodeIsOtherThan(3, logOutput))
                .then(result => {
                    expect(result.exitCode).to.equal(3);
                }));

        it(`fails when discarding an ability doesn't complete within a timeout`, () =>
            jasmine('examples/screenplay/ability-discard-timeout.spec.js')
            jasmine('examples/screenplay/ability-close-timeout.spec.js')
                .then(ifExitCodeIsOtherThan(3, logOutput))
                .then(result => {
                    expect(result.exitCode).to.equal(3);
                }));

        it(`executes all the scenarios in the test suite even when some of them fail because of an error when discarding an ability`, () =>
            jasmine('examples/screenplay/ability-discard-error-should-not-affect-stage-cue.spec.js')
            jasmine('examples/screenplay/ability-close-error-should-not-affect-stage-cue.spec.js')
                .then(ifExitCodeIsOtherThan(3, logOutput))
                .then(result => {
                    expect(result.exitCode).to.equal(3);
                        .next(SceneFinished,       event => {
                            expect(event.outcome).to.be.instanceOf(ExecutionSuccessful);
                        })
                        .next(SceneStarts,         event => expect(event.details.name).to.equal(new Name('A screenplay scenario fails if the ability fails todiscard again')))
                        .next(SceneStarts,         event => expect(event.details.name).to.equal(new Name('A screenplay scenario fails if the ability fails toclose again')))
                        .next(SceneFinished,       event => {
                            const outcome: ProblemIndication = event.outcome as ProblemIndication;

diff --git a/integration/mcp/.gitignore b/integration/mcp/.gitignore
 # Node
 node_modules
 *.log

 # Build artifacts
 lib
 playwright-report
 test-results
 output
diff --git a/integration/mcp/examples/empty/package.json b/integration/mcp/examples/empty/package.json
 {
  "name": "@integration/mcp-examples-empty",
  "private": true,
  "config": {
    "access": "private"
  }
 }
diff --git a/integration/mcp/examples/package-json-empty-scripts/package.json b/integration/mcp/examples/package-json-empty-scripts/package.json
 {
  "name": "example-package-json-empty-scripts",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {},
  "description": ""
 }
diff --git a/integration/mcp/examples/package-json-no-scripts/package.json b/integration/mcp/examples/package-json-no-scripts/package.json
 {
  "name": "example-package-json-no-scripts",
  "version": "1.0.0",
  "main": "index.js",
  "description": ""
 }
diff --git a/integration/mcp/examples/playwright-test-default-config/playwright.config.ts b/integration/mcp/examples/playwright-test-default-config/playwright.config.ts
 import { defineConfig, devices } from '@playwright/test';
 /**
 * See https://playwright.dev/docs/test-configuration.
 */
 export default defineConfig({
    testDir: './tests',
    /* Run tests in files in parallel */
    fullyParallel: true,
    /* Fail the build on CI if you accidentally left test.only in the source code. */
    forbidOnly: !!process.env.CI,
    /* Retry on CI only */
    retries: process.env.CI ? 2 : 0,
    /* Opt out of parallel tests on CI. */
    workers: process.env.CI ? 1 : undefined,
    /* Reporter to use. See https://playwright.dev/docs/test-reporters */
    reporter: 'html',
    /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
    use: {
        // baseURL: 'http://localhost:3000',
    },
    /* Configure projects for major browsers */
    projects: [
        { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    ],
 });
diff --git a/integration/mcp/examples/playwright-test/package.json b/integration/mcp/examples/playwright-test/package.json
 {
  "name": "@integration/mcp-examples-playwright-test",
  "private": true,
  "config": {
    "access": "private"
  },
  "devDependencies": {
    "@playwright/test": "^1.55.1",
    "@types/node": "^24.3.0"
  }
 }
diff --git a/integration/mcp/package.json b/integration/mcp/package.json
 {
  "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.16.8",
    "@modelcontextprotocol/sdk": "1.18.2",
    "@playwright/test": "1.55.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
 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/assertions/expectations.spec.ts b/integration/mcp/spec/assertions/expectations.spec.ts
 import { describe, expect, it } from '../../src/mcp-api.js';

 describe('expectations', () => {

    it('produces an expectation to include a substring', async ({ client, testServerUrl }) => {
        const response = await client.callTool({
            name: 'serenity_assertions_includes',
            arguments: {
                actorName: 'Alice',
                expected: {
                    imports: { '@serenity-js/web': [ 'Text', 'PageElement', 'By' ] },
                    question: `Text.of(PageElement.located(By.css('h1')).describedAs('header'))`,
                },
            },
        });

        expect(response.structuredContent).toEqual({
            result: {
                question: {
                    imports: {
                        '@serenity-js/assertions': [ 'includes' ],
                        '@serenity-js/web': [ 'By', 'PageElement', 'Text' ]
                    },
                    template: "includes(Text.of(PageElement.located(By.css('h1')).describedAs('header')))"
                },
            }
        });
    });
 });
diff --git a/integration/mcp/spec/list_capabilities.spec.ts b/integration/mcp/spec/list_capabilities.spec.ts
 import { describe, expect, it } from '../src/mcp-api.js';

 describe('List Capabilities', () => {

    it('lists Serenity/JS test automation capabilities', async ({ client }) => {
        const response = await client.callTool({
            name: 'serenity_list_capabilities',
            arguments: {},
        });

        expect(response.structuredContent).toEqual({
            project: {
                analyze_runtime_environment: `Analyze a Node.js project in the specified root directory to determine compatibility with Serenity/JS. Detect available command line tools. Check for any runtime issues, explains their causes, and provides recommended fixes.`,
                analyze_dependencies: `List the Node.js packages used by the project in the specified root directory to determine compatibility with Serenity/JS. Check for compatibility issues and recommend any missing packages that should be installed.`,
                configure_playwright_test: 'Configure Playwright Test for use with Serenity/JS',
                configure_package_json_scripts: 'Configure NPM scripts in package.json to include commands for running tests with Serenity/JS',
                create_example_test_file: 'Create an example test file demonstrating writing Serenity/JS test scenarios',
                run_test: 'Discover the commands to run Serenity/JS test scenarios',
            },
            inspection: {
                page_element_resolver: 'Define a selector identifying a page element based on its reference from the accessibility snapshot',
                snapshot: 'Capture an accessibility snapshot of the website to detect the elements of interest',
            },
            test_automation: {
                assertions: {
                    activities: {
                        ensure: {
                            that: 'Ensure.that($actual, $expectation) - Verify if the resolved value of the provided question meets the specified expectation',
                        },
                    },
                    questions: {
                        equals: 'equals($expected) - Check if the actual value of type T equals the expected value of the same type T',
                        includes: 'includes($expected) - Check if the actual string value includes the expected substring',
                    },
                },
                web: {
                    activities: {
                        click: {
                            on: 'Click.on($pageElement) - Click on a page element',
                        },
                        navigate: {
                            to: 'Navigate.to($url) - Navigate to a specific URL in the browser',
                            back: 'Navigate.back() - Navigate back in the browser history',
                            forward: 'Navigate.forward() - Navigate forward in the browser history',
                            reload_page: 'Navigate.reloadPage() - Reload the current page in the browser',
                        }
                    },
                    questions: {
                        page: {
                            current: {
                                name: 'Page.current().name() - A question that retrieves the name of the current page in the browser',
                                title: 'Page.current().title() - A question that retrieves the title of the current page in the browser',
                                url: {
                                    href: 'Page.current().url().href - A question that retrieves the URL of the current page in the browser.',
                                },
                            }
                        }
                    }
                }
            }
        });
    });
 });
diff --git a/integration/mcp/spec/project_analyze_runtime.spec.ts b/integration/mcp/spec/project_analyze_runtime.spec.ts
 import path from 'node:path';

 import { describe, expect, it } from '../src/mcp-api.js';

 const __dirname = path.dirname(new URL(import.meta.url).pathname);

 describe('Project Analyze Runtime', () => {

    it('instructs the user to install a test runner first if none is found', async ({ client }) => {
        const rootDirectory = path.resolve(__dirname, '../examples/empty');
        const response = await client.callTool({
            name: 'serenity_project_analyze_runtime_environment',
            arguments: {
                rootDirectory,
            },
        });

        expect(response.isError).not.toBe(true);
    });

    it('analyzes the runtime of a node.js project to determine compatibility with Serenity/JS', async ({ client }) => {
        const response = await client.callTool({
            name: 'serenity_project_analyze_runtime_environment',
            arguments: {
                rootDirectory: path.resolve(__dirname, '../examples/playwright-test'),
            },
        });

        expect(response.isError).not.toBe(true);

        // expect(response.structuredContent['missingDependencies']).toEqual([
        //     `@serenity-js/assertions`,
        //     `@serenity-js/console-reporter`,
        //     `@serenity-js/core`,
        //     `@serenity-js/playwright`,
        //     `@serenity-js/playwright-test`,
        //     `@serenity-js/rest`,
        //     `@serenity-js/serenity-bdd`,
        //     `@serenity-js/web`,
        //     `npm-failsafe`,
        // ]);

        // expect(response.content[0].text).toEqual(`
        // `);
    });
 });
Original file line number	Diff line number	Diff line change
Expand Up		@@ -147,6 +147,7 @@ jobs:
		strategy:
		matrix:
		module:
		- mcp
		- playwright-test
		- playwright-test-ct
		- playwright-web
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -51,7 +51,7 @@ describe('@serenity-js/Jasmine', function () {
		}));

		it('fails when discarding an ability results in Error', () =>
		jasmine('examples/screenplay/ability-discard-error.spec.js')
		jasmine('examples/screenplay/ability-close-error.spec.js')
		.then(ifExitCodeIsOtherThan(3, logOutput))
		.then(result => {
		expect(result.exitCode).to.equal(3);
Expand All		@@ -77,7 +77,7 @@ describe('@serenity-js/Jasmine', function () {
		}));

		it(`fails when discarding an ability doesn't complete within a timeout`, () =>
		jasmine('examples/screenplay/ability-discard-timeout.spec.js')
		jasmine('examples/screenplay/ability-close-timeout.spec.js')
		.then(ifExitCodeIsOtherThan(3, logOutput))
		.then(result => {
		expect(result.exitCode).to.equal(3);
Expand All		@@ -103,7 +103,7 @@ describe('@serenity-js/Jasmine', function () {
		}));

		it(`executes all the scenarios in the test suite even when some of them fail because of an error when discarding an ability`, () =>
		jasmine('examples/screenplay/ability-discard-error-should-not-affect-stage-cue.spec.js')
		jasmine('examples/screenplay/ability-close-error-should-not-affect-stage-cue.spec.js')
		.then(ifExitCodeIsOtherThan(3, logOutput))
		.then(result => {
		expect(result.exitCode).to.equal(3);
Expand All		@@ -125,7 +125,7 @@ describe('@serenity-js/Jasmine', function () {
		.next(SceneFinished, event => {
		expect(event.outcome).to.be.instanceOf(ExecutionSuccessful);
		})
		.next(SceneStarts, event => expect(event.details.name).to.equal(new Name('A screenplay scenario fails if the ability fails todiscard again')))
		.next(SceneStarts, event => expect(event.details.name).to.equal(new Name('A screenplay scenario fails if the ability fails toclose again')))
		.next(SceneFinished, event => {
		const outcome: ProblemIndication = event.outcome as ProblemIndication;

Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,9 @@
		# Node
		node_modules
		*.log

		# Build artifacts
		lib
		playwright-report
		test-results
		output
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,7 @@
		{
		"name": "@integration/mcp-examples-empty",
		"private": true,
		"config": {
		"access": "private"
		}
		}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,7 @@
		{
		"name": "example-package-json-empty-scripts",
		"version": "1.0.0",
		"main": "index.js",
		"scripts": {},
		"description": ""
		}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,6 @@
		{
		"name": "example-package-json-no-scripts",
		"version": "1.0.0",
		"main": "index.js",
		"description": ""
		}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,25 @@
		import { defineConfig, devices } from '@playwright/test';
		/**
		* See https://playwright.dev/docs/test-configuration.
		*/
		export default defineConfig({
		testDir: './tests',
		/* Run tests in files in parallel */
		fullyParallel: true,
		/* Fail the build on CI if you accidentally left test.only in the source code. */
		forbidOnly: !!process.env.CI,
		/* Retry on CI only */
		retries: process.env.CI ? 2 : 0,
		/* Opt out of parallel tests on CI. */
		workers: process.env.CI ? 1 : undefined,
		/* Reporter to use. See https://playwright.dev/docs/test-reporters */
		reporter: 'html',
		/* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
		use: {
		// baseURL: 'http://localhost:3000',
		},
		/* Configure projects for major browsers */
		projects: [
		{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
		],
		});
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,11 @@
		{
		"name": "@integration/mcp-examples-playwright-test",
		"private": true,
		"config": {
		"access": "private"
		},
		"devDependencies": {
		"@playwright/test": "^1.55.1",
		"@types/node": "^24.3.0"
		}
		}
Original file line number	Diff line number	Diff line change
		@@ -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.16.8",
		"@modelcontextprotocol/sdk": "1.18.2",
		"@playwright/test": "1.55.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"
		}
		}
Original file line number	Diff line number	Diff line change
		@@ -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' } },
		],
		});