AGENTS.md

1# Working on Issues in the Components Area
2 
3This guide provides step-by-step instructions for working on issues in the ASP.NET Core Components area.
4 
5## Working on issues
6 
7You MUST follow this workflow when implementing new features or fixing bugs in the Components area.
8* Add the workflow to your `todos` and follow it strictly.
9- Create a sample scenario.
10- If working on a bug, use playwright to reproduce the behavior/problem first.
11- You MUST have reproduced the problem before attempting to fix it.
12- Research the problem area using the microsoft docs, existing code, git history, and logging on the sample project.
13- Implement the fix or feature in the sample project first.
14- Test the fix or feature interactively using Playwright.
15- Once the fix or feature is validated in the sample, implement E2E tests for it.
16  - When you create an E2E test. First execute it interactively with Playwright.
17  - If an E2E test is failing, debug it by running the test server manually and navigating to the scenario in a browser.
18- Only after the E2E tests are passing, remove the sample code you added in the Samples projects.
19  - Use `git checkout` and `git clean -fd` to remove the sample code.
20 
21### Overview
22 
23The workflow for implementing new features in the Components area follows these steps:
24 
251. **Create a sample scenario first** - This is the most important first step. Update code in one of the projects in the `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.
26 
272. **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.
28 
29### Sample Projects
30 
31The `src/Components/Samples` folder contains canonical Blazor Web App samples, and `src/Components/WebAssembly/Samples` contains a standalone WebAssembly sample, that you can use for developing and testing features. All are generated from the `dotnet new blazor`/`blazorwasm` templates with `Auto` interactivity and adapted to reference the in-tree framework:
32 
33- **BlazorWebAppGlobal** (+ **.Client**) - A Blazor Web App with **global** interactivity (`@rendermode="InteractiveAuto"` on `Routes`/`HeadOutlet` in `App.razor`). Change that one value to `InteractiveServer`/`InteractiveWebAssembly` to test the whole app on a single platform.
34- **BlazorWebAppPerPage** (+ **.Client**) - A Blazor Web App with **per-page** interactivity. Apply `@rendermode` per page/component (`InteractiveServer`/`InteractiveWebAssembly`/`InteractiveAuto`), mix modes, or omit it for static SSR.
35- **BlazorWebAssemblyStandalone** - A standalone Blazor WebAssembly app (no server host), under `src/Components/WebAssembly/Samples`.
36 
37Together these cover every interactivity platform (Server/WebAssembly/Auto/None) and location (Global/Per-page) by editing a single `@rendermode` rather than restructuring.
38 
39**Always start by adding your feature scenario to whichever sample matches the render mode you need.** This allows you to:
40- Quickly iterate on the implementation
41- Test the feature interactively in a real browser
42- Verify the feature works before writing formal E2E tests
43- Debug issues more easily with full logging capabilities
44 
453. **Debug when needed**:
46   - If something isn't working as expected, increase the logging level in the sample for `Microsoft.AspNetCore.Components` to `Debug` to see detailed logs.
47   - Check browser console logs using Playwright's `browser_console_messages`.
48   - Use Microsoft documentation to learn more about troubleshooting Blazor applications.
49   - You can also increase the log level for JavaScript console output.
50 
514. **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.
52 
535. **Implement E2E tests** - Only after the sample is validated, implement E2E tests for it.
54 
556. **Clean up sample code** - After your E2E tests are passing, remove the sample code you added to the Samples projects. The sample was only for development and interactive testing; the E2E tests now provide the permanent test coverage. Use `git checkout -- src/Components/Samples` and `git clean -df -- src/Components/Samples` to remove the sample code.
56 
57## Build Tips
58 
59### Efficient Build Strategy
60 
61To avoid unnecessary full repository builds, follow this optimized approach:
62 
63#### 1. Initial Setup - Check for First Build
64Before running any commands, check if a full build has already been completed:
65- Look for `artifacts\agent-sentinel.txt` in the repository root
66- If this file exists, skip to step 2
67- If not present, run the initial build and create the sentinel file:
68 
69```bash
70.\eng\build.cmd
71echo "We ran eng\build.cmd successfully" > artifacts\agent-sentinel.txt
72```
73 
74#### 2. Check for JavaScript Assets
75Before running tests or samples, verify that JavaScript assets are built:
76- Check for `src\Components\Web.JS\dist\Debug\blazor.web.js`
77- If not present, run from the repository root: `npm run build`
78 
79#### 3. Iterating on C# Changes
80 
81**Most of the time (no dependency changes):**
82```bash
83dotnet build --no-restore -v:q
84```
85 
86Or with `eng\build.cmd`:
87```bash
88.\eng\build.cmd -NoRestore -NoBuildDeps -NoBuildNative -NoBuildNodeJS -NoBuildJava -NoBuildInstallers -verbosity:quiet
89```
90 
91**When you've added/changed project references or package dependencies:**
92 
93First restore:
94```bash
95.\restore.cmd
96```
97 
98Then build:
99```bash
100dotnet build --no-restore -v:q
101```
102 
103**Note:** The `-v:q` (or `-verbosity:quiet`) flag minimizes build output to only show success/failure and error details. Remove this flag if you need to see detailed build output for debugging.
104 
105#### 4. Building Individual Projects (Fixing Build Errors)
106 
107When fixing build errors in a specific project, you can build just that project without its dependencies for even faster iteration:
108 
109```bash
110dotnet build <path-to-project.csproj> --no-restore --no-dependencies -v:q
111```
112 
113**When to use `--no-dependencies`:**
114- Fixing compilation errors in a single project (syntax errors, type errors, etc.)
115- Making isolated changes that don't affect project references
116- Rapid iteration on a specific library
117 
118**When NOT to use `--no-dependencies`:**
119- You've changed public APIs that other projects depend on
120- You need to verify that dependent projects still compile correctly
121- You're unsure if your changes affect other projects (safer to build without this flag)
122 
123**Example:**
124```bash
125# Fix a compilation error in Components.Endpoints
126dotnet build src\Components\Endpoints\src\Microsoft.AspNetCore.Components.Endpoints.csproj --no-restore --no-dependencies -v:q
127```
128 
129#### Quick Reference
130 
1311. **First time only**: `.\eng\build.cmd` → create `artifacts\agent-sentinel.txt`
1322. **Check JS assets**: Verify `src\Components\Web.JS\dist\Debug\blazor.web.js` exists, run `npm run build` if missing
1333. **Most C# changes**: `dotnet build --no-restore -v:q`
1344. **Fixing build errors in one project**: `dotnet build <project.csproj> --no-restore --no-dependencies -v:q`
1355. **Added/changed dependencies**: Run `.\restore.cmd` first, then use step 3
136 
137### E2E Testing Structure
138 
139Tests live in `src/Components/test`. The structure includes:
140 
141- **testassets folder** - Contains test assets and scenarios
142- **Components.TestServer project** - A web application that launches multiple web servers with different scenarios (different project startups). Avoid adding new startup files unless strictly necessary.
143 
144### Running E2E Tests Manually
145 
1461. **Build the tests**: Follow the build instructions to build the E2E test project and its dependencies.
1472. **Start Components.TestServer**:
148```bash
149   cd src\Components\test\testassets\Components.TestServer
150   dotnet run --project Components.TestServer.csproj
151```
1523. **Navigate to the test server** - The main server runs on `http://127.0.0.1:5019/subdir`
1534. **Select a test scenario** - The main page shows a dropdown with all available test components
1545. **Reproduce the scenario** to verify it works the same way as in the sample
155 
156Note: There are also other server instances launched for different test configurations (authentication, CORS, prerendering, etc.). These are listed in the "scenarios" table on the main page.
157 
158### Understanding Logging Configuration
159 
160#### Server-side (.NET) Logging
161 
162The server uses `Microsoft.Extensions.Logging.Testing.TestSink` for capturing logs. Log configuration is in `Program.cs`:
163 
164```csharp
165.ConfigureLogging((ctx, lb) =>
166{
167    TestSink sink = new TestSink();
168    lb.AddProvider(new TestLoggerProvider(sink));
169    lb.Services.Add(ServiceDescriptor.Singleton(sink));
170})
171```
172 
173#### Client-side (Blazor WebAssembly) Logging
174 
175Logs appear in the browser console. Log levels:
176- Logs with `warn:` prefix are Warning level
177- Logs with `info:` prefix are Information level
178- Logs with `fail:` prefix are Error level
179 
180The Blazor WebAssembly log level can be configured at startup:
181 
182```javascript
183Blazor.start({
184    logLevel: 1 // LogLevel.Debug
185});
186```
187 
188LogLevel values: Trace=0, Debug=1, Information=2, Warning=3, Error=4, Critical=5
189 
190For Server-side Blazor (SignalR):
191```javascript
192Blazor.start({
193    circuit: {
194        configureSignalR: builder => {
195            builder.configureLogging("debug") // LogLevel.Debug
196        }
197    }
198});
199```
200 
201#### Viewing Logs in Playwright
202 
203Use `browser_console_messages` to see JavaScript console output including .NET logs routed to the console.
204 
205### Creating E2E Tests
206 
207E2E tests are located in `src/Components/test/E2ETest`.
208 
2091. First, check if there are already E2E tests for the component/feature area you're working on
2102. Try to add an additional test to existing test files when possible
2113. When adding test coverage, prefer extending existing test components and assets over creating a set of new ones if it doesn't complicate the existing ones excessively. This reduces test infrastructure complexity and keeps related scenarios together.
212 
213### Running E2E Tests
214 
215The E2E tests use Selenium. To build and run tests:
216 
217```bash
218# Build the E2E test project and its dependencies
219dotnet build src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-restore -v:q
220 
221# After the build succeeds, run a specific test
222dotnet test src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-build --filter &quot;FullyQualifiedName~TestName&quot;
223```
224 
225For the first E2E run in a fresh worktree, or after relevant build, configuration, or output changes, run the dependency-aware build above. Do not use `--no-dependencies` to prepare E2E tests when referenced test-app outputs may be stale or missing. It may copy existing dependency outputs, but it does not rebuild referenced projects or apps. After the build succeeds, `--no-build` is the supported fast loop for repeated targeted tests while those inputs remain unchanged.
226 
227**Important**: Never run all E2E tests locally as that is extremely costly. Full test runs should only happen on CI machines.
228 
229If a test is failing, it's best to run the server manually and navigate to the test to investigate. The test output won't be very useful for debugging.
230