Back to Details

scaffold-dotnet-test-project

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scaffold a .NET Test Project

搭建.NET测试项目

Create the smallest test project that fits the repository's existing build and test conventions, wire it to the correct production project and build entry point, and prove solution-level test discovery sees it. This skill scaffolds the container for tests; it does not invent a solution-wide test architecture.
创建符合仓库现有构建和测试规范的最小测试项目，将其关联至正确的生产项目和构建入口点，并验证解决方案级别的测试发现机制能够识别它。本技能仅搭建测试容器，不会设计全解决方案的测试架构。

When to Use

适用场景

  • A .NET solution or project has production code but no suitable test project.
  • A user asks to "set up tests" or "add a test project" from a vague starting point.
  • Tests pass when the new 
    .csproj
    is targeted directly but CI cannot discover it.
  • A multi-project solution needs a bounded test project for one production project.
  • .NET解决方案或项目包含生产代码，但无合适的测试项目。
  • 用户从模糊的起点要求「设置测试」或「添加测试项目」。
  • 直接针对新的
    .csproj
    运行时测试通过，但CI无法发现该测试项目。
  • 多项目解决方案需要为某个生产项目创建一个限定范围的测试项目。

When Not to Use

不适用场景

  • A compatible test project already references the target production project. Reuse it and continue with 
    code-testing-agent
    .
  • The request is specifically about authoring or modernizing MSTest test code. Use 
    writing-mstest-tests
    after the project exists.
  • The repository's current build is broken for an unrelated reason. Report that blocker; do not redesign project structure to hide it.
  • The user asks to migrate xUnit, NUnit, MSTest, TUnit, VSTest, or MTP.
  • 已有兼容的测试项目引用了目标生产项目。请复用该项目并继续使用
    code-testing-agent
    。
  • 请求明确涉及编写或现代化MSTest测试代码。请在项目创建完成后使用
    writing-mstest-tests
    。
  • 仓库当前构建因无关原因失败。请报告该阻塞问题；不要通过重新设计项目结构来掩盖它。
  • 用户要求迁移xUnit、NUnit、MSTest、TUnit、VSTest或MTP。

Inputs

输入参数

InputRequiredDescription
Repository or solution pathNoDiscover from the current workspace when omitted
Production projectNoInfer the narrowest project in the requested scope
Test frameworkNoUse an explicit choice; otherwise infer repository convention
Build entry pointNoExisting 
.sln
, 
.slnx
, 
.slnf
, or project graph used by CI
输入项是否必填描述
仓库或解决方案路径否若省略则从当前工作区自动发现
生产项目否从请求范围中推断最窄范围的项目
测试框架否使用明确指定的框架；否则推断仓库的规范
构建入口点否CI使用的现有
.sln
、
.slnx
、
.slnf
或项目图

Workflow

工作流程

Step 1: Establish the repository contract

步骤1：确定仓库约定

Inspect only the files needed to answer these questions:
  1. Which production project is in scope?
  2. What command does CI or the repository use to build and test?
  3. Does a suitable test project already reference that production project?
  4. Which test framework and runner do neighboring test projects use?
  5. Are package versions centrally managed by 
    Directory.Packages.props
    , 
    Directory.Build.props
    , 
    global.json
    , or an MSBuild SDK declaration?
  6. Which target framework(s) must the test project compile against?
Treat a test project as suitable only when its target framework can reference the production project and its purpose matches the requested layer. Do not create a second test project merely because its name differs from your preferred name.
No-op stop condition: when a suitable project already exists and is registered in the requested build entry point, do not repair, normalize, convert, or replace the solution. If the user did not ask for tests yet, report the existing project path and stop with the workspace byte-for-byte unchanged.
仅检查需要回答以下问题的文件：
  1. 哪些生产项目在范围内？
  2. CI或仓库使用什么命令来构建和测试？
  3. 是否已有合适的测试项目引用了该生产项目？
  4. 相邻的测试项目使用哪种测试框架和运行器？
  5. 包版本是否由
    Directory.Packages.props
    、
    Directory.Build.props
    、
    global.json
    或MSBuild SDK声明集中管理？
  6. 测试项目必须针对哪些目标框架进行编译？
只有当测试项目的目标框架能够引用生产项目，且其用途与请求的层级匹配时，才认为该测试项目是合适的。不要仅仅因为名称与你偏好的不同就创建第二个测试项目。
无操作终止条件：当合适的项目已存在并已注册到请求的构建入口点时，不要修复、标准化、转换或替换解决方案。如果用户尚未要求添加测试，只需报告现有项目路径并保持工作区完全不变后终止操作。

Step 2: Choose one bounded project

步骤2：选择一个限定范围的项目

Default to one test project per production project, named according to repository convention (
Foo.Tests
, 
Foo.UnitTests
, and so on). For a vague multi-project request, start with the project that owns the user-visible behavior or has the highest-value untested logic; do not create one test project per source project without evidence that the repository wants that layout.
Match, in order:
  1. The user's explicit framework choice.
  2. Existing test projects in the same repository.
  3. Repository-wide package/SDK conventions.
  4. A standard SDK template only when the repository provides no convention.
Never mix frameworks in one test project. Never add package versions directly when central package management supplies them.
默认每个生产项目对应一个测试项目，命名遵循仓库约定（如
Foo.Tests
、
Foo.UnitTests
等）。对于模糊的多项目请求，从拥有用户可见行为或具有最高价值未测试逻辑的项目开始；不要在没有证据表明仓库需要该布局的情况下，为每个源项目创建一个测试项目。
按以下优先级匹配：
  1. 用户明确指定的框架选择。
  2. 仓库中已有的测试项目。
  3. 仓库范围内的包/SDK约定。
  4. 仅当仓库未提供任何约定时，才使用标准SDK模板。
切勿在一个测试项目中混合使用多种框架。当中央包管理提供包版本时，切勿直接添加包版本。

Step 3: Scaffold and reference the target

步骤3：搭建并关联目标项目

Use the matching 
dotnet new
template (
xunit
, 
nunit
, or 
mstest
) rather than hand-writing template boilerplate. Then make only the repository-specific edits:
  1. Align target framework, nullable, implicit-usings, runner, and package style.
  2. Add a 
    ProjectReference
    to each production project directly exercised by the planned tests. Do not reference every project in the solution.
  3. Remove template sample tests that do not test repository behavior.
For xUnit v3 projects that the repository runs through 
dotnet test
, preserve or add both:
xml
<OutputType>Exe</OutputType>
<TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>
OutputType=Exe
alone makes the self-hosted runner work with 
dotnet run
; it is not evidence that the repository's 
dotnet test
command can discover the tests.
Prefer 
dotnet add <test-project> reference <production-project>
for project references. Inspect the resulting project file before continuing.
使用匹配的
dotnet new
模板（
xunit
、
nunit
或
mstest
），而非手动编写模板样板代码。然后仅进行仓库特定的编辑：
  1. 对齐目标框架、可空类型、隐式using、运行器和包风格。
  2. 添加
    ProjectReference
    到每个计划测试直接调用的生产项目。不要引用解决方案中的所有项目。
  3. 删除与仓库行为无关的模板示例测试。
对于仓库通过
dotnet test
运行的xUnit v3项目，保留或添加以下两项配置：
xml
<OutputType>Exe</OutputType>
<TestingPlatformDotnetTestSupport>true</TestingPlatformDotnetTestSupport>
仅设置
OutputType=Exe
可使自托管运行器配合
dotnet run
工作；但这并不代表仓库的
dotnet test
命令能够发现测试。
优先使用
dotnet add <test-project> reference <production-project>
来添加项目引用。继续操作前请检查生成的项目文件。

Step 4: Register with the real build entry point

步骤4：注册至实际构建入口点

Creating a 
.csproj
is not enough. Add it to the exact solution artifact used by the repository:
  • .sln
    or 
    .slnx
    : 
    dotnet sln <solution> add <test-project>
  • .slnf
    : add the project to the underlying solution and include it in the filter used by the requested/CI test command.
  • No solution artifact: keep the existing project-oriented workflow. Do not create a solution solely for aesthetics unless the user asked for one.
Do not substitute a different solution file because it is easier to edit.
仅创建
.csproj
是不够的。需将其添加至仓库使用的具体解决方案工件中：
  • .sln
    或
    .slnx
    ：执行
    dotnet sln <solution> add <test-project>
  • .slnf
    ：将项目添加至底层解决方案，并包含在请求/CI测试命令使用的筛选器中。
  • 无解决方案工件：保留现有的面向项目的工作流程。除非用户要求，否则不要仅为了美观而创建解决方案。
不要因为编辑更简单就替换为其他解决方案文件。

Step 5: Add a real smoke test

步骤5：添加真实的冒烟测试

Replace template examples with the smallest smoke suite requested. The tests must:
  • instantiate or invoke a real symbol from the referenced production project;
  • assert a concrete result, not only non-null/truthiness;
  • avoid network, wall-clock, process, and real filesystem dependencies.
These tests prove the project reference and discovery path. Stop after every behavior explicitly named by the user is covered; extra boundary permutations are out of scope here and belong to 
code-testing-agent
.
用用户要求的最小冒烟测试套件替换模板示例。测试必须满足：
  • 实例化或调用引用生产项目中的真实符号；
  • 断言具体结果，而非仅断言非空/真值；
  • 避免依赖网络、时钟、进程和真实文件系统。
这些测试用于验证项目引用和发现路径。在覆盖用户明确指定的所有行为后停止；额外的边界排列超出了本技能的范围，属于
code-testing-agent
的职责。

Step 6: Verify direct and harness-level execution

步骤6：验证直接执行和 harness 级执行

Run, in this order:
  1. dotnet test <test-project>
    to isolate scaffolding failures.
  2. The repository's solution/root test command to prove CI discovery.
  3. A solution/project listing command to confirm the new project is registered.
If the direct command passes but the harness-level command discovers no new test, the scaffolding is incomplete. Fix registration before reporting success. Do not claim success from 
dotnet build
alone.
按以下顺序运行：
  1. dotnet test <test-project>
    ：隔离搭建过程中的失败。
  2. 仓库的解决方案/根测试命令：验证CI能够发现测试。
  3. 解决方案/项目列表命令：确认新项目已注册。
如果直接命令通过，但harness级命令未发现新测试，则搭建不完整。在报告成功前修复注册问题。不要仅通过
dotnet build
就声称成功。

Output Contract

输出约定

Report a compact table:
RequirementEvidence
Test project created/reusedProject path
Production referenceReferenced 
.csproj
path
Build registration
.sln
/
.slnx
/
.slnf
entry or project-oriented command
Test discoveryPassing harness-level command and discovered test
If validation is blocked, report the exact failing command and first actionable error. Do not describe an unrun command as successful.
报告一个简洁的表格：
要求证据
测试项目已创建/复用项目路径
生产项目引用被引用的
.csproj
路径
构建注册
.sln
/
.slnx
/
.slnf
条目或面向项目的命令
测试发现通过的harness级命令及发现的测试
如果验证被阻塞，报告确切的失败命令和第一个可解决的错误。不要将未运行的命令描述为成功。

Validation

验证清单

  • A suitable existing test project was ruled out before creating another.
  • Framework, runner, target framework, and package style match the repository.
  • Project references cover only the production projects under test.
  • Central package management was preserved.
  • Template sample tests were removed.
  • At least one real deterministic test asserts a concrete behavior.
  • The test project passes directly.
  • The repository's solution/root command discovers and runs the new test.
  • 在创建新项目之前，已排除存在合适的现有测试项目。
  • 框架、运行器、目标框架和包风格与仓库一致。
  • 项目引用仅覆盖被测生产项目。
  • 保留了中央包管理。
  • 已删除模板示例测试。
  • 至少有一个真实的确定性测试断言了具体行为。
  • 测试项目直接运行通过。
  • 仓库的解决方案/根命令能够发现并运行新测试。

Common Pitfalls

常见陷阱

PitfallCorrective action
Creating a project that CI never seesRegister it with the exact solution/filter used by CI and run that command
Picking a favorite frameworkInfer the repository convention before using a default
Adding package versions under CPMAdd versionless references and keep versions in 
Directory.Packages.props
Referencing the whole solutionReference only projects whose APIs the tests compile against
Keeping 
UnitTest1
Replace it with a concrete test of repository behavior
Creating parallel unit/integration projects from a vague askStart with one bounded project; expand only for a demonstrated boundary
Treating a green build as test discoveryRun the harness-level test command and observe the test
陷阱纠正措施
创建的项目从未被CI识别将其注册至CI使用的具体解决方案/筛选器，并运行该命令
选择偏好的框架在使用默认框架之前，先推断仓库的约定
在CPM下添加包版本添加无版本引用，将版本保留在
Directory.Packages.props
中
引用整个解决方案仅引用测试编译时需要其API的项目
保留
UnitTest1
将其替换为针对仓库行为的具体测试
因模糊请求创建并行的单元/集成项目从一个限定范围的项目开始；仅在有明确边界需求时扩展
将构建成功视为测试已被发现运行harness级测试命令并观察测试结果