Add an Agents.md file for Blazor #64603

javiercn · 2025-12-02T18:41:32Z

This PR adds a comprehensive development guide for the Blazor Components area.

Overview

Adds an Agents.md file to src/Components/ that documents the recommended workflow and best practices for working on issues in the ASP.NET Core Components area.

Key Content

Feature Development Workflow

Emphasizes a sample-first approach: Always create working scenarios in sample projects (BlazorServerApp, BlazorUnitedApp) before writing formal tests
Interactive development and testing using Playwright
Debugging guidance with logging configuration
Only implementing E2E tests after sample validation

Build Optimization

Efficient build strategies to avoid unnecessary full repository builds
Use of sentinel files to track initial build completion
JavaScript asset build verification
Targeted builds with --no-restore and --no-dependencies flags
When and how to run restore operations

E2E Testing Guide

Test structure and organization in src/Components/test
Manual testing with Components.TestServer
Logging configuration for both server-side (.NET) and client-side (Blazor WebAssembly)
Best practices for creating and running E2E tests
Guidance on extending existing tests vs. creating new ones

This guide aims to streamline the development process and reduce the learning curve for contributors working on Blazor Components.

ilonatommy · 2025-12-02T18:46:02Z

src/Components/Agents.md

+
+### Running E2E Tests Manually
+
+1. **Build the repository** first with `.\eng\build.cmd` from the repo root


I like that in "Quick Reference" you said that this build is "first time only". Should we undeline it here as well? I usually prefer a command "first time build the repo from the root, after that build projects that you changed files in". Or similar

ilonatommy

If it works for you, let's merge it and update later.

Copilot

Pull request overview

This PR adds a new Agents.md documentation file to guide developers (or AI agents) through working on issues in the ASP.NET Core Components (Blazor) area. The file provides comprehensive instructions for developing new features, building the project efficiently, and running E2E tests.

Key changes:

Introduces a structured workflow for feature development starting with sample scenarios
Documents optimized build strategies to avoid unnecessary full repository builds
Provides detailed guidance on E2E test structure and execution

src/Components/Agents.md

Copilot · 2025-12-02T18:53:07Z

src/Components/AGENTS.MD

+
+1. **Create a sample scenario first** - This is the most important first step. Update code in one of the projects in `src/Components/Samples` folder to include the scenarios for the feature you want to build. This allows you to develop and test the feature interactively before writing formal tests.
+
+2. **Build and test interactively** - Build the feature and use Playwright to test it in the browser, ensuring it works end-to-end at a basic level.


The document references using "Playwright" to test samples in the browser, but there is no Playwright infrastructure in the Components area. The E2E tests use Selenium (WebDriver). This reference should either be updated to clarify that Playwright is an external tool developers should use independently, or it should be changed to use browser-based manual testing or Selenium-based testing approaches that are actually available in the repository.

Playwright as in the playwright tool

Copilot · 2025-12-02T18:53:07Z

src/Components/AGENTS.MD

+
+3. **Debug when needed**:
+   - If something isn't working as expected, increase the logging level in the sample for `Microsoft.AspNetCore.Components` to `Debug` to see detailed logs.
+   - Check browser console logs using Playwright's `browser_console_messages`.


browser_console_messages is a Playwright-specific API that is not available in the Selenium-based E2E test infrastructure used in this repository. If Playwright is meant to be used as an external tool, this should be clarified. Otherwise, this should reference the appropriate Selenium/WebDriver method for accessing console logs.

Suggested change

- Check browser console logs using Playwright's `browser_console_messages`.

- Check browser console logs using Selenium/WebDriver's browser log access (e.g., `driver.Manage().Logs.GetLog(LogType.Browser)` in C#).

This is the playwright mcp tool

Copilot · 2025-12-02T18:53:08Z

src/Components/AGENTS.MD

+   - Use Microsoft documentation to learn more about troubleshooting Blazor applications.
+   - You can also increase the log level for JavaScript console output.
+
+4. **Validate the sample works** - You must have a validated, working sample in the Samples folder before proceeding. Use Playwright to confirm the feature works end-to-end in the browser.


References using "Playwright to confirm the feature works end-to-end", but Playwright is not part of the Components test infrastructure. The E2E tests use Selenium. This should either clarify that Playwright is an external tool for manual testing, or be updated to reflect the actual Selenium-based test infrastructure.

This is the playwright mcp tool

src/Components/AGENTS.MD

Copilot · 2025-12-02T18:53:08Z

src/Components/AGENTS.MD

+```bash
+.\eng\build.cmd
+echo "We ran eng\build.cmd successfully" > artifacts\agent-sentinel.txt
+```
+


The code block shows mixed Windows and Linux syntax. Line 54 uses .\eng\build.cmd (Windows), but line 55 uses echo "..." with quotes which is Linux/Bash syntax. For Windows CMD, the command should be:

.\eng\build.cmd echo We ran eng\build.cmd successfully > artifacts\agent-sentinel.txt

Or if targeting PowerShell:

.\eng\build.cmd "We ran eng\build.cmd successfully" | Out-File artifacts\agent-sentinel.txt

Consider clarifying which shell this targets or providing separate examples for different platforms.

Suggested change

```bash

.\eng\build.cmd

echo "We ran eng\build.cmd successfully" > artifacts\agent-sentinel.txt

```

```cmd

.\eng\build.cmd

echo We ran eng\build.cmd successfully > artifacts\agent-sentinel.txt

./eng/build.sh echo "We ran eng/build.sh successfully" > artifacts/agent-sentinel.txt

It's powershell

src/Components/Agents.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Add an Agents.md file for Blazor

f61b9ac

Copilot AI review requested due to automatic review settings December 2, 2025 18:41

javiercn requested a review from a team as a code owner December 2, 2025 18:41

github-actions bot added the area-blazor Includes: Blazor, Razor Components label Dec 2, 2025

Copilot started reviewing on behalf of javiercn December 2, 2025 18:42 View session

ilonatommy reviewed Dec 2, 2025

View reviewed changes

ilonatommy approved these changes Dec 2, 2025

View reviewed changes

Copilot finished reviewing on behalf of javiercn December 2, 2025 18:51

Copilot AI reviewed Dec 2, 2025

View reviewed changes

javiercn commented Dec 2, 2025

View reviewed changes

src/Components/Agents.md Outdated Show resolved Hide resolved

javiercn and others added 2 commits December 2, 2025 21:37

Apply suggestions from code review

0de0cb1

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Fix the casing

cdf88f2

javiercn merged commit 1b871a0 into main Dec 3, 2025
9 checks passed

dotnet-policy-service bot added this to the 11.0-preview1 milestone Dec 3, 2025

ilonatommy mentioned this pull request Dec 4, 2025

[Blazor] Add OnRowClick EventCallback to QuickGrid #64602

Merged

dotnet-maestro bot mentioned this pull request Dec 6, 2025

[main] Source code updates from dotnet/aspnetcore dotnet/dotnet#3720

Merged


		### Running E2E Tests Manually

		1. Build the repository first with `.\eng\build.cmd` from the repo root


		1. Create a sample scenario first - This is the most important first step. Update code in one of the projects in `src/Components/Samples` folder to include the scenarios for the feature you want to build. This allows you to develop and test the feature interactively before writing formal tests.

		2. Build and test interactively - Build the feature and use Playwright to test it in the browser, ensuring it works end-to-end at a basic level.

	- Check browser console logs using Playwright's `browser_console_messages`.
	- Check browser console logs using Selenium/WebDriver's browser log access (e.g., `driver.Manage().Logs.GetLog(LogType.Browser)` in C#).

Add an Agents.md file for Blazor #64603

Add an Agents.md file for Blazor #64603

Uh oh!

Conversation

javiercn commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Content

Feature Development Workflow

Build Optimization

E2E Testing Guide

Uh oh!

ilonatommy Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

ilonatommy left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

javiercn Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

javiercn Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

javiercn Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

javiercn Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

javiercn commented Dec 2, 2025 •

edited

Loading