diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index deb035e73..be37e1c33 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,20 +13,20 @@ There are many ways to contribute: - **DO** use a descriptive title that identifies the issue to be addressed or the requested feature. - **DO** specify a detailed description of the issue or requested feature. - **DO** provide the following for bug reports - - Describe the expected behavior and the actual behavior. If it is not self-evident such as in the case of a crash, provide an explanation for why the expected behavior is expected. + - Describe the expected behavior and the actual behavior. If it is not self-evident such as in the case of a crash, explain why the expected behavior is expected. - Provide example code that reproduces the issue. - Specify any relevant exception messages and stack traces. -- **DO** subscribe to notifications for the created issue in case there are any follow up questions. +- **DO** subscribe to notifications for the created issue in case there are any follow-up questions. ## Submitting Pull Requests -- **DO** ensure submissions pass all Azure DevOps legs and are merge conflict free. +- **DO** ensure submissions pass all Azure DevOps legs and are merge conflict-free. - **DO** follow the [.editorconfig](http://editorconfig.org/) settings for each directory. - **DO NOT** submit Pull Requests without having an approved feature request or enhancement. -- **DO NOT** submit large code formatting changes without discussing with the team first. +- **DO NOT** submit large code formatting changes without discussing them with the team first. ## Coding Style -The MSTest project follows the same rules as runtime repository [developer guide](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/coding-style.md). +The MSTest project follows the same rules as the runtime repository [developer guide](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/coding-style.md). The repository includes [.editorconfig](http://editorconfig.org) files to help enforce this convention. Contributors should ensure they follow these guidelines when making submissions. diff --git a/README.md b/README.md index 33e6e1eef..09e6598c4 100644 --- a/README.md +++ b/README.md @@ -10,17 +10,17 @@ [![Commit Activity](https://img.shields.io/github/commit-activity/m/microsoft/testfx)](.) [![Build Status](https://dev.azure.com/dnceng-public/public/_apis/build/status/Microsoft/testfx/microsoft.testfx?branchName=main)](https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=209&branchName=main) -MSTest, Microsoft Testing Framework, is a unit testing framework for .NET applications. It allows you to write tests, use Test Explorer, create test suites, and apply the red, green, refactor pattern to write code. +MSTest, Microsoft Testing Framework, is a unit testing framework for .NET applications. It allows you to write tests, use Test Explorer, create test suites, and apply the red, green, and refactor patterns to write code. -This is a fully supported, open source and cross-platform test framework with which to write tests targeting .NET Framework, .NET Core, .NET, UWP and WinUI on Windows, Linux, and Mac. +This is a fully supported, open source, and cross-platform test framework with which to write tests targeting .NET Framework, .NET Core, .NET, UWP, and WinUI on Windows, Linux, and Mac. ## How can I contribute? We welcome any kind of contribution! -- [Contributing](./CONTRIBUTING.md) provides guidance on how to best contribute +- [Contributing](./CONTRIBUTING.md) guides how to best contribute - [Dev Guide](./docs/dev-guide.md) explains how to build and test -- [Documentation](docs/README.md) contains information about history, context and supported or unsupported features. It also gather the various official documentation pages on learn.microsoft.com about MSTest. +- [Documentation](docs/README.md) contains information about the history, context, and supported or unsupported features. It also gathers the various official documentation pages on learn.microsoft.com about MSTest. ## How to consume MSTest? @@ -29,7 +29,7 @@ MSTest is shipped as NuGet packages that can be added to your projects. The foll | Name | Description | Stable version | Preview version | Dogfood version | |--------------|---------|:--------------:|:---------------:|:---------------:| | MSTest | This package is a meta package that simplifies referencing all recommended MSTest packages. | [![#](https://img.shields.io/nuget/v/mstest.svg?style=flat)](http://www.nuget.org/packages/MSTest/) | [![#](https://img.shields.io/nuget/vpre/mstest.svg?style=flat)](http://www.nuget.org/packages/MSTest/) | [Azure Artifacts](https://dnceng.visualstudio.com/public/_artifacts/feed/test-tools/NuGet/MSTest/versions) | -| MSTest.TestFramework | This package includes the libraries for writing tests with MSTest. To ensure discovery and execution of your tests, install the `MSTest.TestAdapter`` package. | [![#](https://img.shields.io/nuget/v/mstest.testframework.svg?style=flat)](http://www.nuget.org/packages/MSTest.TestFramework/) | [![#](https://img.shields.io/nuget/vpre/mstest.testframework.svg?style=flat)](http://www.nuget.org/packages/MSTest.TestFramework/) | [Azure Artifacts](https://dnceng.visualstudio.com/public/_artifacts/feed/test-tools/NuGet/MSTest.TestFramework/versions) | +| MSTest.TestFramework | This package includes the libraries for writing tests with MSTest. To ensure the discovery and execution of your tests, install the `MSTest.TestAdapter`` package. | [![#](https://img.shields.io/nuget/v/mstest.testframework.svg?style=flat)](http://www.nuget.org/packages/MSTest.TestFramework/) | [![#](https://img.shields.io/nuget/vpre/mstest.testframework.svg?style=flat)](http://www.nuget.org/packages/MSTest.TestFramework/) | [Azure Artifacts](https://dnceng.visualstudio.com/public/_artifacts/feed/test-tools/NuGet/MSTest.TestFramework/versions) | | MSTest.TestAdapter | This package includes the adapter logic to discover and run tests. For access to the testing framework, install the `MSTest.TestFramework` package. | [![#](https://img.shields.io/nuget/v/mstest.testadapter.svg?style=flat)](http://www.nuget.org/packages/MSTest.TestAdapter/) | [![#](https://img.shields.io/nuget/vpre/mstest.testadapter.svg?style=flat)](http://www.nuget.org/packages/MSTest.TestAdapter/) | [Azure Artifacts](https://dnceng.visualstudio.com/public/_artifacts/feed/test-tools/NuGet/MSTest.TestAdapter/versions) | | MSTest.Analyzers | This package includes code analyzers and code fixes for MSTest. | [![#](https://img.shields.io/nuget/v/mstest.analyzers.svg?style=flat)](http://www.nuget.org/packages/MSTest.Analyzers/) | [![#](https://img.shields.io/nuget/vpre/mstest.analyzers.svg?style=flat)](http://www.nuget.org/packages/MSTest.Analyzers/) | [Azure Artifacts](https://dnceng.visualstudio.com/public/_artifacts/feed/test-tools/NuGet/MSTest.Analyzers/versions) | diff --git a/docs/README.md b/docs/README.md index af9be7b6a..509649163 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ The following official [learn.microsoft.com website](https://learn.microsoft.com/visualstudio/test/unit-test-basics) contains all the information about writing unit tests, unit test frameworks, integration with CLI and Visual Studio. -This [blog post](https://devblogs.microsoft.com/devops/mstest-v2-now-and-ahead/) announce the vision for MSTest V2. +This [blog post](https://devblogs.microsoft.com/devops/mstest-v2-now-and-ahead/) announces the vision for MSTest V2. For API documentation refer [here](https://docs.microsoft.com/dotnet/api/microsoft.visualstudio.testtools.unittesting). @@ -15,7 +15,7 @@ For API documentation refer [here](https://docs.microsoft.com/dotnet/api/microso You can find the main differences with MSTest v1 in [Deltas w.r.t MSTest V1](delta-with-MSTestV1.md). -You can find detailed examples and explanation of MSTest features at +You can find detailed examples and explanations of MSTest features at - [MSTest element via runsettings](https://learn.microsoft.com/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file#mstest-element) - [Use the MSTest framework in unit tests](https://learn.microsoft.com/visualstudio/test/using-microsoft-visualstudio-testtools-unittesting-members-in-unit-tests) diff --git a/docs/dev-guide.md b/docs/dev-guide.md index 0eccfd18a..515bfeb94 100644 --- a/docs/dev-guide.md +++ b/docs/dev-guide.md @@ -1,10 +1,10 @@ # Development Guide -This document contains all the required information to build, test and consume MSTest. +This document contains all the required information to build, test, and consume MSTest. ## Prerequisites -In order to build and test all functionalities of MSTest, we recommend installing [Visual Studio 2022](https://visualstudio.microsoft.com/) with the following workloads: +To build and test all functionalities of MSTest, we recommend installing [Visual Studio 2022](https://visualstudio.microsoft.com/) with the following workloads: - `.NET desktop development` - `Universal Windows Platform development` @@ -12,10 +12,10 @@ In order to build and test all functionalities of MSTest, we recommend installin ## Recommended workflow -We recommend the following overall workflow when developing for this repository: +We recommend the following overall workflow when developing this repository: - Fork this repository. -- Always work in your fork. +- Always work on your fork. - Always keep your fork up to date. ### Starting with your fork @@ -26,7 +26,7 @@ Before updating your fork, run this command: git remote add upstream https://github.com/Microsoft/testfx.git ``` -This will make management of multiple forks and your own work easier over time. +This will make management of multiple forks and your work easier over time. ### Updating your fork @@ -66,7 +66,7 @@ For Linux and macOS: ### Common building options -By default, the script generates a *Debug* build type, which is not optimized code and includes asserts. As its name suggests, this makes it easier and friendlier to debug the code. If you want to make performance measurements, you ought to build the *Release* version instead, which doesn't have any asserts and has all code optimizations enabled. Likewise, if you plan on running tests, the *Release* configuration is more suitable since it's considerably faster than the *Debug* one. For this, you add the flag `-configuration release` (or `-c release`). For example: +By default, the script generates a *Debug* build type, which is not optimized code and includes asserts. As its name suggests, this makes it easier and friendlier to debug the code. If you want to make performance measurements, you ought to build the *Release* version instead, which doesn't have any assets and has all code optimizations enabled. Likewise, if you plan on running tests, the *Release* configuration is more suitable since it's considerably faster than the *Debug* one. For this, you add the flag `-configuration release` (or `-c release`). For example: For Windows: @@ -80,13 +80,13 @@ For Linux and macOS: ./build.sh --configuration release ``` -Another common flag is `-pack` that will produce the NuGet packages of MSTest. These packages are required for the acceptance tests (see [testing section](#testing)). +Another common flag is `-pack` which will produce the NuGet packages of MSTest. These packages are required for the acceptance tests (see [testing section](#testing)). For more information about all the different options available, supply the argument `-help|-h` when invoking the build script. On Unix-like systems, non-abbreviated arguments can be passed in with a single `-` or double hyphen `--`. ### Build layout -MSTest uses Microsoft common infrastructure called [arcade](https://github.com/dotnet/arcade) as such all outputs are following this structure: +MSTest uses Microsoft common infrastructure called [arcade](https://github.com/dotnet/arcade) as such all outputs follow this structure: ```text artifacts @@ -159,10 +159,10 @@ For Linux and macOS: ./build.sh -pack -test -integrationTest ``` -Note that `-test` allows to run the unit tests and `-integrationTest` allows to run the two kind of integration tests. Acceptance integration tests require the NuGet packages to have been produced hence the `-pack` flag. +Note that `-test` allows to run the unit tests and `-integrationTest` allows to run the two kinds of integration tests. Acceptance integration tests require the NuGet packages to have been produced hence the `-pack` flag. ## Working with Visual Studio -If you are working with Visual Studio, we recommend opening it through the `open-vs.cmd` script at the repo root. This script will set all the required environment variables required so that Visual Studio picks up the locally downloaded version of the .NET SDK. If you prefer to use your machine wide configuration, you can open Visual Studio directly. +If you are working with Visual Studio, we recommend opening it through the `open-vs.cmd` script at the repo root. This script will set all the required environment variables required so that Visual Studio picks up the locally downloaded version of the .NET SDK. If you prefer to use your machine-wide configuration, you can open Visual Studio directly. -Inside of Visual Studio, all projects can be built normally. All but acceptance tests can be tested directly from Visual Studio. The acceptance tests will always use the version of the NuGet packages produced in the `artifacts/packages/shipping` folder so if you have made some changes and run these tests, it's likely that the changes will not be applied. +Inside Visual Studio, all projects can be built normally. All but acceptance tests can be tested directly from Visual Studio. The acceptance tests will always use the version of the NuGet packages produced in the `artifacts/packages/shipping` folder so if you have made some changes and run these tests, it's likely that the changes will not be applied.