NScreenplay.Playwright 0.2.0

NScreenplay

An AI-native Screenplay Test Automation Framework for .NET.

NScreenplay organizes automation around this flow:

Actor → Ability → Task → Interaction → Question → Consequence

What It Solves

• Keeps tests in business language instead of low-level UI scripts
• Centralizes selectors and endpoint metadata in Targets
• Preserves existing test frameworks while adopting Screenplay abstractions
• Exposes deterministic MCP tools for AI-assisted discovery, planning, and safe adoption

Packages

• NScreenplay.Core: Screenplay abstractions (Actor, IAbility, ITask, IInteraction, IQuestion<T>, IConsequence, Target)
• NScreenplay.Playwright: Playwright integration (BrowseTheWeb, Interactions, Questions)
• NScreenplay.Reqnroll: Reqnroll integration (ScenarioActor, hooks, browser lifecycle)
• NScreenplay.Mcp: MCP server (tooling layer, not a NuGet package)

Install

dotnet add package NScreenplay.Core --version 0.2.0

If the project uses Playwright:

dotnet add package NScreenplay.Playwright --version 0.2.0

If the project uses Reqnroll:

dotnet add package NScreenplay.Reqnroll --version 0.2.0

Quick Start (xUnit + Playwright)

using Microsoft.Playwright;
using NScreenplay.Core;
using NScreenplay.Playwright;

static class LoginPage
{
    public static Target Username = Target.The("username field").ByTestId("username-input");
    public static Target Password = Target.The("password field").ByTestId("password-input");
    public static Target LoginButton = Target.The("login button").ByTestId("login-button");
}

await using IPlaywright playwright = await Playwright.CreateAsync();
await using var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions { Headless = true });
await using var page = await browser.NewPageAsync();

var actor = Actor.Named("Alice");
actor.Can(BrowseTheWeb.Using(page));

await actor.AttemptsTo(Navigate.To("https://example.com/login"));
await actor.AttemptsTo(Enter.TheValue("alice@example.com").Into(LoginPage.Username));
await actor.AttemptsTo(Enter.TheValue("secret123").Into(LoginPage.Password));
await actor.AttemptsTo(Click.On(LoginPage.LoginButton));

Reqnroll Integration

Reqnroll is preserved. NScreenplay does not replace it.

Use ScenarioActor in step definitions and keep steps thin:

public LoginSteps(ScenarioActor scenario) => _scenario = scenario;

See docs/reqnroll.md and samples/Login.

AI Adoption Workflow (MCP)

Canonical playbook: docs/external-agent-adoption.md

Canonical flow:

Analyze → Plan → Human Approval → Apply → Validate

Required MCP tools:

1. nscreenplay_analyze_project
2. nscreenplay_create_adoption_plan
3. nscreenplay_apply_adoption_plan (only after explicit approval)

Safety boundaries:

• no shell/PowerShell/arbitrary script execution
• apply executes only explicit validated plan actions
• workspace-root and path safety checks are enforced

Skills

This repository includes 7 reusable AI Agent Skills designed to guide AI agents (Claude, GitHub Copilot, Cursor, Cline, etc.) in working effectively with the NScreenplay framework.

Each skill is a standalone markdown file with YAML frontmatter for discovery via skills.sh:

Available Skills

Skill Format

Each skill file includes YAML frontmatter:

---
name: <skill-name>
description: <brief description of when to use this skill>
---

# Skill Content (Markdown)
...

The frontmatter enables discovery by AI agents and skills.sh.

Using Skills

Skills are installed and discovered via skills.sh:

npx skills add hadijahangiri/NScreenPlay

This registers all 7 skills with your AI agent. Once installed, agents can:

• List available skills: See all NScreenplay skills in your tool ecosystem
• Load skills on demand: Inject skill content when relevant to the current task
• Follow skill guidance: Use skill workflows to maintain Screenplay architecture and best practices

Skills are also discoverable via the NScreenplay MCP server (nscreenplay_list_skills, nscreenplay_get_skill).

Architecture

graph TD
    R[Reqnroll] --> NR[NScreenplay.Reqnroll]
    NR --> C[NScreenplay.Core]
    P[NScreenplay.Playwright] --> C
    M[NScreenplay.Mcp] --> C

Documentation

• Getting started
• Screenplay pattern
• Playwright integration
• Reqnroll integration
• Reqnroll smoke harness
• Project analysis and adoption flow
• External-agent adoption playbook
• MCP
• AI
• Skills
• Healing
• Architecture

Project Structure

• src/NScreenplay.Core
• src/NScreenplay.Playwright
• src/NScreenplay.Reqnroll
• src/NScreenplay.Mcp
• tests/NScreenplay.Core.Tests
• tests/NScreenplay.Playwright.Tests
• tests/NScreenplay.Reqnroll.Tests
• tests/NScreenplay.Mcp.Tests
• samples/Login
• skills
• docs

License

MIT License