Updated installation instructions (#793)

* Updated installation instructions * Updated installation instructions * give a UID to the installation page So that it can be cross-referenced by ID rather than path * Add uid for nunit lite runner Should resolve the other xref warning * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/installation.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/dotnet-core-and-dotnet-standard.md Co-authored-by: Sean Killeen <[email protected]> * Update docs/articles/nunit/getting-started/dotnet-core-and-dotnet-standard.md * convert to note * convert to note * change markdown to use xml --------- Co-authored-by: Sean Killeen <[email protected]>
nunit · Sep 22, 2023 · 257a56c · 257a56c
1 parent a313455
commit 257a56c
Show file tree

Hide file tree

Showing 4 changed files with 135 additions and 22 deletions.
diff --git a/docs/articles/nunit/getting-started/dotnet-core-and-dotnet-standard.md b/docs/articles/nunit/getting-started/dotnet-core-and-dotnet-standard.md
@@ -2,20 +2,21 @@
 
 More information and getting started tutorials are available for NUnit and .NET Core targeting [C#](https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-with-nunit), [F#](https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-fsharp-with-nunit) and [Visual Basic](https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-visual-basic-with-nunit) in the .NET Core documentation's [Unit Testing in .NET Core and .NET Standard](https://docs.microsoft.com/en-us/dotnet/core/testing/) page.
 
-Each test project needs to reference version 4.1.0 or later of the NUnit3 Visual Studio Test Adapter.
+The other information on this page is older documentation. If you follow the instructions in the [Installation section](xref:installation) your project will work with .NET Core and .NET Standard.
 
-It is recommended to install the adapter from NuGet if you are testing .NET Core or .NET Standard projects.
-The VSIX adapter has been deprecated for VS2019. Latest version is 3.17.0. For VS2022 there is no VSIX adapter.
+The test projects have to be .NET Core or .NET Framework; .NET Standard can't be used as a test project, since it can't be run on its own, but any code in a .NET Standard library can be tested from a .NET Core or .NET Framework test project.
 
-Adding this adapter and `Microsoft.NET.Test.Sdk` version `17.0.0` to your NUnit test projects will also enable the `dotnet test` command for .NET Core projects.
+## TL;DR
+
+Adding the adapter and `Microsoft.NET.Test.Sdk` version `17.0.0` or greater to your NUnit test projects will also enable the `dotnet test` command for .NET Core projects.
 
 Any tests using the new style CSPROJ format, either .NET Core or .NET 4.x, need to add a `PackageReference` to the NuGet package `Microsoft.NET.Test.Sdk`. Your test assemblies must also be .NET Core or .NET 4.x, not .NET Standard.
 
 ```xml
 <ItemGroup>
-  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.5.0" />
-  <PackageReference Include="NUnit" Version="3.9.0" />
-  <PackageReference Include="NUnit3TestAdapter" Version="3.9.0" />
+  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.7.2" />
+  <PackageReference Include="NUnit" Version="3.13.3" />
+  <PackageReference Include="NUnit3TestAdapter" Version="4.5.0" />
 </ItemGroup>
 ```
 
@@ -57,7 +58,7 @@ This is a limitation of Visual Studio, hopefully it will be fixed in a future re
 
 Meanwhile, you can run specific tests using the `--framework` command line option of [dotnet test](https://docs.microsoft.com/en-ca/dotnet/core/tools/dotnet-test?tabs=netcore2x)
 
-#### How do I produce a test results file
+## How do I produce a test results file
 
 `dotnet test` can generate an NUnit3 test result file by adding a runsettings property. The property to add is [TestOutputXml](/articles/vs-test-adapter/Tips-And-Tricks.html#testoutputxml). This generation is done using the NUnit Engine report service, and produce the same result as the [NUnit3-console](https://www.nuget.org/packages/NUnit.Console/). This is available through the [NUnit3TestAdapter](https://www.nuget.org/packages/NUnit3TestAdapter).
 

diff --git a/docs/articles/nunit/getting-started/installation.md b/docs/articles/nunit/getting-started/installation.md
@@ -1,43 +1,151 @@
+---
+uid: installation
+---
+
 # Installation
 
-To get a copy of the NUnit 3, you can use various installation approaches.
+To install NUnit, you can use various installation approaches, depending upon your preferred development environment and preferences.
+
+## I'm using Visual Studio as my development tool
+
+You can add a NUnit project from the `Add New Project` dialog. Search for `NUnit` and choose the `NUnit Test Project` template.
+
+This will add a new project to your solution, containing a single test class and a single test method. Your project file will have the necessary references to NUnit, the NUnit Test Adapter, the NUnit Analyzer, Microsoft Test SDK and the coverlet code coverage package.
+
+> [!NOTE]
+> Be aware that the templates behind this may be out of date, so always go to the `Manage NuGet Packages` dialog and update to the latest version of all packages there.
+
+## I'm using Visual Studio Code as my development tool
+
+Ensure you have the [C# Dev Kit](https://code.visualstudio.com/docs/csharp/get-started) installed. Then `Shift+CTRL+P`, type `New` and select `New Project`. Select `NUnit 3 Test Project` and follow the prompts.
+The results will be exactly the same as if you had used Visual Studio.
+
+Rider has built-in support for NUnit, and is using the same template, so you'll achieve the same result.
+
+## I'm using Rider as my development tool
+
+This is the same procedure as for Visual Studio: `Add New Project`, select the `NUnit Test Project` template, and follow the prompts.
+The results will be exactly the same as if you had used Visual Studio.
+
+## I prefer to do this using the command line or any of the built-in terminals
+
+From your solution folder, run `dotnet new nunit -o TestProject1` to create a new NUnit test project in the folder `TestProject1`.
+The results will be exactly the same as if you had used Visual Studio.
+
+## Examples of what you get
+
+All of the above will create a new project with the following structure, after updating the packages to the latest versions (as of Sept 2023):
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net8.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+
+        <IsPackable>false</IsPackable>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.7.2" />
+        <PackageReference Include="NUnit" Version="3.13.3" />
+        <PackageReference Include="NUnit3TestAdapter" Version="4.5.0" />
+        <PackageReference Include="NUnit.Analyzers" Version="3.7.0">
+          <PrivateAssets>all</PrivateAssets>
+          <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+        <PackageReference Include="coverlet.collector" Version="6.0.0">
+          <PrivateAssets>all</PrivateAssets>
+          <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+     </ItemGroup>
+
+</Project>
+
+```
+
+It will create a `UnitTest1.cs` file with the following contents:
+
+```cs
+namespace TestProject1;
+
+public class Tests
+{
+    [SetUp]
+    public void Setup()
+    {
+    }
+
+    [Test]
+    public void Test1()
+    {
+        Assert.Pass();
+    }
+}
+```
+
+and a `Usings.cs` file:
+
+```cs
+global using NUnit.Framework;
+```
+
+## Adding NUnit to an existing test project
+
+If you need to update an existing test project to use NUnit -- perhaps a .NET Standard class lib you want to convert to a test project, or adding NUnit to a project that already has XUnit or MSTest -- you can do that by adding the `ItemGroup` in the `.csproj` file above to your project file, and then the appropriate `using NUnit.Framework;` in your code.
+
+Also note that multiple different test frameworks (XUnit, MSTest, NUnit) can co-exist in the same test project, preferably in different files to avoid name clashes. See [this blog post](https://devblogs.microsoft.com/devops/part-2using-traits-with-different-test-frameworks-in-the-unit-test-explorer/) for details.
+
+## TL;DR
+
+All of the above ways to create a new NUnit project will result in the same structure, the same test class and methods, and the same packages being installed. That means you can do it any way you like, you can start with one tool and continue with another.
+
+The template used is maintained as part of .NET and will be upgraded when .NET updates. All the above pick the template from .NET, which is why the end result is the same.
+
+## I want to do it the old and hard way
+
+This is from the older documentation, and is still valid, but we recommend you use the above methods.
 
 1. Full NUnit install via NuGet.
 2. NUnitLite install via NuGet.
 3. Zip and/or MSI file download.
 4. Combined Approach
 
-## Using NuGet Packages
+### Using NuGet Packages and the NUnit Console
 
 In Visual Studio, from the Tools menu, select NuGet Package Manager | Manage NuGet packages for solution...
 Open the Browser tab, and Scroll or use search to locate the **NUnit** and **NUnit.Console** packages.
 
-## NUnit and NUnit.Console
+### NUnit and NUnit.Console
 
 Install both packages. The **NUnit** package should be referenced by each of your test assemblies, but not by any others.
 
 Locate nunit3-console in the **packages\NUnit.ConsoleRunner.3.X.X\tools** (or your configured package directory of choice) directory under your solution. This is the location from which you must run nunit3-console when if you would like to run NUnit3 from console.
 We recommend you only use this approach when running under the control of a script on your build server.
 
-## NUnit3TestAdapter
+ [See here for more details of using the NUnit Console app](https://github.com/nunit/nunit-console#readme).
 
-If you want to run NUnit tests automated on a clean machine without any installations (e.g. TFS build agent) - and you're using Visual Studio 2012 or later, use this package.
+## NUnit3TestAdapter
 
-It's based on [the Visual Studio Test Adapter](xref:vstestadapterinstallation) and provides a compiled NUnit3 Visual Studio Test Adapter.
+If you want to automate the running of NUnit tests on a clean machine without any installations (e.g. Azure DevOps or GitHub Actions build agents) - and you're using Visual Studio 2012 or later, use this package.
 
-### Using NuGet NUnitLite Package
+See [the Visual Studio Test Adapter](xref:vstestadapterinstallation) for details.
 
-The NUnitLite approach provides a way to run NUnit tests without a full install of the NUnit runner and test engine assemblies. Only the framework and a small runner program are installed. Note that this is currently the only way to run tests under SilverLight 5.0 or the compact framework.
+> [!NOTE]
+> If you have used any of the above 4 approaches, you already have this package installed, and it will work on any CI build system.
 
-In Visual Studio, from the Tools menu, select NuGet Package Manager | Manage NuGet packages for solution...
+### Using NuGet NUnitLite Package
 
-Scroll or use search to locate the **NUnitLite Version 3** and install it. The package should be referenced by each of your test assemblies, but not by any others.
+The NUnitLite approach provides a way to run NUnit tests without a full install of the NUnit runner and test engine assemblies. Only the framework and a small runner program are installed. If you want to experiment with NUnit or debug something in NUnit, this can be a helpful choice.
 
-As a result of your installation, a file named "Program.cs" will have been copied into each of your test projects. NUnitLite test projects are console applications and this file contains the Main() program for your tests. If you already have a Main() in some other class, you may delete the file. This file also contains comments describing how the main should call the NUnitLite runner.
+Follow the instructions for [NUnitLite](xref:nunitlite) to install the package and create a test assembly. You will need to add a reference to the `NUnitLite` package in your test assembly.
 
 To run your tests, simply run your executable test assembly. No other runner is needed.
 
-### Downloading the Zip File
+Note that since this approach includes a `Program.cs` it can not be combined with the ordinary unit test project, as that would create two entry points, which would confuse the compiler.
+
+### Downloading the Zip File -- Not Recommended
 
 Download the latest binary zip of the NUnit Framework from our [Download page](https://nunit.org/download/). Unzip the file into any convenient directory.
 

diff --git a/docs/articles/nunit/getting-started/toc.yml b/docs/articles/nunit/getting-started/toc.yml
@@ -2,9 +2,9 @@
   href: installation.md
 - name: Upgrading
   href: upgrading.md
-- name: .NET Core and .NET Standard
-  href: dotnet-core-and-dotnet-standard.md
 - name: Samples
   href: samples.md
 - name: Breaking Changes
   topicUid: breakingchanges
+- name: .NET Core and .NET Standard
+  href: dotnet-core-and-dotnet-standard.md
diff --git a/docs/articles/nunit/running-tests/NUnitLite-Runner.md b/docs/articles/nunit/running-tests/NUnitLite-Runner.md
@@ -1,3 +1,7 @@
+---
+uid: nunitlite
+---
+
 # NUnite Lite Runner
 
 NUnitLite started out life as a separate version of the NUnit framework, with fewer features and a built-in test runner. It ran on devices as well as on desktop .NET and mono and allowed users to create executable tests without the overhead of a full NUnit installation.