Skip to content

Commit 1b871a0

Browse files
javiercnjaviercn
authored
Add an Agents.md file for Blazor (#64603)
* Add an AGENTS.MD file for Blazor
1 parent 46b20bb commit 1b871a0

File tree

1 file changed

+212
-0
lines changed

1 file changed

+212
-0
lines changed

‎src/Components/AGENTS.MD‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# Working on Issues in the Components Area
2+
3+
This guide provides step-by-step instructions for working on issues in the ASP.NET Core Components area.
4+
5+
## Working on New Features
6+
7+
### Overview
8+
9+
The workflow for implementing new features in the Components area follows these steps:
10+
11+
1. **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.
12+
13+
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.
14+
15+
### Sample Projects
16+
17+
The `src/Components/Samples` folder contains several sample projects you can use for developing and testing features:
18+
19+
- **BlazorServerApp** - A Blazor Server application for testing server-side scenarios
20+
- **BlazorUnitedApp** - A Blazor Web App (united/hybrid mode) for testing combined server and WebAssembly scenarios
21+
- **BlazorUnitedApp.Client** - The client-side portion of the BlazorUnitedApp
22+
23+
**Always start by adding your feature scenario to one of these sample projects first.** This allows you to:
24+
- Quickly iterate on the implementation
25+
- Test the feature interactively in a real browser
26+
- Verify the feature works before writing formal E2E tests
27+
- Debug issues more easily with full logging capabilities
28+
29+
3. **Debug when needed**:
30+
- If something isn't working as expected, increase the logging level in the sample for `Microsoft.AspNetCore.Components` to `Debug` to see detailed logs.
31+
- Check browser console logs using Playwright's `browser_console_messages`.
32+
- Use Microsoft documentation to learn more about troubleshooting Blazor applications.
33+
- You can also increase the log level for JavaScript console output.
34+
35+
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.
36+
37+
5. **Implement E2E tests** - Only after the sample is validated, implement E2E tests for it.
38+
39+
6. **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.
40+
41+
## Build Tips
42+
43+
### Efficient Build Strategy
44+
45+
To avoid unnecessary full repository builds, follow this optimized approach:
46+
47+
#### 1. Initial Setup - Check for First Build
48+
Before running any commands, check if a full build has already been completed:
49+
- Look for `artifacts\agent-sentinel.txt` in the repository root
50+
- If this file exists, skip to step 2
51+
- If not present, run the initial build and create the sentinel file:
52+
53+
```bash
54+
.\eng\build.cmd
55+
echo "We ran eng\build.cmd successfully" > artifacts\agent-sentinel.txt
56+
```
57+
58+
#### 2. Check for JavaScript Assets
59+
Before running tests or samples, verify that JavaScript assets are built:
60+
- Check for `src\Components\Web.JS\dist\Debug\blazor.web.js`
61+
- If not present, run from the repository root: `npm run build`
62+
63+
#### 3. Iterating on C# Changes
64+
65+
**Most of the time (no dependency changes):**
66+
```bash
67+
dotnet build --no-restore -v:q
68+
```
69+
70+
Or with `eng\build.cmd`:
71+
```bash
72+
.\eng\build.cmd -NoRestore -NoBuildDeps -NoBuildRepoTasks -NoBuildNative -NoBuildNodeJS -NoBuildJava -NoBuildInstallers -verbosity:quiet
73+
```
74+
75+
**When you've added/changed project references or package dependencies:**
76+
77+
First restore:
78+
```bash
79+
.\restore.cmd
80+
```
81+
82+
Then build:
83+
```bash
84+
dotnet build --no-restore -v:q
85+
```
86+
87+
**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.
88+
89+
#### 4. Building Individual Projects (Fixing Build Errors)
90+
91+
When fixing build errors in a specific project, you can build just that project without its dependencies for even faster iteration:
92+
93+
```bash
94+
dotnet build <path-to-project.csproj> --no-restore --no-dependencies -v:q
95+
```
96+
97+
**When to use `--no-dependencies`:**
98+
- Fixing compilation errors in a single project (syntax errors, type errors, etc.)
99+
- Making isolated changes that don't affect project references
100+
- Rapid iteration on a specific library
101+
102+
**When NOT to use `--no-dependencies`:**
103+
- You've changed public APIs that other projects depend on
104+
- You need to verify that dependent projects still compile correctly
105+
- You're unsure if your changes affect other projects (safer to build without this flag)
106+
107+
**Example:**
108+
```bash
109+
# Fix a compilation error in Components.Endpoints
110+
dotnet build src\Components\Endpoints\src\Microsoft.AspNetCore.Components.Endpoints.csproj --no-restore --no-dependencies -v:q
111+
```
112+
113+
#### Quick Reference
114+
115+
1. **First time only**: `.\eng\build.cmd` → create `artifacts\agent-sentinel.txt`
116+
2. **Check JS assets**: Verify `src\Components\Web.JS\dist\Debug\blazor.web.js` exists, run `npm run build` if missing
117+
3. **Most C# changes**: `dotnet build --no-restore -v:q`
118+
4. **Fixing build errors in one project**: `dotnet build <project.csproj> --no-restore --no-dependencies -v:q`
119+
5. **Added/changed dependencies**: Run `.\restore.cmd` first, then use step 3
120+
121+
### E2E Testing Structure
122+
123+
Tests live in `src/Components/test`. The structure includes:
124+
125+
- **testassets folder** - Contains test assets and scenarios
126+
- **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.
127+
128+
### Running E2E Tests Manually
129+
130+
1. **Build the tests**: Follow the build instructions to build the E2E test project and its dependencies.
131+
2. **Start Components.TestServer**:
132+
```bash
133+
cd src\Components\test\testassets\Components.TestServer
134+
dotnet run --project Components.TestServer.csproj
135+
```
136+
3. **Navigate to the test server** - The main server runs on `http://127.0.0.1:5019/subdir`
137+
4. **Select a test scenario** - The main page shows a dropdown with all available test components
138+
5. **Reproduce the scenario** to verify it works the same way as in the sample
139+
140+
Note: 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.
141+
142+
### Understanding Logging Configuration
143+
144+
#### Server-side (.NET) Logging
145+
146+
The server uses `Microsoft.Extensions.Logging.Testing.TestSink` for capturing logs. Log configuration is in `Program.cs`:
147+
148+
```csharp
149+
.ConfigureLogging((ctx, lb) =>
150+
{
151+
TestSink sink = new TestSink();
152+
lb.AddProvider(new TestLoggerProvider(sink));
153+
lb.Services.Add(ServiceDescriptor.Singleton(sink));
154+
})
155+
```
156+
157+
#### Client-side (Blazor WebAssembly) Logging
158+
159+
Logs appear in the browser console. Log levels:
160+
- Logs with `warn:` prefix are Warning level
161+
- Logs with `info:` prefix are Information level
162+
- Logs with `fail:` prefix are Error level
163+
164+
The Blazor WebAssembly log level can be configured at startup:
165+
166+
```javascript
167+
Blazor.start({
168+
logLevel: 1 // LogLevel.Debug
169+
});
170+
```
171+
172+
LogLevel values: Trace=0, Debug=1, Information=2, Warning=3, Error=4, Critical=5
173+
174+
For Server-side Blazor (SignalR):
175+
```javascript
176+
Blazor.start({
177+
circuit: {
178+
configureSignalR: builder => {
179+
builder.configureLogging("debug") // LogLevel.Debug
180+
}
181+
}
182+
});
183+
```
184+
185+
#### Viewing Logs in Playwright
186+
187+
Use `browser_console_messages` to see JavaScript console output including .NET logs routed to the console.
188+
189+
### Creating E2E Tests
190+
191+
E2E tests are located in `src/Components/test/E2ETest`.
192+
193+
1. First, check if there are already E2E tests for the component/feature area you're working on
194+
2. Try to add an additional test to existing test files when possible
195+
3. 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.
196+
197+
### Running E2E Tests
198+
199+
The E2E tests use Selenium. To build and run tests:
200+
201+
```bash
202+
# Build the E2E test project (this includes all test assets as dependencies)
203+
dotnet build src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-restore -v:q
204+
205+
# Run a specific test
206+
dotnet test src/Components/test/E2ETest/Microsoft.AspNetCore.Components.E2ETests.csproj --no-build --filter "FullyQualifiedName~TestName"
207+
```
208+
209+
**Important**: Never run all E2E tests locally as that is extremely costly. Full test runs should only happen on CI machines.
210+
211+
If 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.
212+

0 commit comments

Comments
 (0)