convez.ai
MCP ServerAutomaçãoIntermediário
DataficationSDK

Motus – Automação de Navegador para .NET com MCP

DataficationSDK/Motus

Automação de navegador nativa .NET com arquitetura totalmente extensível

Ver no GitHub
BomPluginScore · de 0 a 100

Framework extensível de automação e testes de navegador para .NET que comunica diretamente com Chromium e Firefox via WebSocket, sem dependência Node.js. Inclui geração de código, analisadores Roslyn, gravador de testes, executor visual Blazor e servidor MCP para agentes IA, todo construído sobre interfaces de plugin públicas.

Instalação

$npx convez-ai DataficationSDK/Motus

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
16
Forks
3
Acompanhando
0
Saúde
37%
Último commit
há 3 semanas
Versão
motus-v1.1.0
Issues abertas
4
Contribuidores
1

Casos de uso

  • Testes automatizados de aplicações web em .NET
  • Geração automática de page objects a partir de páginas vivas
  • Gravação e playback de sessões de teste
  • Automação de workflows com agentes IA via MCP
  • Validação de DOM e comportamento de UI em pipelines CI/CD

Veredito

Motus é uma solução madura e bem arquitetada para automação de navegador em .NET, diferenciando-se pela comunicação direta com protocolos de browser (CDP/BiDi), geração de código fonte e filosofia de extensibilidade coerente. O servidor MCP o torna viável para orquestração por agentes IA, embora exija familiaridade com .NET e conhecimento de padrões de teste.

README

A tradução para o português deste README ainda está na fila.

Motus

Extensible browser automation and testing framework for .NET, built on a fully extensible architecture.

License: MIT .NET 8 | 10 NuGet

The Story

Every .NET browser automation framework either wraps a JavaScript tool behind a process boundary or bolts extensibility on as an afterthought. Playwright for .NET proxies commands through a Node.js sidecar. Selenium's extension model grew organically over fifteen years and it shows.

Motus started from a premise proven by the architecture of Verso: if the framework's own features are built on the same public plugin interfaces available to third-party authors, the architecture stays honest. Every built-in selector strategy, lifecycle hook, wait condition, and reporter is registered through the same IPluginContext that any consumer can use. There are no internal shortcuts.

The result is a framework that talks directly to Chromium and Firefox over WebSocket (CDP and WebDriver BiDi), ships source-generated protocol bindings for NativeAOT, and gives you compile-time diagnostics for common automation mistakes before your tests ever run.

Getting Started

Prerequisites

  • .NET 8 SDK or .NET 10 SDK
  • Chrome, Edge, or Firefox installed (or use motus install to download a browser binary)

Install

dotnet add package Motus
dotnet add package Motus.Testing.MSTest # or Motus.Testing.xUnit / Motus.Testing.NUnit
dotnet tool install --global Motus.Cli

Write Your First Test

using Motus;
using Motus.Abstractions;
using Motus.Testing.MSTest;
using static Motus.Assertions.Expect;

[TestClass]
public class SearchTests : MotusTestBase
{
    [TestMethod]
    public async Task SearchReturnsResults()
    {
        var page = await Context.NewPageAsync();
        await page.GotoAsync("https://example.com");

        await page.Locator("input[name='q']").FillAsync("motus automation");
        await page.Locator("button[type='submit']").ClickAsync();

        await That(page).ToHaveUrlAsync("**/search**");
        await That(page.Locator(".results")).ToBeVisibleAsync();
    }
}

Generate Page Objects from Live Pages

motus codegen https://example.com/login --output ./Pages --namespace MyApp.Pages

# Or open a browser, navigate yourself, then press Enter to analyze
motus codegen --headed --output ./Pages

This navigates to the URL, crawls the DOM for interactive elements, infers the best selector for each using pluggable strategies, and emits a typed .g.cs Page Object Model class. Use --detect-listeners to also discover elements with directly-attached JS event handlers (vanilla JS, jQuery, etc.).

Record a Test Session

motus record --output ./Tests/LoginTest.cs --framework mstest --selector-priority testid,role,text,css

Run Tests

motus run ./bin/Debug/net8.0/MyTests.dll --workers auto --reporter console
motus run ./bin/Debug/net8.0/MyTests.dll --visual
motus run ./bin/Debug/net8.0/MyTests.dll --reporter html:./reports/result.html
motus run ./bin/Debug/net8.0/MyTests.dll --reporter junit:./reports/junit.xml

Accessibility Testing

Motus audits pages against WCAG 2.1 Level A/AA rules using the browser's native accessibility tree (no JavaScript injection). Enable the built-in audit hook to run checks automatically after every navigation, or use assertions for targeted validation.

// Assert the page passes all accessibility rules
await Expect.That(page).ToPassAccessibilityAuditAsync();

// Skip specific rules or exclude warnings
await Expect.That(page).ToPassAccessibilityAuditAsync(opts =>
{
    opts.SkipRules("a11y-color-contrast");
    opts.IncludeWarnings = false;
});

// Assert accessible name and role on individual elements
await Expect.That(page.Locator("button#submit")).ToHaveAccessibleNameAsync("Submit order");
await Expect.That(page.Locator("nav")).ToHaveRoleAsync("navigation");

Enable the audit lifecycle hook via config or CLI to run audits automatically:

# Report violations without failing tests
motus run ./bin/Debug/net8.0/MyTests.dll --a11y warn

# Fail tests on error-severity violations
motus run ./bin/Debug/net8.0/MyTests.dll --a11y enforce

Or in motus.config.json:

{
  "accessibility": {
    "enable": true,
    "mode": "enforce",
    "skipRules": ["a11y-color-contrast"]
  }
}

Performance Testing

Motus collects Core Web Vitals (LCP, FCP, TTFB, CLS, INP) and supplementary metrics (JS heap size, DOM node count) directly from the browser during test execution. Set budget thresholds via attributes or config, and performance regressions fail your tests automatically.

// Assert all metrics are within the class-level budget
[PerformanceBudget(Lcp = 2500, Fcp = 1800, Cls = 0.1)]
[TestClass]
public class DashboardTests : MotusTestBase
{
    [TestMethod]
    public async Task DashboardLoadsWithinBudget()
    {
        await Page.GotoAsync("https://app.example.com/dashboard");
        await Expect.That(Page).ToMeetPerformanceBudgetAsync();
    }
}

// Or assert individual metrics
await Expect.That(page).ToHaveLcpBelowAsync(2500);
await Expect.That(page).ToHaveClsBelowAsync(0.1);

Enable budget enforcement from the CLI:

motus run ./bin/Debug/net8.0/MyTests.dll --perf-budget

Or in motus.config.json:

{
  "performance": {
    "enable": true,
    "lcp": 2500,
    "cls": 0.1,
    "inp": 200
  }
}

Code Coverage

Motus collects JavaScript coverage via the CDP Profiler/Debugger domains and CSS rule-usage coverage via the CDP CSS domain on every page driven by your tests. Coverage is collected per-test and aggregated across the run, with optional thresholds that fail the run when not met.

Enable coverage from the CLI with one or more output formats:

# Console summary table
motus run ./bin/Debug/net8.0/MyTests.dll --coverage console

# Static HTML report (index + per-file source views with line highlighting)
motus run ./bin/Debug/net8.0/MyTests.dll --coverage html:./coverage

# Cobertura XML for CI ingestion
motus run ./bin/Debug/net8.0/MyTests.dll --coverage cobertura:./coverage.xml

# Repeat the flag for multiple formats at once
motus run ./bin/Debug/net8.0/MyTests.dll --coverage console --coverage html:./coverage

Source-mapped JS bundles are remapped back to original sources automatically when sourcemaps are reachable. Configure thresholds and defaults in motus.config.json:

{
  "coverage": {
    "enable": true,
    "includeJavaScript": true,
    "includeCss": true,
    "js": { "lines": 70, "functions": 60 },
    "css": { "rules": 50 }
  }
}

When a threshold is set and the aggregated run coverage falls below it, the run exits non-zero so CI fails the build.

Retrying Flaky Runs

CDP WebSocket connections are occasionally dropped by the browser under heavy tracing or when sibling targets close mid-command. Use --retries N to re-run a failing test up to N additional times, but only when the failure is a transient CDP disconnect. Non-transient failures (assertion errors, timeouts) are not retried, so real bugs aren't masked.

motus run ./bin/Debug/net8.0/MyTests.dll --retries 2

Each retry runs the entire test fresh: new browser context, new WebSocket, new test instance. A [RETRY] line is logged to stderr for every attempt so flake patterns are visible.

MCP Server for AI Agents

Motus exposes its browser engine to AI agents through a Model Context Protocol server, shipped as the motus mcp verb on the CLI tool. Agents navigate, snapshot the accessibility tree, click and type against referenced elements, act at raw coordinates on canvas surfaces (including drag and drop), intercept network traffic, run accessibility and performance audits, record traces, HARs, and videos, and generate Page Object Model code, all over stdio or Streamable HTTP.

Register it with Claude Code against the installed tool:

dotnet tool install --global Motus.Cli
motus install
claude mcp add motus -- motus mcp

See MCP Server for the full registration story, the tool catalog, and the HTTP transport.

How It Works

Motus communicates directly with the browser over WebSocket. For Chromium-based browsers, it speaks the Chrome DevTools Protocol (CDP). For Firefox, it uses WebDriver BiDi. There is no Node.js sidecar, no driver binary, and no process boundary between your test code and the protocol layer.

All CDP types are source-generated at build time from the protocol JSON schema. Serialization uses System.Text.Json source generators for zero-reflection, NativeAOT-compatible marshalling.

Architecture

ProjectRole
Motus.AbstractionsPublic interfaces and types (zero dependencies)
MotusCore engine: transport, browser management, page controller, locators, selectors, assertions
Motus.CodegenRoslyn source generator for CDP protocol types and plugin discovery
Motus.AnalyzersRoslyn diagnostic analyzers and code fixes
Motus.RecorderAction capture, selector inference, POM generation
Motus.RunnerBlazor visual test runner with live screencast and timeline
Motus.Climotus CLI tool
Motus.Testing.*Test framework integrations (MSTest, xUnit, NUnit)

The Extension Model

Five interfaces define every point of extensibility, all registered through IPluginContext:

InterfaceWhat It Does
ISelectorStrategyResolve elements and generate selectors for a custom prefix (e.g. data-testid=)
ILifecycleHookIntercept navigation, actions, page create/close, console messages, and errors
IWaitConditionDefine named wait conditions for use with WaitForAsync
IReporterReceive test run events for custom reporting (multiple reporters run simultaneously)
IAccessibilityRuleDefine custom WCAG accessibility rules evaluated against the browser's accessibility tree
IAccessibilityReporterOpt-in interface for reporters to receive per-violation accessibility events
IPerformanceReporterOpt-in interface for reporters to receive performance metrics and budget results
ICoverageReporterOpt-in interface for reporters to receive per-test and aggregated JS/CSS coverage data
IMotusLoggerStructured logging for plugin diagnostics

Plugin Discovery

Plugins are discovered two ways:

  1. Compile-time auto-discovery: Mark a class with [MotusPlugin] and the Roslyn source generator emits a [ModuleInitializer] that registers it at startup. No reflection.
  2. Manual registration: Pass instances via LaunchOptions.Plugins for full control.
[MotusPlugin]
public class MyPlugin : IPlugin
{
    public string PluginId => "my-plugin";
    public string Name => "My Plugin";
    public string Version => "1.0.0";

    public Task OnLoadedAsync(IPluginContext context)
    {
        context.RegisterSelectorStrategy(new MyCustomStrategy());
        context.RegisterLifecycleHook(new MyHook());
        return Task.CompletedTask;
    }

    public Task OnUnloadedAsync() => Task.CompletedTask;
}

Dogfooding All the Way Down

The five built-in selector strategies (CSS, XPath, Text, Role, TestId) are registered through IPluginContext. The console, HTML, JUnit, and TRX reporters implement IReporter. The visual runner's timeline is powered by an ILifecycleHook. The nine built-in WCAG rules and the accessibility audit hook are registered as plugins through the same IPluginContext. None of them have special access to engine internals.

Roslyn Analyzers

The Motus.Analyzers package ships seven diagnostics that catch common automation mistakes at compile time:

RuleSeverityWhat It Catches
MOT001WarningNon-awaited automation call
MOT002InfoHardcoded Task.Delay or Thread.Sleep in test code
MOT003InfoFragile selector (deep nesting, nth-child chains, auto-generated class names)
MOT004WarningIBrowser or IBrowserContext not disposed
MOT005WarningLocator created but never used
MOT006InfoDeprecated selector prefix
MOT007WarningAssertion after navigation without intervening wait

Code fixes are provided for MOT001, MOT002, and MOT004.

Visual Runner

Launch the Blazor-based visual runner with motus run --visual:

  • Live browser view with real-time screencast via CDP Page.startScreencast
  • Action timeline with clickable steps, before/after screenshots, network requests, and console messages
  • Step-through debugging with pause, inspect, and resume controls
  • Visual regression with pixel-level diff, side-by-side comparison, and baseline management

Key Features

CategoryDetails
Browser SupportChromium (CDP), Firefox (WebDriver BiDi)
SelectorsCSS, XPath, Text, ARIA Role, Test ID, plus custom strategies via ISelectorStrategy
Auto-WaitActionability checks (visible, enabled, stable, receives events) with configurable timeout
Shadow DOMAutomatic piercing of open shadow roots (configurable per-locator)
AssertionsAuto-retry polling assertions for locators, pages, and responses with .Not negation
NetworkRequest interception, response mocking, route matching with glob patterns
RecordingCapture browser interactions and emit idiomatic C# test code (MSTest, xUnit, NUnit)
CodegenGenerate Page Object Model classes from live pages with selector inference
AccessibilityBuilt-in WCAG 2.1 Level A/AA audits via CDP accessibility tree, lifecycle hook, page and locator assertions, custom rules via IAccessibilityRule
PerformanceCore Web Vitals collection (LCP, FCP, TTFB, CLS, INP), configurable budgets via [PerformanceBudget] attribute or config, auto-retry assertions, reporter integration via IPerformanceReporter
CoveragePer-test JS coverage via CDP Profiler/Debugger, CSS rule-usage coverage via CDP CSS, source-map remapping to original sources, console / HTML / Cobertura reporters, configurable thresholds that fail the run, custom reporters via ICoverageReporter
ReportersConsole, HTML, JUnit XML, TRX, plus custom reporters via IReporter (with opt-in IAccessibilityReporter, IPerformanceReporter, ICoverageReporter for domain events)
TracingScreenshots, DOM snapshots, network logs, HAR export, and WebM video recording
ParallelContext-level, browser-level, and worker-level parallel execution
ConfigurationLayered: motus.config.json, environment variables, code (code always wins)
NativeAOTSource-generated serialization and plugin discovery with zero reflection

CLI Reference

motus run <assemblies>  Run tests with optional --visual, --filter, --workers, --reporter, --a11y, --perf-budget, --coverage, --retries
motus record           Record a browser session and emit test code
motus codegen          Generate POM classes from live pages (--headed, --connect, --detect-listeners)
motus screenshot       Capture a screenshot (--full-page, --delay, --hide-banners, --width, --height)
motus pdf              Generate a PDF from a URL (--delay, --hide-banners, --width, --timeout)
motus trace show       Open a trace file in the visual runner with timeline, screenshots, and network
motus install          Download and install browser binaries
motus update-protocol  Fetch and update CDP protocol schema files
motus mcp              Run the MCP server for AI agents (stdio by default, or --http)

Build from Source

git clone https://github.com/DataficationSDK/Motus
cd Motus
dotnet build Motus.sln
dotnet test Motus.sln

Contributing

Contributions are welcome. Open an issue to discuss what you'd like to work on.

Sponsors

Thanks to @fluentfoundation and @fiVISION for supporting this project.

License

MIT

Motus is a Datafication project.

Ver o original no GitHub

Bom para

Relacionados