diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 62a742fb1..ae1ede7bf 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -17,7 +17,8 @@ "shuworks.vscode-table-formatter", "ms-dotnettools.csharp", "github.vscode-github-actions", - "ms-azuretools.vscode-docker" + "ms-azuretools.vscode-docker", + "" ] } } diff --git a/.github/linters/.markdownlint.yml b/.github/linters/.markdownlint.yml index 7bc093fed..01dbaabc1 100644 --- a/.github/linters/.markdownlint.yml +++ b/.github/linters/.markdownlint.yml @@ -19,7 +19,10 @@ # Rules by id # ############### MD024: false -MD013: false +MD013: + line_length: 120 + code_blocks: false + tables: false MD026: false MD046: false # Mix of indented and fenced code blocks MD004: false diff --git a/.markdownlintrc b/.markdownlintrc index ca285c6af..d9509f680 100644 --- a/.markdownlintrc +++ b/.markdownlintrc @@ -1,6 +1,11 @@ { "MD024": false, - "MD013": false, + "MD013": { + "line_length": 123, + "code_blocks": false, + "tables": false + + }, "MD026": false, "MD046": false, "MD004": false diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 000000000..229789f63 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,24 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations. + // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp + + // List of extensions which should be recommended for users of this workspace. + "recommendations": [ + "streetsidesoftware.code-spell-checker", + "oderwat.indent-rainbow", + "mdickin.markdown-shortcuts", + "davidanson.vscode-markdownlint", + "redhat.vscode-yaml", + "vsls-contrib.codetour", + "GitHub.vscode-pull-request-github", + "shuworks.vscode-table-formatter", + "ms-dotnettools.csharp", + "github.vscode-github-actions", + "ms-azuretools.vscode-docker", + "stkb.rewrap" + ], + // List of extensions recommended by VS Code that should not be recommended for users of this workspace. + "unwantedRecommendations": [ + + ] +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json index 9850997f8..b6cc11639 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -15,5 +15,9 @@ "cSpell.enabled": true, "cSpell.enableFiletypes": [ "aspnetcorerazor" - ] + ], + "editor.wordWrap": "wordWrapColumn", + "editor.wrappingIndent": "same", + "editor.wordWrapColumn": 120, + "editor.rulers": [120], } \ No newline at end of file diff --git a/cSpell.json b/cSpell.json index d2dff2c9e..dfca064fd 100644 --- a/cSpell.json +++ b/cSpell.json @@ -37,6 +37,7 @@ "prefilter", "Randomizer", "Refactorings", + "reimplementation", "Remoting", "ReSharper", "ruleset", @@ -151,54 +152,57 @@ "Ihor", "Sychevskyi", "Cropp", - "Maddock" + "Maddock", + "Frans", + "Bouma", + "yowko" ], "patterns": [ { - "name": "Markdown links", - "pattern": "\\((.*)\\)", - "description": "" + "name": "Markdown links", + "pattern": "\\((.*)\\)", + "description": "" }, { - "name": "Markdown code blocks", - "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx", - "description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions" + "name": "Markdown code blocks", + "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx", + "description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions" }, { - "name": "Inline code blocks", - "pattern": "\\`([^\\`\\r\\n]+?)\\`", - "description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex" + "name": "Inline code blocks", + "pattern": "\\`([^\\`\\r\\n]+?)\\`", + "description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex" }, { - "name": "Link contents", - "pattern": "\\", - "description": "" + "name": "Link contents", + "pattern": "\\", + "description": "" }, { - "name": "Snippet references", - "pattern": "-- snippet:(.*)", - "description": "" + "name": "Snippet references", + "pattern": "-- snippet:(.*)", + "description": "" }, { - "name": "Snippet references 2", - "pattern": "\\<\\[sample:(.*)", - "description": "another kind of snippet reference" + "name": "Snippet references 2", + "pattern": "\\<\\[sample:(.*)", + "description": "another kind of snippet reference" }, { - "name": "Multi-line code blocks", - "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm" + "name": "Multi-line code blocks", + "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm" }, { - "name": "HTML Tags", - "pattern": "<[^>]*>", - "description": "Reference: https://stackoverflow.com/questions/11229831/regular-expression-to-remove-html-tags-from-a-string" + "name": "HTML Tags", + "pattern": "<[^>]*>", + "description": "Reference: https://stackoverflow.com/questions/11229831/regular-expression-to-remove-html-tags-from-a-string" }, { "name": "UID Lines", "pattern": "uid: (.*)" } - ], - "ignoreRegExpList": [ + ], + "ignoreRegExpList": [ "Markdown links", "Markdown code blocks", "Inline code blocks", @@ -208,5 +212,10 @@ "Multi-line code blocks", "HTML Tags", "UID Lines" - ] + ], + "ignorePaths": [ + "**/articles/nunit-engine/release-notes.md", + "**/articles/nunit/release-notes/framework.md", + "**/articles/vs-test-adapter/AdapterV*-Release-Notes.md" + ] } diff --git a/docs/404.md b/docs/404.md index 5981af750..7a2ac599f 100644 --- a/docs/404.md +++ b/docs/404.md @@ -2,4 +2,5 @@ We're sorry, but the page you're looking for cannot be found on the site. -Feel free to [Open an issue in the NUnit Docs GitHub Repository](https://github.com/nunit/docs/issues/new) with the URL or content you expected to exist, and we'll be happy to look into it. +Feel free to [Open an issue in the NUnit Docs GitHub Repository](https://github.com/nunit/docs/issues/new) with the URL +or content you expected to exist, and we'll be happy to look into it. diff --git a/docs/articles/developer-info/Best-practices-for-XML-documentation.md b/docs/articles/developer-info/Best-practices-for-XML-documentation.md index f6cf716d0..1147d4745 100644 --- a/docs/articles/developer-info/Best-practices-for-XML-documentation.md +++ b/docs/articles/developer-info/Best-practices-for-XML-documentation.md @@ -1,6 +1,8 @@ # Best Practices for XML Documentation -XML documentation has a significant impact on the end user's experience. Unlike other parts of the code, XML comments (as well as exception messages) are user-facing and highly visible. They can save valuable time and even make the difference for an end user between a confusing debugging session and no debugging needed in the first place. +XML documentation has a significant impact on the end user's experience. Unlike other parts of the code, XML comments +(as well as exception messages) are user-facing and highly visible. They can save valuable time and even make the +difference for an end user between a confusing debugging session and no debugging needed in the first place. Polished and informative XML documentation provides a noticeably positive experience. @@ -8,43 +10,56 @@ Polished and informative XML documentation provides a noticeably positive experi Always end sentences with proper punctuation, typically a period. -If there aren't enough words to form a sentence, it's likely that they are redundant. Try to add enough context to make a sentence to avoid anemic documentation. Rather than `The comparer`, say `Used to compare the .` The added clarity is desirable. +If there aren't enough words to form a sentence, it's likely that they are redundant. Try to add enough context to make +a sentence to avoid anemic documentation. Rather than `The comparer`, say `Used to compare the .` The added clarity is desirable. ## ``, `` and `` Use ``, `` and `` whenever possible. -The compiler checks the validity of the names and overloads. Future refactoring can be done with confidence that you aren't leaving the docs out of date. +The compiler checks the validity of the names and overloads. Future refactoring can be done with confidence that you +aren't leaving the docs out of date. -This also provides a seamless experience by creating links in the Object Browser and intellisense and colorizes intellisense. Consider using `` for keywords to maintain the seamlessness. +This also provides a seamless experience by creating links in the Object Browser and intellisense and colorizes +intellisense. Consider using `` for keywords to maintain the seamlessness. ## `` Add a `` tag for each public type and member. -However, prefer to give each type and member a really communicative name. If those names end up covering all the user could need to know, remove the `` tag (if this does not cause a build warning) to avoid super redundant documentation. If they do not, add relevant details. +However, prefer to give each type and member a really communicative name. If those names end up covering all the user +could need to know, remove the `` tag (if this does not cause a build warning) to avoid super redundant +documentation. If they do not, add relevant details. ## `` and `` Add a `` tag for each parameter describing what *effect* it has (rather than what it *is*). -However, prefer to give each parameter a really communicative name. If those names end up covering all the user could need to know about *all* the parameters, remove all the `` tags to avoid super redundant documentation. If they do not, add relevant details to each `` to the extent possible. +However, prefer to give each parameter a really communicative name. If those names end up covering all the user could +need to know about *all* the parameters, remove all the `` tags to avoid super redundant documentation. If they +do not, add relevant details to each `` to the extent possible. -The same applies to `` tags. They are shown by intellisense as the user enters type parameter lists exactly the way `` descriptions are shown as the user enters method parameter lists. `` elements are just as important on generic methods as they are on generic type definitions. +The same applies to `` tags. They are shown by intellisense as the user enters type parameter lists exactly +the way `` descriptions are shown as the user enters method parameter lists. `` elements are just as +important on generic methods as they are on generic type definitions. ## `` and `` -Don't spend any time on the `` or `` tags since the contents are not typically seen. Important details should all be in the ``. If the IDE auto-inserts them, just remove them. +Don't spend any time on the `` or `` tags since the contents are not typically seen. Important details +should all be in the ``. If the IDE auto-inserts them, just remove them. ## Empty tags -Do not leave any empty tags. Either remove them or fill them out. This includes the compiler's all-or-none `` and `` tag enforcement. +Do not leave any empty tags. Either remove them or fill them out. This includes the compiler's all-or-none `` and +`` tag enforcement. ## `` -Consider documenting things that lead to exceptions being thrown using the `` tag. -This can really get the end user up to speed on things that aren't immediately obvious from the method signature. +Consider documenting things that lead to exceptions being thrown using the `` tag. This can really get the +end user up to speed on things that aren't immediately obvious from the method signature. -Sadly intellisense will only show the `` type thrown, not the message, so for important messages it's good to also include the message a second time in the summary: +Sadly intellisense will only show the `` type thrown, not the message, so for important messages it's good to +also include the message a second time in the summary: ```csharp /// diff --git a/docs/articles/developer-info/Coding-Standards.md b/docs/articles/developer-info/Coding-Standards.md index 802aa5c92..a08e4d8d3 100644 --- a/docs/articles/developer-info/Coding-Standards.md +++ b/docs/articles/developer-info/Coding-Standards.md @@ -1,40 +1,64 @@ # Coding Standards -In order to keep the code consistent, we follow certain conventions. Many of the choices we have made are somewhat arbitrary and could easily have gone another way. At this point, most of these conventions are already well-established, so please don't re-open a discussion about them unless you have new issues to present. +In order to keep the code consistent, we follow certain conventions. Many of the choices we have made are somewhat +arbitrary and could easily have gone another way. At this point, most of these conventions are already well-established, +so please don't re-open a discussion about them unless you have new issues to present. -Notice that these standards are all stylistic. Do not write standards that tell people how to program. For example, we don't need a standard that tells us to always dispose of disposable objects because that's part of the normal "standard" for C# programming. In other words, these standards are about relatively trivial things that we have all agreed to do the same way. +Notice that these standards are all stylistic. Do not write standards that tell people how to program. For example, we +don't need a standard that tells us to always dispose of disposable objects because that's part of the normal "standard" +for C# programming. In other words, these standards are about relatively trivial things that we have all agreed to do +the same way. ## Making Changes -If you do want to make changes, please initiate a discussion of what you want to change on the developer list first. If you are intending to standardize more things than we usually standardize, it's wise to discuss it first to avoid wasting time! +If you do want to make changes, please initiate a discussion of what you want to change on the developer list first. If +you are intending to standardize more things than we usually standardize, it's wise to discuss it first to avoid wasting +time! ## General - Please Read This -Follow these guidelines unless you have an extremely good reason not to. Add a comment explaining why you are not following them so others will know your reasoning. +Follow these guidelines unless you have an extremely good reason not to. Add a comment explaining why you are not +following them so others will know your reasoning. -Don't make arbitrary changes in existing code merely to conform them to these guidelines. Normally, you should only change the parts of a file that you have to edit in order to fix a bug or implement new functionality. In particular, don't use automatic formatting to change an entire file at once as this makes it difficult to identify the underlying code changes when we do a code review. +Don't make arbitrary changes in existing code merely to conform them to these guidelines. Normally, you should only +change the parts of a file that you have to edit in order to fix a bug or implement new functionality. In particular, +don't use automatic formatting to change an entire file at once as this makes it difficult to identify the underlying +code changes when we do a code review. -In cases where we make broad changes in layout or naming, they should be committed separately from any bug fixes or feature changes in order to keep the review process as simple as possible. That said, we don't do this very often, since we have real work to do! +In cases where we make broad changes in layout or naming, they should be committed separately from any bug fixes or +feature changes in order to keep the review process as simple as possible. That said, we don't do this very often, since +we have real work to do! -Visual Studio can be set up to match the coding standards by importing the [nunit.vssettings](https://github.com/nunit/docs/blob/master/nunit.vssettings) file from this repository. This file will only change the C# indentation and formatting settings. It will not modify any other Visual Studio settings. It can be imported into Visual Studio 2010 and later by going to Tools | Import and Export Settings... +Visual Studio can be set up to match the coding standards by importing the +[nunit.vssettings](https://github.com/nunit/docs/blob/master/nunit.vssettings) file from this repository. This file will +only change the C# indentation and formatting settings. It will not modify any other Visual Studio settings. It can be +imported into Visual Studio 2010 and later by going to Tools | Import and Export Settings... ## Copyright -NUnit is licensed under the MIT license. Each file is prefixed by the NUnit Copyright Notice `Copyright (c) Charlie Poole, Rob Prouse and Contributors. MIT License - see LICENSE.txt` enclosed in appropriate comment characters for the language of the file. +NUnit is licensed under the MIT license. Each file is prefixed by the NUnit Copyright Notice `Copyright (c) Charlie +Poole, Rob Prouse and Contributors. MIT License - see LICENSE.txt` enclosed in appropriate comment characters for the +language of the file. ### Notes -1. Charlie Poole and Rob Prouse are the copyright holders for the NUnit code on behalf of the NUnit community. Do not place your name on the copyright line if you wish to contribute code. +1. Charlie Poole and Rob Prouse are the copyright holders for the NUnit code on behalf of the NUnit community. Do not + place your name on the copyright line if you wish to contribute code. 2. The year is not included in the copyright file header. -3. In the NUnit Framework project, you can insert the copyright header in a file using the quick fix `Ctrl+.` in Visual Studio. +3. In the NUnit Framework project, you can insert the copyright header in a file using the quick fix `Ctrl+.` in Visual + Studio. ### Language Level -Each NUnit project sets its own C# language level. We generally aim to keep the code buildable by folks who don't necessarily have the latest compilers, so this is sometimes not the very latest level. Currently, the maximum level for most NUnit projects is C# 6. +Each NUnit project sets its own C# language level. We generally aim to keep the code buildable by folks who don't +necessarily have the latest compilers, so this is sometimes not the very latest level. Currently, the maximum level for +most NUnit projects is C# 6. -Note that targeting a particular level of C# does not mean that all features are available. Features are limited based on the framework targeted as well. For example, the engine currently targets .NET 2.0, which means that `System.Linq` extensions cannot be used in the code. +Note that targeting a particular level of C# does not mean that all features are available. Features are limited based +on the framework targeted as well. For example, the engine currently targets .NET 2.0, which means that `System.Linq` +extensions cannot be used in the code. ### Layout @@ -96,7 +120,8 @@ public string SomeProperty #### Spaces -Method declarations and method calls should not have spaces between the method name and the parenthesis, nor within the parenthesis. Put a space after a comma between parameters. +Method declarations and method calls should not have spaces between the method name and the parenthesis, nor within the +parenthesis. Put a space after a comma between parameters. ```csharp public void SomeMethod(int x, int y) @@ -114,7 +139,8 @@ for (int i = 1; i < 10; i++) } ``` -There should be no spaces in expression parenthesis, type casts, generics or array brackets, but there should be a space before and after binary operators. +There should be no spaces in expression parenthesis, type casts, generics or array brackets, but there should be a space +before and after binary operators. ```csharp int x = a * (b + c); @@ -125,7 +151,8 @@ var y = (double)list[0]; #### Indentation -Use four consecutive spaces per level of indent. Don't use tabs - except where the IDE can be set to convert tabs to four spaces. In Visual Studio, set the tab size to 4, the indent size to 4 and make sure Insert spaces is selected. +Use four consecutive spaces per level of indent. Don't use tabs - except where the IDE can be set to convert tabs to +four spaces. In Visual Studio, set the tab size to 4, the indent size to 4 and make sure Insert spaces is selected. Indent content of code blocks. @@ -143,7 +170,8 @@ switch (name) Methods and Properties should be separated by one blank line. Private member variables should have no blank lines. -Blocks of related code should have not have any blank lines. Blank lines can be used to visually group sections of code, but there should never be multiple blank lines. +Blocks of related code should have not have any blank lines. Blank lines can be used to visually group sections of code, +but there should never be multiple blank lines. If brackets are not used on a control flow statement with a single line, a blank line should follow. @@ -162,9 +190,12 @@ public static double GetAttribute(XmlNode result, string name, double defaultVal ### Naming -The following table shows our naming standard for various types of names. All names should be clear enough that somebody unfamiliar with the code can learn about the code by reading them, rather than having to understand the code in order to figure out the names. We don't use any form of "Hungarian" notation. +The following table shows our naming standard for various types of names. All names should be clear enough that somebody +unfamiliar with the code can learn about the code by reading them, rather than having to understand the code in order to +figure out the names. We don't use any form of "Hungarian" notation. -For items that may vary by project, the project’s root .editorconfig and solution DotSettings may provide the defaults and diagnostics expected for PRs in that project. +For items that may vary by project, the project’s root .editorconfig and solution DotSettings may provide the defaults +and diagnostics expected for PRs in that project. |Named Item|Naming Standard|Notes| |--- |--- |--- | @@ -180,7 +211,9 @@ For items that may vary by project, the project’s root .editorconfig and solut ### Comments -Use doc comments on all publicly accessible members. Keep the audience in mind. For example, comments on publicly used framework methods or attributes should be written for easy understanding by users, while comments on internal methods should target folks who work on NUnit. +Use doc comments on all publicly accessible members. Keep the audience in mind. For example, comments on publicly used +framework methods or attributes should be written for easy understanding by users, while comments on internal methods +should target folks who work on NUnit. Don't comment what is obvious. @@ -190,11 +223,13 @@ Use TODO comments when needed, but make sure to go back periodically and do what ### File Organization -Normally, have one public type per source file. An exception is made for a simple enumeration, which is used in the interface of the public type and seems to "belong" to it. Example: TestResult and ResultState +Normally, have one public type per source file. An exception is made for a simple enumeration, which is used in the +interface of the public type and seems to "belong" to it. Example: TestResult and ResultState Name the source file after the public type it represents. -The Directory hierarchy and Namespace hierarchy should match. For example, if the root namespace for a project is `NUnit.Framework`, files in the Constraints subdirectory should be in the `NUnit.Framework.Constraints` namespace. +The Directory hierarchy and Namespace hierarchy should match. For example, if the root namespace for a project is +`NUnit.Framework`, files in the Constraints subdirectory should be in the `NUnit.Framework.Constraints` namespace. Wherever possible, classes should be laid out in the following order, @@ -213,7 +248,10 @@ Using statements should be sorted as follows: * All System namespaces * All Other namespaces, including NUnit's -It is permissible, but not required, to place using statements inside the namespace block, in shortened form, for namespaces that are descendants of the namespace itself. Note that the compiler will permit other uses of shortened namespaces within the namespace block, but we prefer to limit ourselves to descendants. Non-descendant namespaces should be listed in full form in the main using block. +It is permissible, but not required, to place using statements inside the namespace block, in shortened form, for +namespaces that are descendants of the namespace itself. Note that the compiler will permit other uses of shortened +namespaces within the namespace block, but we prefer to limit ourselves to descendants. Non-descendant namespaces should +be listed in full form in the main using block. ```csharp using System; @@ -236,7 +274,9 @@ namespace NUnit.Engine.Internal ### Use of the var keyword -The `var` keyword should be used where the type is obvious to someone reading the code, for example when creating a new object. Use the full type whenever the type is not obvious, for example when initializing a variable with the return value of a method. +The `var` keyword should be used where the type is obvious to someone reading the code, for example when creating a new +object. Use the full type whenever the type is not obvious, for example when initializing a variable with the return +value of a method. ```csharp var i = 12; diff --git a/docs/articles/developer-info/Contributions.md b/docs/articles/developer-info/Contributions.md index 57b68bb4b..7fc7cc10f 100644 --- a/docs/articles/developer-info/Contributions.md +++ b/docs/articles/developer-info/Contributions.md @@ -1,14 +1,18 @@ # Contributions -This page contains guidelines to follow when evaluating and accepting contributions in form of source code from other developers. +This page contains guidelines to follow when evaluating and accepting contributions in form of source code from other +developers. ## Shape -All proposed changes to the code should come in the form of GitHub pull requests. Pull requests are built automatically on the build server and they make it easy to track the origin of any change. +All proposed changes to the code should come in the form of GitHub pull requests. Pull requests are built automatically +on the build server and they make it easy to track the origin of any change. ## Quality -When appropriate, pull requests should contain enough unit tests to provide coverage for the changes they introduce. Because pull requests are built automatically on the build server it is important to check that the changes pass all tests. +When appropriate, pull requests should contain enough unit tests to provide coverage for the changes they introduce. +Because pull requests are built automatically on the build server it is important to check that the changes pass all +tests. Ideally pull requests should contain only few commits which address directly the issue or feature. @@ -16,23 +20,30 @@ Ideally pull requests should contain only few commits which address directly the There are several ways a pull request can be integrated into NUnit's repository: -* Pull requests can be merged automatically using GitHub's Web interface. This is an option only if they are clean of useless commits which would only cause confusion and clutter the history for no good reason. Merging pull requests using GitHub Web interface creates a merge commit even when fast-forward would be possible. +* Pull requests can be merged automatically using GitHub's Web interface. This is an option only if they are clean of + useless commits which would only cause confusion and clutter the history for no good reason. Merging pull requests + using GitHub Web interface creates a merge commit even when fast-forward would be possible. -* Pull requests can be merged manually once they've been checked out locally. Usually this would result in a fast-forward commit if no other changes appeared in the branch where the pull request is being integrated. In other cases you may still have the option to rebase the changes rather than merging. Although a linear history is nice, it's probably even better to force a merge instead, because it records more clearly where those changes came from and also because it automatically closes the pull request (although there may be GitHub hooks to close the pull request, perhaps mentioning its # in the commit message, which I'm not aware of). +* Pull requests can be merged manually once they've been checked out locally. Usually this would result in a + fast-forward commit if no other changes appeared in the branch where the pull request is being integrated. In other + cases you may still have the option to rebase the changes rather than merging. Although a linear history is nice, it's + probably even better to force a merge instead, because it records more clearly where those changes came from and also + because it automatically closes the pull request (although there may be GitHub hooks to close the pull request, + perhaps mentioning its # in the commit message, which I'm not aware of). -Usually it is preferable to use GitHub's automatic merge, and if the pull request does not comply with the few commits rule ask the contributor to sanitize it before doing it yourself. +Usually it is preferable to use GitHub's automatic merge, and if the pull request does not comply with the few commits +rule ask the contributor to sanitize it before doing it yourself. -Avoid committing contributions by repeating the changes in the pull request manually, because this loses track of the origin of changes. +Avoid committing contributions by repeating the changes in the pull request manually, because this loses track of the +origin of changes. ## Special reviews -Anyone submitting a PR can ask for extra review or review by a -particular person. Just say so in the PR indicating what needs special -review. If you want someone particular to review it, use @ notation. +Anyone submitting a PR can ask for extra review or review by a particular person. Just say so in the PR indicating what +needs special review. If you want someone particular to review it, use @ notation. -By default, any PR is eligible to merge after it is reviewed as OK. If -anyone wants to create a PR early to get feedback on the code, then -he should say so right at the top of the PR. +By default, any PR is eligible to merge after it is reviewed as OK. If anyone wants to create a PR early to get feedback +on the code, then he should say so right at the top of the PR. ## Cleaning up @@ -40,8 +51,11 @@ After a pull request has been integrated remember to close associated issues, wh If a pull request has been integrated manually remember to close the pull request afterwards. -The branch of a pull request, in case it belongs to the NUnit's repository might be deleted as well. GitHub provides the option to do so in the Web user interface. Be careful before deleting a branch that the author may have intended the branch to be long-lived. +The branch of a pull request, in case it belongs to the NUnit's repository might be deleted as well. GitHub provides the +option to do so in the Web user interface. Be careful before deleting a branch that the author may have intended the +branch to be long-lived. ## Notes -For contributions from within the team, using branches on the NUnit repository rather than clones, don't forget to delete the branches once merged unless they need to hang around for long-running work +For contributions from within the team, using branches on the NUnit repository rather than clones, don't forget to +delete the branches once merged unless they need to hang around for long-running work diff --git a/docs/articles/developer-info/Issue-Tracking.md b/docs/articles/developer-info/Issue-Tracking.md index c0c1e8b54..ce8cf21a1 100644 --- a/docs/articles/developer-info/Issue-Tracking.md +++ b/docs/articles/developer-info/Issue-Tracking.md @@ -1,67 +1,99 @@ # Issue Tracking -We use the GitHub issue tracker to keep track of our ongoing work. We supplement GitHub's native issue handling by using [ZenHub](https://www.zenhub.com/), which provides a number of additional features. +We use the GitHub issue tracker to keep track of our ongoing work. We supplement GitHub's native issue handling by using +[ZenHub](https://www.zenhub.com/), which provides a number of additional features. ## Workflow -We use a [ZenHub](https://www.zenhub.com/) Board with a standard set of pipelines to track the flow of work in each repo. Our standard set of pipeline columns are slightly different from the ZenHub default: +We use a [ZenHub](https://www.zenhub.com/) Board with a standard set of pipelines to track the flow of work in each +repo. Our standard set of pipeline columns are slightly different from the ZenHub default: -* **New Issues** All issues start as new. We like to review them as quickly as possible. Some issues can be immediately closed while others need to be categorized for further work. We usually assign at least an _is_ and a _priority_ label (see below) to every issue and then move it to either the **Discussion** or the **Backlog** column. +* **New Issues** All issues start as new. We like to review them as quickly as possible. Some issues can be immediately + closed while others need to be categorized for further work. We usually assign at least an _is_ and a _priority_ label + (see below) to every issue and then move it to either the **Discussion** or the **Backlog** column. -* **Discussion** These are items that require some discussion, either about whether we want to do them or how they should be implemented. Some items here may require confirmation or design as well. +* **Discussion** These are items that require some discussion, either about whether we want to do them or how they + should be implemented. Some items here may require confirmation or design as well. -* **Backlog** This is our product backlog consisting of all the issues we want to get done now or in the future. In the past, we have often put things we didn't really want to do in our Backlog, assigning them a low priority. While this avoids having to say no to the requester, it doesn't do them any real service. Putting an issue into the Backlog should mean that it will eventually make it to a release. +* **Backlog** This is our product backlog consisting of all the issues we want to get done now or in the future. In the + past, we have often put things we didn't really want to do in our Backlog, assigning them a low priority. While this + avoids having to say no to the requester, it doesn't do them any real service. Putting an issue into the Backlog + should mean that it will eventually make it to a release. -* **To Do** These are things we are ready to get working on right now and represent a suggestion to developers as to what to choose to work on next. Most but not all of them will be scheduled for the next milestone. This is a good place to keep issues that are blocking other work, so as to encourage developers to get the issue done. +* **To Do** These are things we are ready to get working on right now and represent a suggestion to developers as to + what to choose to work on next. Most but not all of them will be scheduled for the next milestone. This is a good + place to keep issues that are blocking other work, so as to encourage developers to get the issue done. > [!NOTE] -> Since the number of people actively working on a given project varies, we can't establish a fixed number of items to keep in this column. The project lead should try to keep it to a reasonable size, generally no more than twice the number of active developers. If it seems to be growing too rapidly, some of the issues should be moved to the backlog. +> Since the number of people actively working on a given project varies, we can't establish a fixed number of +> items to keep in this column. The project lead should try to keep it to a reasonable size, generally no more than +> twice the number of active developers. If it seems to be growing too rapidly, some of the issues should be moved to +> the backlog. -* **In Progress** These are issues that somebody is already working on. That person should be shown as assigned to the issue and would normally be the one to move the issue into this column. +* **In Progress** These are issues that somebody is already working on. That person should be shown as assigned to the + issue and would normally be the one to move the issue into this column. -* **Done** When all work is done and the person doing it feels it is ready to be merged, the issue should be moved to this column. It remains there while comments are discussed and small changes are made. If the comments will lead to significant rework, then move the issue back to In Progress. +* **Done** When all work is done and the person doing it feels it is ready to be merged, the issue should be moved to + this column. It remains there while comments are discussed and small changes are made. If the comments will lead to + significant rework, then move the issue back to In Progress. * **Closed** Issues go here automatically when they are closed. ## Issue Assignment -Normally, committers self-assign items they want to work on. Please don't assign something to yourself and then let it sit. As a matter of courtesy, nobody else will start working on something that is assigned to you, so the result is that the work won't get done. +Normally, committers self-assign items they want to work on. Please don't assign something to yourself and then let it +sit. As a matter of courtesy, nobody else will start working on something that is assigned to you, so the result is that +the work won't get done. -GitHub won't let non-committers assign issues to themselves (or anyone) so if a contributor wants to work on an issue, they should post a comment to that effect. One of the committers will make the assignment. In many cases, the assignment will be shared between the contributor and a committer who is providing mentoring for them. +GitHub won't let non-committers assign issues to themselves (or anyone) so if a contributor wants to work on an issue, +they should post a comment to that effect. One of the committers will make the assignment. In many cases, the assignment +will be shared between the contributor and a committer who is providing mentoring for them. -If an issue that is assigned to you then you should do what needs to be done. For example, if it's in the discussion column, then it's up to you to make sure the discussion happens and progresses to a conclusion. If it's marked _confirm_ then you should confirm it. If it's marked _design_ then you should do the design and get it reviewed. And, of course, if it's ready for implementation you should do that! +If an issue that is assigned to you then you should do what needs to be done. For example, if it's in the discussion +column, then it's up to you to make sure the discussion happens and progresses to a conclusion. If it's marked _confirm_ +then you should confirm it. If it's marked _design_ then you should do the design and get it reviewed. And, of course, +if it's ready for implementation you should do that! ## Issue Labels -We try to use a standard set of labels across all the NUnit repositories. In some cases, an individual project may not yet have been converted to use these labels, but we expect to do so soon. +We try to use a standard set of labels across all the NUnit repositories. In some cases, an individual project may not +yet have been converted to use these labels, but we expect to do so soon. -That said, don't stress about whether something is a bug or an enhancement, normal versus low priority, etc. Just pick one. If things change later, the label can be changed as well. This is only intended to help us organize a relatively large number of issues, not to give us extra work. +That said, don't stress about whether something is a bug or an enhancement, normal versus low priority, etc. Just pick +one. If things change later, the label can be changed as well. This is only intended to help us organize a relatively +large number of issues, not to give us extra work. ### What it is -Labels starting with **is:** indicate the nature of the issue. Only one should be used, based on the judgment of the committer who assigns the label. If there is no **is:** label, then we presumably don't know what the item is and should not be working on it! +Labels starting with **is:** indicate the nature of the issue. Only one should be used, based on the judgment of the +committer who assigns the label. If there is no **is:** label, then we presumably don't know what the item is and should +not be working on it! * **is:bug** Something that isn't working as designed. * **is:docs** Solely pertaining to the documentation or sample code. * **is:enhancement** An addition or improvement to an existing feature. * **is:feature** An entirely new feature. -* **is:idea** An idea about something we might do. We discuss these until they are either dropped or turned into a feature or enhancement we can work on. +* **is:idea** An idea about something we might do. We discuss these until they are either dropped or turned into a + feature or enhancement we can work on. * **is:question** Just a question - we discourage these as issues but they do happen. * **is:build** Something to do with how we build the software, scripts, etc. * **is:refactor** What it says: refactoring that is needed. ### Priority -Labels starting with **pri:** indicate the priority of an issue. Pick just one, please. Priority may, of course, change over time, as items become more or less important to us. If no priority is assigned, we shouldn't be working on it. +Labels starting with **pri:** indicate the priority of an issue. Pick just one, please. Priority may, of course, change +over time, as items become more or less important to us. If no priority is assigned, we shouldn't be working on it. -* **pri:critical** Should only apply to bugs, which need to be fixed immediately, dropping everything else. At times, we will even speed up the release cycle due to a critical bug. +* **pri:critical** Should only apply to bugs, which need to be fixed immediately, dropping everything else. At times, we + will even speed up the release cycle due to a critical bug. * **pri:high** High priority - implement as soon as possible. * **pri:normal** Standard priority - implement when we can. * **pri:low** Low priority - implement later or not at all. ### PRs and issues that need attention -The goal with these is to keep team members from having to do tedious re-scanning to figure out the state of each long-lived PR or issue as well as increasing awareness. +The goal with these is to keep team members from having to do tedious re-scanning to figure out the state of each +long-lived PR or issue as well as increasing awareness. * **awaiting:contributor**: Blocked until the contributor responds to the team's request for changes. * **awaiting:team**: Blocked until a team member responds to a question or problem. @@ -70,28 +102,47 @@ The goal with these is to keep team members from having to do tedious re-scannin ### Close Reason -Labels starting with **closed:** indicate the status of the bug at closing and should only appear on closed bugs. Please remember to apply one of these when closing a bug as it makes it easier to review the list of closed bugs without opening each one to see what the disposition was. +Labels starting with **closed:** indicate the status of the bug at closing and should only appear on closed bugs. Please +remember to apply one of these when closing a bug as it makes it easier to review the list of closed bugs without +opening each one to see what the disposition was. * **closed:done** The work called for is done, i.e. the bug is fixed or the feature/enhancement is implemented. * **closed:duplicate** The issue is a duplicate of one that we are working. A comment should indicate the issue number. -* **closed:notabug** The issue (generally a bug) is not valid or the feature already exists. There should be an explanatory comment. -* **closed:norepro** While the issue (generally a bug) may exist on the user's system, we have tried and are unable to reproduce it. If somebody later figures out a repro, the issue can be reopened. -* **closed:wontfix** The issue is possibly valid but we don't intend to implement it. It may be out of scope for the project or inconsistent with the values and priorities of the project. There should be an explanatory comment. +* **closed:notabug** The issue (generally a bug) is not valid or the feature already exists. There should be an + explanatory comment. +* **closed:norepro** While the issue (generally a bug) may exist on the user's system, we have tried and are unable to + reproduce it. If somebody later figures out a repro, the issue can be reopened. +* **closed:wontfix** The issue is possibly valid but we don't intend to implement it. It may be out of scope for the + project or inconsistent with the values and priorities of the project. There should be an explanatory comment. ### Other Labels -* **confirm** Somebody should verify that the issue actually exists and then remove the label. In some cases, a bug may have been reported against an older version of NUnit and needs to be checked out using the current code. -* **blocked** The issue cannot be worked on until something else happens, external to the project. There should be a comment on the issue indicating what that something is. -* **design** Some design decisions need to be made before this can really be worked on. Sometimes this label may be applied before anything happens and other times the work may have started but reached a point where design decisions need to be made involving others in the team. -* **up-for-grabs** Indicates a backlog issue ready for implementation where we would love for the wider community to jump in and be assigned! Whoever adds this label should couple it with a comment suggesting what code to look at and a general approach to working the issue. +* **confirm** Somebody should verify that the issue actually exists and then remove the label. In some cases, a bug may + have been reported against an older version of NUnit and needs to be checked out using the current code. +* **blocked** The issue cannot be worked on until something else happens, external to the project. There should be a + comment on the issue indicating what that something is. +* **design** Some design decisions need to be made before this can really be worked on. Sometimes this label may be + applied before anything happens and other times the work may have started but reached a point where design decisions + need to be made involving others in the team. +* **up-for-grabs** Indicates a backlog issue ready for implementation where we would love for the wider community to + jump in and be assigned! Whoever adds this label should couple it with a comment suggesting what code to look at and a + general approach to working the issue. * **easyfix** Indicates an issue that is expected to take no more than a few nights' work. ## Epics -Where appropriate, we make use of the [ZenHub](https://www.zenhub.com/) **Epic** feature to create issues that include a number of sub-issues. For example, when we split the original NUnit repository into separate framework and engine repositories, we created an epic that included a number of separate issues that had to be completed in order to accomplish the split smoothly. +Where appropriate, we make use of the [ZenHub](https://www.zenhub.com/) **Epic** feature to create issues that include a +number of sub-issues. For example, when we split the original NUnit repository into separate framework and engine +repositories, we created an epic that included a number of separate issues that had to be completed in order to +accomplish the split smoothly. ## Milestones -We use GitHub Milestones to represent future releases. Generally milestones are created by the project or team leader, who also decides what issues to place into the milestone. Our practice is to only schedule a limited number of key features in advance for each milestone, rather than trying to "fill" the milestone with the amount of work we think can be completed. Other work is only added to the next milestone after it has been completed. +We use GitHub Milestones to represent future releases. Generally milestones are created by the project or team leader, +who also decides what issues to place into the milestone. Our practice is to only schedule a limited number of key +features in advance for each milestone, rather than trying to "fill" the milestone with the amount of work we think can +be completed. Other work is only added to the next milestone after it has been completed. -We do it this way because the amount of time developers have to spend on our projects can vary considerably over the course of time. We never know how much work will be done in a given period. Since we can't predict both the timing and the content of each release, we have chosen to hold the time constant and vary the content. +We do it this way because the amount of time developers have to spend on our projects can vary considerably over the +course of time. We never know how much work will be done in a given period. Since we can't predict both the timing and +the content of each release, we have chosen to hold the time constant and vary the content. diff --git a/docs/articles/developer-info/Notes-Toward-NUnit-4.0.md b/docs/articles/developer-info/Notes-Toward-NUnit-4.0.md index 63c18f525..1ddc681de 100644 --- a/docs/articles/developer-info/Notes-Toward-NUnit-4.0.md +++ b/docs/articles/developer-info/Notes-Toward-NUnit-4.0.md @@ -6,7 +6,9 @@ Also see [Towards NUnit 4](xref:towardsnunit4) for more details on the changes. ## Extensions -With the release of nunit3-console 4.0, we intend to stop distributing the **teamcity-event-listener** bundled with the console as a standard extension. We will continue to support the `--teamcity` option in the console runner when the extension is installed separately by the user. +With the release of nunit3-console 4.0, we intend to stop distributing the **teamcity-event-listener** bundled with the +console as a standard extension. We will continue to support the `--teamcity` option in the console runner when the +extension is installed separately by the user. ## API possibilities diff --git a/docs/articles/developer-info/Packaging-Extensions.md b/docs/articles/developer-info/Packaging-Extensions.md index cae5967cf..0a07ec292 100644 --- a/docs/articles/developer-info/Packaging-Extensions.md +++ b/docs/articles/developer-info/Packaging-Extensions.md @@ -8,7 +8,10 @@ The NUnit Console/Engine currently ships with the following extensions, * NUnit.Extension.NUnitV2Driver * NUnit.Extension.TeamCityEventListener -All but the TeamCityEventListener are built and shipped by the NUnit team. These extensions must be built and released before building and releasing the Console/Engine, but only if they are changed and a release is planned. For the 3.5 release, all extensions will be built and released with the console. Future releases of each extension will be on an as-needed basis and the version numbers of the extensions and the console/engine will diverge over time. +All but the TeamCityEventListener are built and shipped by the NUnit team. These extensions must be built and released +before building and releasing the Console/Engine, but only if they are changed and a release is planned. For the 3.5 +release, all extensions will be built and released with the console. Future releases of each extension will be on an +as-needed basis and the version numbers of the extensions and the console/engine will diverge over time. ## Create a Release Branch @@ -16,43 +19,53 @@ All work on releases should be done on a branch. 1. Fetch and pull latest from master 2. Create a branch in the form release-3.5 -3. As you make the changes below, push the branch to GitHub and create a Pull Request to allow other team members to review your changes. +3. As you make the changes below, push the branch to GitHub and create a Pull Request to allow other team members to + review your changes. 4. **Do not merge this branch/PR**, we will create a separate PR to merge the changes back into master. ## Make Sure it Works 1. Close all instances of Visual Studio or other IDE to ensure that no changes are left unsaved. -2. Do a clean build and run all the tests on Windows. You may use the command below or three separate commands if preferred. If you encounter errors at any stage, you're not actually ready to release! +2. Do a clean build and run all the tests on Windows. You may use the command below or three separate commands if + preferred. If you encounter errors at any stage, you're not actually ready to release! - `build.cmd -Target=Clean` - `build.cmd -Target=Test` + `build.cmd -Target=Clean` `build.cmd -Target=Test` -3. Repeat the build on a Linux system, if available. If this is not possible, be sure to scrutinize the results from the Travis CI build carefully. On Linux, you may use the command +3. Repeat the build on a Linux system, if available. If this is not possible, be sure to scrutinize the results from the + Travis CI build carefully. On Linux, you may use the command `./build -Target=Test` -4. Make sure that the most recent commits of master passed all tests in the CI builds. Check the builds on both Travis and AppVeyor. +4. Make sure that the most recent commits of master passed all tests in the CI builds. Check the builds on both Travis + and AppVeyor. ## Review Milestone Status -1. Check the milestone for the current release to see that there are no open issues. Any issues that are not going to be in this release should be moved to a future milestone. This may be the time to create the next milestone. +1. Check the milestone for the current release to see that there are no open issues. Any issues that are not going to be + in this release should be moved to a future milestone. This may be the time to create the next milestone. -2. Make sure that completed issues are marked with the appropriate 'closed' label depending on disposition. The release notes will end up reflecting issues marked closed:done. +2. Make sure that completed issues are marked with the appropriate 'closed' label depending on disposition. The release + notes will end up reflecting issues marked closed:done. -3. Check all future open milestones for completed issues. Anything that is completed will be included in this release so change its milestone to the current release. +3. Check all future open milestones for completed issues. Anything that is completed will be included in this release so + change its milestone to the current release. ## Check Versioning -`AssemblyVersion` and `AssemblyFileVersion` are set in `src\extension\Properties\AssemblyInfo.cs` and should match the version in `build.cake`. These values are normally incremented after a release, but should be checked. +`AssemblyVersion` and `AssemblyFileVersion` are set in `src\extension\Properties\AssemblyInfo.cs` and should match the +version in `build.cake`. These values are normally incremented after a release, but should be checked. ## Update Copyright Year -The copyright year in all the source files is only updated as they are changed, but the copyright in the `[assembly: AssemblyCopyright("...")]` should be updated to the year of the release. +The copyright year in all the source files is only updated as they are changed, but the copyright in the `[assembly: +AssemblyCopyright("...")]` should be updated to the year of the release. -If necessary, update the year in the general copyright notice `LICENSE.txt`. The `.nuspec` files in solution root contains a copyright line, which should also be updated. +If necessary, update the year in the general copyright notice `LICENSE.txt`. The `.nuspec` files in solution root +contains a copyright line, which should also be updated. -Notices at the top of each source code file are only updated when copyrightable changes are made to the file, not at the time of release. +Notices at the top of each source code file are only updated when copyrightable changes are made to the file, not at the +time of release. ## Push All Changes @@ -64,13 +77,13 @@ Make sure the release branch and any changes are pushed to GitHub, reviewed in a `erase package\*` - This is not absolutely required, but will be helpful if you have other release packages present - in the directory. + This is not absolutely required, but will be helpful if you have other release packages present in the directory. -2. You should be working on the release branch. Do a pull to make sure you have everything up to date. If changes of any significance were merged, you should test again before creating the release. +2. You should be working on the release branch. Do a pull to make sure you have everything up to date. If changes of any + significance were merged, you should test again before creating the release. -3. Ensure that the release build is up to date. If you have any doubt whether the latest code changes - have actually been built, do a clean build. If the build is up to date you may skip this step. +3. Ensure that the release build is up to date. If you have any doubt whether the latest code changes have actually been + built, do a clean build. If the build is up to date you may skip this step. `build -Target Build` @@ -84,13 +97,17 @@ Make sure the release branch and any changes are pushed to GitHub, reviewed in a ## Testing the Release -Open the NuGet package from the `package` sub-directory using [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer). Inspect the package metadata for errors and check that the tools folder contains the extension dll and any dependent assemblies. +Open the NuGet package from the `package` sub-directory using [NuGet Package +Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer). Inspect the package metadata for errors and +check that the tools folder contains the extension dll and any dependent assemblies. -Next install the extension into a project with the `NUnit.ConsoleRunner` package and make sure you can run tests. If you are releasing the V2 driver, run NUnit 2 tests. If you are releasing the V2 Result Writer, write out V2 results. +Next install the extension into a project with the `NUnit.ConsoleRunner` package and make sure you can run tests. If you +are releasing the V2 driver, run NUnit 2 tests. If you are releasing the V2 Result Writer, write out V2 results. ## Archiving the Release -Packages are archived on nunit.org in the downloads directory. Create a new sub-folder under `downloads/extensions/v3/EXTENSION_NAME` for the release. Upload all the package files into that directory. +Packages are archived on nunit.org in the downloads directory. Create a new sub-folder under +`downloads/extensions/v3/EXTENSION_NAME` for the release. Upload all the package files into that directory. ## Publishing the Release @@ -102,7 +119,8 @@ Packages are archived on nunit.org in the downloads directory. Create a new sub- 3. Enter a tag to be used for the release in the format v3.x.y **Select your release branch** as the target for the tag. -4. Enter a title for the release, like NUnit Project Loader Extension 3.5 release. If you type 'N' you'll get some hints. +4. Enter a title for the release, like NUnit Project Loader Extension 3.5 release. If you type 'N' you'll get some + hints. 5. Add a description of the release. It will be easier if you have prepared this in advance and can just paste it in. @@ -126,7 +144,8 @@ Packages are archived on nunit.org in the downloads directory. Create a new sub- 1. Close your release Pull Request 2. Create a new branch off of your release branch -3. Increment the version in the various locations. For example 3.5 -> 3.6. See the Update Package Versions section above. +3. Increment the version in the various locations. For example 3.5 -> 3.6. See the Update Package Versions section + above. 4. Push your changes to GitHub 5. Create a pull request from your branch making sure it is based off master diff --git a/docs/articles/developer-info/Packaging-the-Console-and-Engine.md b/docs/articles/developer-info/Packaging-the-Console-and-Engine.md index e6466e01c..c8213d0e4 100644 --- a/docs/articles/developer-info/Packaging-the-Console-and-Engine.md +++ b/docs/articles/developer-info/Packaging-the-Console-and-Engine.md @@ -1,13 +1,17 @@ # Packaging the Console and Engine > [!NOTE] -> **TODO:** This documentation was copied from the original packaging info and needs to be updated for packaging just the Console and Engine. +> **TODO:** This documentation was copied from the original packaging info and needs to be updated for packaging +> just the Console and Engine. -This note describes how to create release packages for the NUnit console runner and test engine. Currently, all the builds and packaging must be done on a single Windows machine. This is likely to change in the future as we add more platforms. +This note describes how to create release packages for the NUnit console runner and test engine. Currently, all the +builds and packaging must be done on a single Windows machine. This is likely to change in the future as we add more +platforms. ## Software Prerequisites -Various software combinations and environments may be used to build the NUnit 3 console runner and engine. Our standard environment is Visual Studio 2017 15.6+ Community Edition. +Various software combinations and environments may be used to build the NUnit 3 console runner and engine. Our standard +environment is Visual Studio 2017 15.6+ Community Edition. ## Preparing for Release @@ -21,28 +25,35 @@ Various software combinations and environments may be used to build the NUnit 3 1. Close all instances of Visual Studio or other IDE to ensure that no changes are left unsaved. -2. Do a clean build and run all the tests on Windows. You may use the command below or three separate commands if preferred. If you encounter errors at any stage, you're not actually ready to release! +2. Do a clean build and run all the tests on Windows. You may use the command below or three separate commands if + preferred. If you encounter errors at any stage, you're not actually ready to release! - `build.cmd -Target=Clean` - `build.cmd -Target=Test` + `build.cmd -Target=Clean` `build.cmd -Target=Test` -3. Repeat the build on a Linux system, if available. If this is not possible, be sure to scrutinize the results from the Travis CI build carefully. On Linux, you may use the command +3. Repeat the build on a Linux system, if available. If this is not possible, be sure to scrutinize the results from the + Travis CI build carefully. On Linux, you may use the command `./build -Target=Test` -4. Make sure that the most recent commits of master passed all tests in the CI builds. Check the builds on both Travis and AppVeyor. Check on TeamCity once we get that build working again. +4. Make sure that the most recent commits of master passed all tests in the CI builds. Check the builds on both Travis + and AppVeyor. Check on TeamCity once we get that build working again. ### Review Milestone Status -1. Check the milestone for the current release to see that there are no open issues. Any issues that are not going to be in this release should be moved to a future milestone. This may be the time to create the next milestone. +1. Check the milestone for the current release to see that there are no open issues. Any issues that are not going to be + in this release should be moved to a future milestone. This may be the time to create the next milestone. -2. Make sure that completed issues are marked with the appropriate 'closed' label depending on disposition. The release notes will end up reflecting issues marked closed:done. +2. Make sure that completed issues are marked with the appropriate 'closed' label depending on disposition. The release + notes will end up reflecting issues marked closed:done. -3. Check all future open milestones for completed issues. Anything that is completed will be included in this release so change its milestone to the current release. +3. Check all future open milestones for completed issues. Anything that is completed will be included in this release so + change its milestone to the current release. ### Check Assembly Versioning -AssemblyVersion and AssemblyFileVersion are set separately for the framework, engine, engine api and console runner. Each is kept in a separate file and they may be updated separately. Using the 3.4.1 release as an example, version information would be set as follows: +AssemblyVersion and AssemblyFileVersion are set separately for the framework, engine, engine api and console runner. +Each is kept in a separate file and they may be updated separately. Using the 3.4.1 release as an example, version +information would be set as follows: Component | File to Update | AssemblyVersion | AssemblyFileVersion --------------------- | ------------------- | --------------- | ------------------- @@ -52,56 +63,85 @@ AssemblyVersion and AssemblyFileVersion are set separately for the framework, en #### Notes -1. The Engine API AssemblyVersion is fixed and will not be changed unless it becomes necessary to modify the API in a non-additive manner. +1. The Engine API AssemblyVersion is fixed and will not be changed unless it becomes necessary to modify the API in a + non-additive manner. -2. These values will normally already be correct for the release, since they should have been set immediately following the prior release. +2. These values will normally already be correct for the release, since they should have been set immediately following + the prior release. ### Update Copyright Year -The copyright year in all the source files is only updated as they are changed, but the copyright in the `[assembly: AssemblyCopyright("...")]` and the copyright text displayed by `nunit3-console` and `nunitlite` should be updated to the year of the release. Search for `AssemblyCopyright` in the solution and update it where needed, then check `Program.cs` in `nunit3-console` for default values used when no attribute is found. +The copyright year in all the source files is only updated as they are changed, but the copyright in the `[assembly: +AssemblyCopyright("...")]` and the copyright text displayed by `nunit3-console` and `nunitlite` should be updated to the +year of the release. Search for `AssemblyCopyright` in the solution and update it where needed, then check `Program.cs` +in `nunit3-console` for default values used when no attribute is found. -If necessary, update the year in the general copyright notice LICENSE.txt. Note that these copyright notices refer to each of the packages in their entirety. Each of the `.nuspec` files in the `nuget` subdirectory contains a copyright line, which should also be updated. +If necessary, update the year in the general copyright notice LICENSE.txt. Note that these copyright notices refer to +each of the packages in their entirety. Each of the `.nuspec` files in the `nuget` subdirectory contains a copyright +line, which should also be updated. -Notices at the top of each source code file are only updated when copyrightable changes are made to the file, not at the time of release. +Notices at the top of each source code file are only updated when copyrightable changes are made to the file, not at the +time of release. ### Update Package Versions -The package version is updated in the `build.cake` file. The following lines appear near the beginning of the file. Update the versions and modifiers if necessary. Normally, they will already have been set correctly. +The package version is updated in the `build.cake` file. The following lines appear near the beginning of the file. +Update the versions and modifiers if necessary. Normally, they will already have been set correctly. ```csharp var version="3.4.1"; var modifier="" ``` -The version variables are three-part version numbers that follow the basic principles of [semantic versioning]. Since we publish a number of nuget packages, we use the nuget implementation of semantic versioning. +The version variables are three-part version numbers that follow the basic principles of [semantic versioning]. Since we +publish a number of nuget packages, we use the nuget implementation of semantic versioning. -For NUnit, the major version is updated only rarely. Normal releases will update the minor version and set the third component to zero. The third component is incremented when "hot fixes" are made to a production release or for builds created for a special purpose. +For NUnit, the major version is updated only rarely. Normal releases will update the minor version and set the third +component to zero. The third component is incremented when "hot fixes" are made to a production release or for builds +created for a special purpose. -For pre-release versions, a non-empty modifier is specified. This is a suffix added to the version. Our standard suffixes are currently `-alpha-n`, `-beta-n` and `-rc-n` The build script adds an additional suffix of -dbg to any packages created using a Debug build. +For pre-release versions, a non-empty modifier is specified. This is a suffix added to the version. Our standard +suffixes are currently `-alpha-n`, `-beta-n` and `-rc-n` The build script adds an additional suffix of -dbg to any +packages created using a Debug build. > [!NOTE] -> The first alpha, beta or rc release may omit the `-n`. In that case, any following alpha, beta or rc should use `-2`. +> The first alpha, beta or rc release may omit the `-n`. In that case, any following alpha, beta or rc should +> use `-2`. ### Update CHANGES File -The CHANGES.txt file in the project root contains all relevant changes for each release. It contains the same information as the release notes in the project documentation, in text format. Because the CHANGES file includes the **date** of the release, you must know when the release is coming out in order to edit it. Otherwise, it will be necessary to make a final change to the file at the point of making the release. +The CHANGES.txt file in the project root contains all relevant changes for each release. It contains the same +information as the release notes in the project documentation, in text format. Because the CHANGES file includes the +**date** of the release, you must know when the release is coming out in order to edit it. Otherwise, it will be +necessary to make a final change to the file at the point of making the release. -Create new sections in the CHANGES file to match those for prior releases. To ensure that all changes are included, review closed issues in the current and any future milestones. If an issue for a previous milestone was actually completed and closed, move it to the current milestone, since that's where it is being released. Include all issues resolved as closed:done in the issues section of the file. Significant feature additions and changes should be documented, even if they are also listed with issue numbers. Reviewing commits and merged pull requests may help in catching additional changes. +Create new sections in the CHANGES file to match those for prior releases. To ensure that all changes are included, +review closed issues in the current and any future milestones. If an issue for a previous milestone was actually +completed and closed, move it to the current milestone, since that's where it is being released. Include all issues +resolved as closed:done in the issues section of the file. Significant feature additions and changes should be +documented, even if they are also listed with issue numbers. Reviewing commits and merged pull requests may help in +catching additional changes. -You should commit the CHANGES file separately from the version number changes since that commit will be merged back into master while the version changes will not. +You should commit the CHANGES file separately from the version number changes since that commit will be merged back into +master while the version changes will not. ### Update the Documentation -The [Release Notes](xref:frameworkreleasenotes) section of the documentation site should match the content of the CHANGES.txt file except for any format differences. +The [Release Notes](xref:frameworkreleasenotes) section of the documentation site should match the content of the +CHANGES.txt file except for any format differences. > [!NOTE] -> Now that the documentation is being kept in a web site generated by github markdown, it may be possible to use the github markdown text directly in this file for future releases. +> Now that the documentation is being kept in a web site generated by github markdown, it may be possible to use +> the github markdown text directly in this file for future releases. -For any significant changes to how NUnit is used or what it does, the appropriate pages of the documentation should be updated or new pages created. If you do this in advance of the release (which is actually a good idea) you should do it in a way that the new documentation is not visible until the release is actually made. +For any significant changes to how NUnit is used or what it does, the appropriate pages of the documentation should be +updated or new pages created. If you do this in advance of the release (which is actually a good idea) you should do it +in a way that the new documentation is not visible until the release is actually made. ### Push All Changes -If you made any changes to the files in git as part of the preceding steps. Make sure you have pushed them and they have been reviewed in the PR. +If you made any changes to the files in git as part of the preceding steps. Make sure you have pushed them and they have +been reviewed in the PR. ## Creating the Release @@ -109,10 +149,10 @@ If you made any changes to the files in git as part of the preceding steps. Make `erase package\*` - This is not absolutely required, but will be helpful if you have other release packages present - in the directory. + This is not absolutely required, but will be helpful if you have other release packages present in the directory. -2. You should be working on the release branch. Do a pull to make sure you have everything up to date. If changes of any significance were merged, you should test again before creating the release. +2. You should be working on the release branch. Do a pull to make sure you have everything up to date. If changes of any + significance were merged, you should test again before creating the release. 3. Create the packages by running: @@ -129,11 +169,13 @@ If you made any changes to the files in git as part of the preceding steps. Make ## Testing the Release -The degree to which each package needs testing may vary depending on what has been changed. Usually, you should install all the NuGet packages into a test project, verifying that the +The degree to which each package needs testing may vary depending on what has been changed. Usually, you should install +all the NuGet packages into a test project, verifying that the ## Archiving the Release -Packages are archived on nunit.org in the downloads directory. Create a new sub-folder under downloads/nunit/v3 for the release. Upload all the package files into that directory. +Packages are archived on nunit.org in the downloads directory. Create a new sub-folder under downloads/nunit/v3 for the +release. Upload all the package files into that directory. ## Publishing the Release @@ -143,7 +185,9 @@ Packages are archived on nunit.org in the downloads directory. Create a new sub- 2. Select Releases and then click on the "Draft a new release" button. -3. Enter a tag to be used for the release. Currently our tags are simply the version of the release, like 3.0.0-alpha-5. If you start typing with '3' you'll get a list of earlier release tags so you can see the format. **Select your release branch** as the target for the tag. +3. Enter a tag to be used for the release. Currently our tags are simply the version of the release, like 3.0.0-alpha-5. + If you start typing with '3' you'll get a list of earlier release tags so you can see the format. **Select your + release branch** as the target for the tag. 4. Enter a title for the release, like NUnit 3.0 RC release. If you type 'N' you'll get some hints. @@ -151,7 +195,8 @@ Packages are archived on nunit.org in the downloads directory. Create a new sub- 6. If this is an Alpha or Beta release, check the box that indicates a pre-release. -7. Upload the packages you created earlier either directly from the package directory or from their archive location. Note that we upload all the packages, including those that are also published on NuGet. +7. Upload the packages you created earlier either directly from the package directory or from their archive location. + Note that we upload all the packages, including those that are also published on NuGet. 8. Click the "Publish release" button to publish the release on Github. @@ -171,13 +216,15 @@ Packages are archived on nunit.org in the downloads directory. Create a new sub- 1. Close your release Pull Request 2. Create a new branch off of your release branch -3. Increment the version in the various locations from the even release to the SemVer odd dev release number. For example 3.2 -> 3.3. See the Update Package Versions section above. +3. Increment the version in the various locations from the even release to the SemVer odd dev release number. For + example 3.2 -> 3.3. See the Update Package Versions section above. 4. Push your changes to GitHub 5. Create a pull request from your branch making sure it is based off master ### Website -If changes to the website have been accumulated in a branch, now is the time to merge it and upload the pages to the site. +If changes to the website have been accumulated in a branch, now is the time to merge it and upload the pages to the +site. ### Notify Users diff --git a/docs/articles/developer-info/Packaging-the-Framework.md b/docs/articles/developer-info/Packaging-the-Framework.md index 026922f4c..30907d4c2 100644 --- a/docs/articles/developer-info/Packaging-the-Framework.md +++ b/docs/articles/developer-info/Packaging-the-Framework.md @@ -1,10 +1,13 @@ # Packaging the Framework -This note describes how to create release packages for the NUnit Framework. Currently, all the builds and packaging must be done on a single Windows machine. This is likely to change in the future as we add more platforms. +This note describes how to create release packages for the NUnit Framework. Currently, all the builds and packaging must +be done on a single Windows machine. This is likely to change in the future as we add more platforms. ## Software Prerequisites -Various software combinations and environments may be used to build NUnit components. The following software is what we have used and tested for building everything and creating the release packages. We'll add options to the list as we find them. +Various software combinations and environments may be used to build NUnit components. The following software is what we +have used and tested for building everything and creating the release packages. We'll add options to the list as we find +them. 1. Visual Studio 2019 16.8 or newer with the NuGet Package manager. 2. .NET 5.0 SDK @@ -18,30 +21,38 @@ All work on releases should be done on a branch. 1. On master `git checkout master`, Fetch `git fetch -p` and pull latest `git pull` 2. Create a branch to prepare the release `git checkout -b release313` 3. Push the branch to GitHub `git push -u origin release313` -4. As you make the changes below, push the changes to GitHub and create a Pull Request targeting the `release` branch to allow other team members to review your changes. +4. As you make the changes below, push the changes to GitHub and create a Pull Request targeting the `release` branch to + allow other team members to review your changes. 5. The PR can be created in the web or using the GitHub CLI with `gh pr create -a rprouse -B release -t "Release 3.13"` ### Make Sure it Works 1. Close all instances of Visual Studio or other IDE to ensure that no changes are left unsaved. -2. Do a clean build and run all the tests on Windows. You may use the command below or three separate commands if preferred. If you encounter errors at any stage, you're not actually ready to release! +2. Do a clean build and run all the tests on Windows. You may use the command below or three separate commands if + preferred. If you encounter errors at any stage, you're not actually ready to release! ```sh .\build.ps1 --Target Clean .\build.ps1 --Target Test ``` -3. Repeat the build on a Linux system, if available. If this is not possible, be sure to scrutinize the results from the Linux Azure DevOps build carefully. On Linux, you may use the command +3. Repeat the build on a Linux system, if available. If this is not possible, be sure to scrutinize the results from the + Linux Azure DevOps build carefully. On Linux, you may use the command `./build -Target=Test` ### Review Milestone Status -1. Check the milestone for the current release to see that there are no open issues. Any issues that are not going to be in this release should be moved to a future milestone. This may be the time to create the next milestone. -2. Make sure that completed issues are marked with the appropriate 'closed' label depending on disposition. The release notes will end up reflecting issues marked closed:done. -3. Check all future open milestones for completed issues. Anything that is completed will be included in this release so change its milestone to the current release. -4. Review all closed issues without a milestone. Move them to the current milestone if they were fixed in this release, or set their milestone to `Closed without action` for questions and issues that were closed without a fix. You can use the following query to find issues that need to be reviewed: +1. Check the milestone for the current release to see that there are no open issues. Any issues that are not going to be + in this release should be moved to a future milestone. This may be the time to create the next milestone. +2. Make sure that completed issues are marked with the appropriate 'closed' label depending on disposition. The release + notes will end up reflecting issues marked closed:done. +3. Check all future open milestones for completed issues. Anything that is completed will be included in this release so + change its milestone to the current release. +4. Review all closed issues without a milestone. Move them to the current milestone if they were fixed in this release, + or set their milestone to `Closed without action` for questions and issues that were closed without a fix. You can + use the following query to find issues that need to be reviewed: ```cmd is:issue no:milestone is:closed -label:closed:sep -label:closed:notabug -label:is:question -label:closed:wontfix -label:closed:noresponsefromreporter -label:closed:fixedin_newer_version -label:closed_moved_to_discussion -label:closed:duplicate -label:closed:byDesign @@ -49,49 +60,70 @@ All work on releases should be done on a branch. ### Update Copyright Year -The copyright in the `[assembly: AssemblyCopyright("...")]` and the copyright text displayed by `nunitlite` should be updated to the year of the release. Search for `AssemblyCopyright` in the solution and update it where needed, then check `TextUI.cs` in `nunitlite-runner` for default values used when no attribute is found. +The copyright in the `[assembly: AssemblyCopyright("...")]` and the copyright text displayed by `nunitlite` should be +updated to the year of the release. Search for `AssemblyCopyright` in the solution and update it where needed, then +check `TextUI.cs` in `nunitlite-runner` for default values used when no attribute is found. -If necessary, update the year in the general copyright notice LICENSE.txt. Note that these copyright notices refer to each of the packages in their entirety. Each of the `.nuspec` files in the `nuget` subdirectory contains a copyright line, which should also be updated. +If necessary, update the year in the general copyright notice LICENSE.txt. Note that these copyright notices refer to +each of the packages in their entirety. Each of the `.nuspec` files in the `nuget` subdirectory contains a copyright +line, which should also be updated. ### Update CHANGES File -The `CHANGES.md` file in the project root contains all relevant changes for each release. It contains the same information as the release notes in the project documentation, in text format. Because the CHANGES file includes the **date** of the release, you must know when the release is coming out in order to edit it. Otherwise, it will be necessary to make a final change to the file at the point of making the release. +The `CHANGES.md` file in the project root contains all relevant changes for each release. It contains the same +information as the release notes in the project documentation, in text format. Because the CHANGES file includes the +**date** of the release, you must know when the release is coming out in order to edit it. Otherwise, it will be +necessary to make a final change to the file at the point of making the release. -Create new sections in the CHANGES file to match those for prior releases. To ensure that all changes are included, review closed issues in the current and any future milestones. If an issue for a previous milestone was actually completed and closed, move it to the current milestone, since that's where it is being released. Include all issues resolved as closed:done in the issues section of the file. Significant feature additions and changes should be documented, even if they are also listed with issue numbers. Reviewing commits and merged pull requests may help in catching additional changes. +Create new sections in the CHANGES file to match those for prior releases. To ensure that all changes are included, +review closed issues in the current and any future milestones. If an issue for a previous milestone was actually +completed and closed, move it to the current milestone, since that's where it is being released. Include all issues +resolved as closed:done in the issues section of the file. Significant feature additions and changes should be +documented, even if they are also listed with issue numbers. Reviewing commits and merged pull requests may help in +catching additional changes. -To generate the change list in the format required, use the **rprouse/GetChanges** console app from [NUnit.InternalTools](https://github.com/nunit/NUnit.InternalTools) which fetches and prints all issues in the given milestone, e.g. for milestone 4.0: +To generate the change list in the format required, use the **rprouse/GetChanges** console app from +[NUnit.InternalTools](https://github.com/nunit/NUnit.InternalTools) which fetches and prints all issues in the given +milestone, e.g. for milestone 4.0: `dotnet run -o nunit -r nunit -l -m 4.0` -Clone the repo and run it from the solution root. The `-o` and `-r` options specify the owner and repo, respectively. The `-l` option includes all links, including those that are closed. The `-m` option specifies the milestone. If no milestone is specified, the current milestone is used. +Clone the repo and run it from the solution root. The `-o` and `-r` options specify the owner and repo, respectively. +The `-l` option includes all links, including those that are closed. The `-m` option specifies the milestone. If no +milestone is specified, the current milestone is used. *Note: You might need to manually create the IssuePr link file. It will be automated in the future.* ### Update the Documentation -The [Release Notes](xref:frameworkreleasenotes) section of the documentation site should match the content of the `CHANGES.md` file except for any format differences. +The [Release Notes](xref:frameworkreleasenotes) section of the documentation site should match the content of the +`CHANGES.md` file except for any format differences. -For any significant changes to how NUnit is used or what it does, the appropriate pages of the documentation should be updated or new pages created. For new features or changes to features, include the version of NUnit that the feature was implemented in. +For any significant changes to how NUnit is used or what it does, the appropriate pages of the documentation should be +updated or new pages created. For new features or changes to features, include the version of NUnit that the feature was +implemented in. ### Push All Changes -Push all changes to the files in git as part of the preceding steps. Make sure you have pushed them and they have been reviewed in the PR. +Push all changes to the files in git as part of the preceding steps. Make sure you have pushed them and they have been +reviewed in the PR. ## Creating the Release Locally -The release **should not** be built on a developers machine, it should be built by the build servers. The following steps are only for reproducing the steps locally. +The release **should not** be built on a developers machine, it should be built by the build servers. The following +steps are only for reproducing the steps locally. 1. Clear the package directory to avoid confusion: `erase package\*` - This is not absolutely required, but will be helpful if you have other release packages present - in the directory. + This is not absolutely required, but will be helpful if you have other release packages present in the directory. -2. You should be working on the release branch. Do a pull to make sure you have everything up to date. If changes of any significance were merged, you should test again before creating the release. +2. You should be working on the release branch. Do a pull to make sure you have everything up to date. If changes of any + significance were merged, you should test again before creating the release. -3. Ensure that the release build is up to date. If you have any doubt whether the latest code changes - have actually been built, do a clean build. If the build is up to date you may skip this step. +3. Ensure that the release build is up to date. If you have any doubt whether the latest code changes have actually been + built, do a clean build. If the build is up to date you may skip this step. `.\build.ps1 --Target Build` @@ -99,9 +131,9 @@ The release **should not** be built on a developers machine, it should be built `.\build.ps1 ---Target CreateImage` - You do this to ensure that the latest build is used for packaging. If the `images` directory does - not already contain a subdirectory named for this release (package version and suffix) you may skip - this step as a new one will be created automatically. + You do this to ensure that the latest build is used for packaging. If the `images` directory does not already contain + a subdirectory named for this release (package version and suffix) you may skip this step as a new one will be + created automatically. 5. Create the packages by running: @@ -119,10 +151,13 @@ The release **should not** be built on a developers machine, it should be built The degree to which each package needs testing may vary depending on what has been changed. At a minimum, -1. Ensure the [NUnit Framework CI](https://nunit.visualstudio.com/NUnit/_build?definitionId=11) build succeeds on all platforms and that the tests passed. +1. Ensure the [NUnit Framework CI](https://nunit.visualstudio.com/NUnit/_build?definitionId=11) build succeeds on all + platforms and that the tests passed. 2. Download `Package.zip` from the build and extract it locally. -3. Five files should be extracted, `NUnit.{version}.nupkg`, `NUnit.{version}.snupkg`, `NunitLite.{version}.nupkg`, `NunitLite.{version}.snupkg` and `NUnit.Framework-{version}.zip`. -4. In Visual Studio, create a test project and add your local directory as a package source. Install the packages and verify that they apply to the project correctly. +3. Five files should be extracted, `NUnit.{version}.nupkg`, `NUnit.{version}.snupkg`, `NunitLite.{version}.nupkg`, + `NunitLite.{version}.snupkg` and `NUnit.Framework-{version}.zip`. +4. In Visual Studio, create a test project and add your local directory as a package source. Install the packages and + verify that they apply to the project correctly. 5. Run unit tests for platforms or features that have changed in the release. ## Merge the Release PR @@ -131,17 +166,22 @@ Once you have tested the release PR and all checks have passed, merge the PR int ## Publishing the Release -Once the [NUnit Framework CI](https://nunit.visualstudio.com/NUnit/_build?definitionId=11) build for the merge to the release branch finishes, once again download and unzip `Package.zip`. +Once the [NUnit Framework CI](https://nunit.visualstudio.com/NUnit/_build?definitionId=11) build for the merge to the +release branch finishes, once again download and unzip `Package.zip`. ### Github 1. Log onto Github and go to the main NUnit repository at . 2. Select Releases and then click on the "Draft a new release" button. -3. Enter a tag to be used for the release. Currently our tags are simply the version of the release prefixed with a `v`, like `v3.12`. If you start typing with 'v' you'll get a list of earlier release tags so you can see the format. **Select the release branch** as the target for the tag. +3. Enter a tag to be used for the release. Currently our tags are simply the version of the release prefixed with a `v`, + like `v3.12`. If you start typing with 'v' you'll get a list of earlier release tags so you can see the format. + **Select the release branch** as the target for the tag. 4. Enter a title for the release, like NUnit 3.13. If you type 'N' you'll get some hints. -5. Use the preamble from the release notes for the description and add a link to the full release notes on the docs website. +5. Use the preamble from the release notes for the description and add a link to the full release notes on the docs + website. 6. If this is an Alpha or Beta release, check the box that indicates a pre-release. -7. Upload the five files from `Package.zip` that you downloaded. Note that we upload all the packages, including those that are also published on NuGet. +7. Upload the five files from `Package.zip` that you downloaded. Note that we upload all the packages, including those + that are also published on NuGet. 8. Click the "Publish release" button to publish the release on Github. ### NuGet @@ -170,7 +210,8 @@ The milestone representing this release should be closed at this time. ### Create a Merge Branch -On your local machine, change to the release branch, fetch latest, pull, then create a branch to merge the release changes back to master. +On your local machine, change to the release branch, fetch latest, pull, then create a branch to merge the release +changes back to master. ```sh git checkout release @@ -181,29 +222,38 @@ git checkout release313-merge ### Update Assembly Versioning -`AssemblyVersion` and `AssemblyFileVersion` are set for all projects in the framework in one file. Update the version in `FrameworkVersion.cs` to the next planned release number. +`AssemblyVersion` and `AssemblyFileVersion` are set for all projects in the framework in one file. Update the version in +`FrameworkVersion.cs` to the next planned release number. ### Update Package Versions -The package version is updated in the `build.cake` file. The following lines appear near the beginning of the file. Update the versions and modifiers as necessary. +The package version is updated in the `build.cake` file. The following lines appear near the beginning of the file. +Update the versions and modifiers as necessary. ```csharp var version="3.14.0"; var modifier="" ``` -The version variables are three-part version numbers that follow the basic principles of [semantic versioning]. Since we publish a number of NuGet packages, we use the NuGet implementation of semantic versioning. +The version variables are three-part version numbers that follow the basic principles of [semantic versioning]. Since we +publish a number of NuGet packages, we use the NuGet implementation of semantic versioning. -For NUnit, the major version is updated only rarely. Normal releases will update the minor version and set the third component to zero. The third component is incremented when "hot fixes" are made to a production release or for builds created for a special purpose. +For NUnit, the major version is updated only rarely. Normal releases will update the minor version and set the third +component to zero. The third component is incremented when "hot fixes" are made to a production release or for builds +created for a special purpose. -For pre-release versions, a non-empty modifier is specified. This is a suffix added to the version. Our standard suffixes are currently `-alpha-n`, `-beta-n` and `-rc-n` The build script adds an additional suffix of -dbg to any packages created using a Debug build. +For pre-release versions, a non-empty modifier is specified. This is a suffix added to the version. Our standard +suffixes are currently `-alpha-n`, `-beta-n` and `-rc-n` The build script adds an additional suffix of -dbg to any +packages created using a Debug build. > [!NOTE] -> The first alpha, beta or rc release may omit the `-n`. In that case, any following alpha, beta or rc should use `-2`. +> The first alpha, beta or rc release may omit the `-n`. In that case, any following alpha, beta or rc should +> use `-2`. ### Create a PR to Merge to Master -Push your local changes to GitHub and create a PR to merge the changes back to master. You can do this in the web or using the GitHub CLI. +Push your local changes to GitHub and create a PR to merge the changes back to master. You can do this in the web or +using the GitHub CLI. ```sh gh pr create -a rprouse -B master -t "Merge 3.13 release changes to master" diff --git a/docs/articles/developer-info/Packaging-the-Installer.md b/docs/articles/developer-info/Packaging-the-Installer.md index 041423d2d..b3ecd166d 100644 --- a/docs/articles/developer-info/Packaging-the-Installer.md +++ b/docs/articles/developer-info/Packaging-the-Installer.md @@ -1,11 +1,13 @@ # Packaging the Installer -Before packaging the installer, you must first package and release the Console and Engine. See [Packaging the Console and Engine](Packaging-the-Console-and-Engine.md) +Before packaging the installer, you must first package and release the Console and Engine. See [Packaging the Console +and Engine](Packaging-the-Console-and-Engine.md) ## Prepare the Release 1. Get latest from master -1. Update CHANGES.TXT. Set the date of the release, and list any packages which have been upgraded since the last release. +1. Update CHANGES.TXT. Set the date of the release, and list any packages which have been upgraded since the last + release. 1. Check the `version` and `displayVersion` in `build.cake`. They should have been updated at the last release. 1. Package the release, `.\build.ps1` or `.\build.cmd` 1. Check the `distribution` directory for `NUnit.{VERSION}.msi` and `NUnit.{VERSION}.zip` @@ -31,7 +33,8 @@ Before packaging the installer, you must first package and release the Console a ## Archiving the Release -Packages are archived on nunit.org in the downloads directory. Add the MSI and ZIP to the existing downloads/nunit/v3 for the Console/Engine release. +Packages are archived on nunit.org in the downloads directory. Add the MSI and ZIP to the existing downloads/nunit/v3 +for the Console/Engine release. ## Publishing the Release @@ -54,4 +57,7 @@ Packages are archived on nunit.org in the downloads directory. Add the MSI and Z 5. Close the milestone if one exists > [!NOTE] -> The release branch in this project is not like the release branches in other projects, we don't save it. If we need to go back and do hotfixes, we will branch off the tag that was created for the release. We do this because there are usually no changes required to this repository for a release except incrementing the version post release. Any larger changes to this repository should be done and tested prior to a release using the normal Pull Request workflow +> The release branch in this project is not like the release branches in other projects, we don't save it. If we +> need to go back and do hotfixes, we will branch off the tag that was created for the release. We do this because there +> are usually no changes required to this repository for a release except incrementing the version post release. Any +> larger changes to this repository should be done and tested prior to a release using the normal Pull Request workflow diff --git a/docs/articles/developer-info/Packaging-the-V2-Adapter.md b/docs/articles/developer-info/Packaging-the-V2-Adapter.md index fb00d8376..d0788bcb3 100644 --- a/docs/articles/developer-info/Packaging-the-V2-Adapter.md +++ b/docs/articles/developer-info/Packaging-the-V2-Adapter.md @@ -2,7 +2,8 @@ ## Introduction -There are two purposes for building the adapter, one is for creating the packages for a release - which is what this page is about, the other is for creating whatever you need for debugging or testing purposes. +There are two purposes for building the adapter, one is for creating the packages for a release - which is what this +page is about, the other is for creating whatever you need for debugging or testing purposes. The procedure described here is for those people who need to release a new version of the adapter. @@ -10,8 +11,8 @@ The procedure described here is for those people who need to release a new versi ### Versioning -The version numbers follow the basic principles of [semantic versioning]. -(The fourth number is used for debug versions under development, and will always be 0 for release versions.) +The version numbers follow the basic principles of [semantic versioning]. (The fourth number is used for debug versions +under development, and will always be 0 for release versions.) The version numbers have to be edited in the following files, and should match: @@ -28,69 +29,88 @@ Build a release version, AnyCPU. ## Packaging -Use NAnt and use the package target `NAnt package` -Run this from the solution root folder +Use NAnt and use the package target `NAnt package` Run this from the solution root folder The resulting files can be found in the "package" folder: -* **NUnitVisualStudioTestAdapter-[VERSION].vsix** This is the extension for Visual Studio, which is uploaded to the [Visual Studio Gallery]. +* **NUnitVisualStudioTestAdapter-[VERSION].vsix** This is the extension for Visual Studio, which is uploaded to the + [Visual Studio Gallery]. -* **NUnitVisualStudioTestAdapter-[VERSION].zip** This is a zipped package for use with TFS Server Builds when you don't use the NuGet package in your solution. See [this blog] for more information. +* **NUnitVisualStudioTestAdapter-[VERSION].zip** This is a zipped package for use with TFS Server Builds when you don't + use the NuGet package in your solution. See [this blog] for more information. -* **NUnitVisualStudioTestAdapter-[VERSION].nupkg** This is the NuGet package, which is uploaded to [NuGet for the adapter] +* **NUnitVisualStudioTestAdapter-[VERSION].nupkg** This is the NuGet package, which is uploaded to [NuGet for the + adapter] -* **NUnitVisualStudioTestAdapterAndFramework-[VERSION].nupkg** This is a NuGet package which includes the NUnit 2.6.3 framework, uploaded to [NuGet for the adapter with framework] +* **NUnitVisualStudioTestAdapterAndFramework-[VERSION].nupkg** This is a NuGet package which includes the NUnit 2.6.3 + framework, uploaded to [NuGet for the adapter with framework] ### Publishing the Release -1. Create a release on GitHub. Few people use this directly, but it is the benchmark release and provides an archive of all past releases, so we do this first. Github will automatically create zip and tar files containing the source. In addition, upload all four packages created above as a part of the release. +1. Create a release on GitHub. Few people use this directly, but it is the benchmark release and provides an archive of + all past releases, so we do this first. Github will automatically create zip and tar files containing the source. In + addition, upload all four packages created above as a part of the release. -2. Upload the vsix package to the [Visual Studio Gallery] using the NUnitDeveloper account. If you don't have access to that account, ask one of the committers with access to do the upload for you. +2. Upload the vsix package to the [Visual Studio Gallery] using the NUnitDeveloper account. If you don't have access to + that account, ask one of the committers with access to do the upload for you. -3. Upload the two NuGet packages to nuget.org. You use your own account for this but you must have been pre-authorized in order for it to work. If you are not authorized, ask a committer with access to do it for you. +3. Upload the two NuGet packages to nuget.org. You use your own account for this but you must have been pre-authorized + in order for it to work. If you are not authorized, ask a committer with access to do it for you. -4. Update the documentation pages in this web site as needed. In order to do this quickly after publishing the packages, you may want to clone the `nunit/docs` repository and prepare a pull request in advance. +4. Update the documentation pages in this web site as needed. In order to do this quickly after publishing the packages, + you may want to clone the `nunit/docs` repository and prepare a pull request in advance. -5. Update the website as needed. The website is maintained in the [nunit.org repository] to which all committers have access. You should create a branch like 'release-n.n' and make the necessary changes there. There are three vsAdapterXxxxx files that will probably require updating. Add an announcement to the home page and remove any announcement for an older version of the adapter.Create a pull request to merge your changes into the master branch. For rapid publication, you should create the PR and have it reviewed in advance, performing the merge after the packages are published. +5. Update the website as needed. The website is maintained in the [nunit.org repository] to which all committers have + access. You should create a branch like 'release-n.n' and make the necessary changes there. There are three + vsAdapterXxxxx files that will probably require updating. Add an announcement to the home page and remove any + announcement for an older version of the adapter.Create a pull request to merge your changes into the master branch. + For rapid publication, you should create the PR and have it reviewed in advance, performing the merge after the + packages are published. -6. Publicize the release, first announcing it on the nunit-developer and nunit-discuss lists and then more widely as appropriate. [We should develop a list of places.] +6. Publicize the release, first announcing it on the nunit-developer and nunit-discuss lists and then more widely as + appropriate. [We should develop a list of places.] #### Notes -* Publishing the release requires access to various online accounts, which are mentioned above. For obvious reasons, the passwords are not provided. Contact Charlie or Terje if you need this access. +* Publishing the release requires access to various online accounts, which are mentioned above. For obvious reasons, the + passwords are not provided. Contact Charlie or Terje if you need this access. * The website and docs site contain duplicate information at this time. In future, the duplication will be eliminated. -* When a change is merged into the nunit.org master branch, one of the project leaders uploads it manually to the web site. This will be automated in the future. +* When a change is merged into the nunit.org master branch, one of the project leaders uploads it manually to the web + site. This will be automated in the future. ## Prerequisites -1. **Visual Studio 2013** -You need Visual Studio 2013. We use the ultimate edition, but it should be enough with the premium edition. (I will probably work with both the Pro or the Express editions too, but we haven't tried them). The latest 1.1 version is built using Update 2 RC. +1. **Visual Studio 2013** You need Visual Studio 2013. We use the ultimate edition, but it should be enough with the +premium edition. (I will probably work with both the Pro or the Express editions too, but we haven't tried them). The +latest 1.1 version is built using Update 2 RC. 1. **Visual Studio 2013 SDK** You need this to work with the vsix. Download from -1. **NAnt** -Download from . We use the 0.92 version. +1. **NAnt** Download from . We use the 0.92 version. -1. **NuGet** -You need the nuget.exe in your path. Download the exe from . We use the 2.8 version +1. **NuGet** You need the nuget.exe in your path. Download the exe from +. We use the 2.8 version -1. **VS2012 TestPlatform object model** -You need to have this around, the adapter and the test project refer to this. The easiest way to get it, is to have VS2012 installed and get it from there. -It is located at a location similar to "C:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\CommonExtensions\Microsoft\TestWindow" and is named Microsoft.VisualStudio.TestPlatform.ObjectModel.dll +1. **VS2012 TestPlatform object model** You need to have this around, the adapter and the test project refer to this. +The easiest way to get it, is to have VS2012 installed and get it from there. It is located at a location similar to +"C:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\CommonExtensions\Microsoft\TestWindow" and is named +Microsoft.VisualStudio.TestPlatform.ObjectModel.dll 1. 1. You might need to fix up these references if the locations doesn't match what has been used. ## Github 1) Close the Milestone -2) Draft and publish a Release, named like "Version 2.0". Add all the binaries to the same release. Tag the release like V2.0 +2) Draft and publish a Release, named like "Version 2.0". Add all the binaries to the same release. Tag the release + like V2.0 ## Documentation The adapter release notes should be updated. -The file is named **vsTestAdapterReleaseNotes.html**, and is found under Docs/2.6.4 in the nunit.org repository, branch "vs-adapter-2.0" +The file is named **vsTestAdapterReleaseNotes.html**, and is found under Docs/2.6.4 in the nunit.org repository, branch +"vs-adapter-2.0" Also check that the files **vsTestAdapterLicense.html** and **vsTestAdapterReleaseNotes.html** is up to date. diff --git a/docs/articles/developer-info/Packaging-the-V3-and-V4-Adapter.md b/docs/articles/developer-info/Packaging-the-V3-and-V4-Adapter.md index 792d06622..c3fb47878 100644 --- a/docs/articles/developer-info/Packaging-the-V3-and-V4-Adapter.md +++ b/docs/articles/developer-info/Packaging-the-V3-and-V4-Adapter.md @@ -2,7 +2,9 @@ ## Introduction -There are two purposes for building the adapter, one is for creating the packages for a release - which is what this page is about, the other is for creating whatever you need for debugging or testing purposes. For the latter, see [How to build and debug the adapter] +There are two purposes for building the adapter, one is for creating the packages for a release - which is what this +page is about, the other is for creating whatever you need for debugging or testing purposes. For the latter, see [How +to build and debug the adapter] The procedure described here is for those people who need to release a new version of the adapter. @@ -10,24 +12,32 @@ The procedure described here is for those people who need to release a new versi ### Update to the latest version of NUnit -This may not be necessary for all releases. However, if the NUnit version used by the adapter is being updated, it is important to do it correctly. +This may not be necessary for all releases. However, if the NUnit version used by the adapter is being updated, it is +important to do it correctly. -* The NUnit3TestAdapter, NUnit3TestAdapterInstall and NUnit3TestAdapterTests projects should all reference the same versions of the NUnit Engine package, normally the most recent. +* The NUnit3TestAdapter, NUnit3TestAdapterInstall and NUnit3TestAdapterTests projects should all reference the same + versions of the NUnit Engine package, normally the most recent. -* The NUnit3TestAdapterTests and NUnitTestDemo projects should reference the same version of the NUnit framework package, also normally the most recent. Note that this is currently the same version as the engine package, but this may not continue to be the case if the frequency of release of the two packages differs. +* The NUnit3TestAdapterTests and NUnitTestDemo projects should reference the same version of the NUnit framework + package, also normally the most recent. Note that this is currently the same version as the engine package, but this + may not continue to be the case if the frequency of release of the two packages differs. ### Assembly References -At this time, after upgrading the NUnit engine package, you have to manually adjust the references, removing several that are added automatically by the package and adding an Alias. We will try to eliminate this manual step in the future. +At this time, after upgrading the NUnit engine package, you have to manually adjust the references, removing several +that are added automatically by the package and adding an Alias. We will try to eliminate this manual step in the +future. -For each of the **NUnit3TestAdapter**, **NUnit3TestAdapterTests** and **NUnit3TestAdapterInstall** projects, remove references to nunit-agent and nunit-agent-x86, leaving only the four Mono.Cecil references, nunit.engine and nunit.engine.api. +For each of the **NUnit3TestAdapter**, **NUnit3TestAdapterTests** and **NUnit3TestAdapterInstall** projects, remove +references to nunit-agent and nunit-agent-x86, leaving only the four Mono.Cecil references, nunit.engine and +nunit.engine.api. For the **NUnit3TestAdapter** project, modify the properties for nunit-engine by entering "ENG" for Aliases. ### Versioning -The version numbers follow the basic principles of [semantic versioning]. -(The fourth number is used for debug versions under development, and will always be 0 for release versions.) +The version numbers follow the basic principles of [semantic versioning]. (The fourth number is used for debug versions +under development, and will always be 0 for release versions.) The version numbers have to be edited in the following files, and should match: @@ -58,33 +68,41 @@ Run this from the solution root folder The resulting files can be found in the "package" folder: -* **NUnit3TestAdapter-[VERSION].zip** This is a zipped package for use with TFS Server Builds when you don't use the NuGet package in your solution. See [this blog] for more information. +* **NUnit3TestAdapter-[VERSION].zip** This is a zipped package for use with TFS Server Builds when you don't use the + NuGet package in your solution. See [this blog] for more information. * **NUnit3TestAdapter.[VERSION].nupkg** This is the NuGet package, which is uploaded to [NuGet for the adapter] ### Testing the Packages -Test the NuGet package on the latest Visual Studio, but if you have earlier versions it is recommended to test on those too, down to VS 2012. +Test the NuGet package on the latest Visual Studio, but if you have earlier versions it is recommended to test on those +too, down to VS 2012. ### Publishing the Release -1. Create a release on GitHub. Few people use this directly, but it is the benchmark release and provides an archive of all past releases, so we do this first. Github will automatically create zip and tar files containing the source. In addition, upload all three packages created above as a part of the release. +1. Create a release on GitHub. Few people use this directly, but it is the benchmark release and provides an archive of + all past releases, so we do this first. Github will automatically create zip and tar files containing the source. In + addition, upload all three packages created above as a part of the release. -2. Upload the NuGet package to nuget.org. You use your own account for this but you must have been pre-authorized in order for it to work. If you are not authorized, ask a committer with access to do it for you. +2. Upload the NuGet package to nuget.org. You use your own account for this but you must have been pre-authorized in + order for it to work. If you are not authorized, ask a committer with access to do it for you. -3. Update the documentation pages in the site as needed. Be sure to update the Release Notes page. In order to perform the update quickly after publishing the packages, you may want to clone the `nunit/docs` repository and prepare the pull request in advance. +3. Update the documentation pages in the site as needed. Be sure to update the Release Notes page. In order to perform + the update quickly after publishing the packages, you may want to clone the `nunit/docs` repository and prepare the + pull request in advance. -4. Publicize the release, first announcing it on the nunit-developer and nunit-discuss lists and then more widely as appropriate. [We should develop a list of places.] +4. Publicize the release, first announcing it on the nunit-developer and nunit-discuss lists and then more widely as + appropriate. [We should develop a list of places.] > [!NOTE] -> Publishing the release requires access to various online accounts, which are mentioned above. For obvious reasons, the passwords are not provided. Contact Charlie or Terje if you need this access. +> Publishing the release requires access to various online accounts, which are mentioned above. For obvious +> reasons, the passwords are not provided. Contact Charlie or Terje if you need this access. ## Prerequisites -1. **Visual Studio** - Visual Studio 2022 is required in order to build and develop the adapter. -2. **.Net SDKs** - You need at least the .Net Core 3.1, .net 5, 6 and 7 SDKs installed. Not all are required for the build, but they are required for the tests. You also need .Net Framework 4.6.2 installed. +1. **Visual Studio** Visual Studio 2022 is required in order to build and develop the adapter. +2. **.Net SDKs** You need at least the .Net Core 3.1, .net 5, 6 and 7 SDKs installed. Not all are required for the + build, but they are required for the tests. You also need .Net Framework 4.6.2 installed. ## Links @@ -92,5 +110,7 @@ Test the NuGet package on the latest Visual Studio, but if you have earlier vers ## Other GitHub Repositories That Need to be Updated -1. **.Net test templates** -You should raise PR in the [dotnet test template repo](https://github.com/dotnet/test-templates) to update the test templates to use the latest version of the adapter. See [this PR](https://github.com/dotnet/test-templates/pull/273) for an example. Right now (March 2023), Microsoft doesn't accept more PRs to the repo. +1. **.Net test templates** You should raise PR in the [dotnet test template +repo](https://github.com/dotnet/test-templates) to update the test templates to use the latest version of the adapter. +See [this PR](https://github.com/dotnet/test-templates/pull/273) for an example. Right now (March 2023), Microsoft +doesn't accept more PRs to the repo. diff --git a/docs/articles/developer-info/The-Teams.md b/docs/articles/developer-info/The-Teams.md index db4ce277f..02d2afb40 100644 --- a/docs/articles/developer-info/The-Teams.md +++ b/docs/articles/developer-info/The-Teams.md @@ -1,14 +1,18 @@ # The Teams in the NUnit Project -The NUnit project is made up of several teams, each with its own focus and responsibilities, and with a set of team members. +The NUnit project is made up of several teams, each with its own focus and responsibilities, and with a set of team +members. -The team members are a bunch of dedicated people from all over the globe, who are passionate about NUnit and want to make it better. They are all volunteers, and they do this in their spare time. +The team members are a bunch of dedicated people from all over the globe, who are passionate about NUnit and want to +make it better. They are all volunteers, and they do this in their spare time. ## The current teams ### Core Team -This team has overall responsibility for the NUnit organization. It defines the vision for NUnit, decides what projects should be included, appoints leads for other teams and maintainers for projects, sets standards and ensures we follow them. +This team has overall responsibility for the NUnit organization. It defines the vision for NUnit, decides what projects +should be included, appoints leads for other teams and maintainers for projects, sets standards and ensures we follow +them. Team Lead: [Terje Sandstrom](https://github.com/osiristerje) diff --git a/docs/articles/nunit-analyzers/NUnit-Analyzers.md b/docs/articles/nunit-analyzers/NUnit-Analyzers.md index 662418db3..19931a6d1 100644 --- a/docs/articles/nunit-analyzers/NUnit-Analyzers.md +++ b/docs/articles/nunit-analyzers/NUnit-Analyzers.md @@ -112,7 +112,8 @@ Rules which improve assertions in the test code. ## Suppressor Rules (NUnit3001 - ) -Rules which suppress compiler errors based on context. Note that these rules are only available in the .NET Standard 2.0 builds (version 3.0.0 and above) which require Visual Studio 2019. +Rules which suppress compiler errors based on context. Note that these rules are only available in the .NET Standard 2.0 +builds (version 3.0.0 and above) which require Visual Studio 2019. | Id | Title | :mag: | :memo: | :bulb: | | :-- | :-- | :--: | :--: | :--: | diff --git a/docs/articles/nunit-analyzers/NUnit1001.md b/docs/articles/nunit-analyzers/NUnit1001.md index f744d02cd..2f8a654a7 100644 --- a/docs/articles/nunit-analyzers/NUnit1001.md +++ b/docs/articles/nunit-analyzers/NUnit1001.md @@ -12,7 +12,8 @@ ## Description -The individual arguments provided by a TestCaseAttribute must match the type of the corresponding parameter of the method. +The individual arguments provided by a TestCaseAttribute must match the type of the corresponding parameter of the +method. ## Motivation @@ -32,7 +33,8 @@ public void SampleTest(int numberValue) ### Problem -In the test case above, `true` in the test case indicates that `numberValue` should be a boolean. However, the test declares that `numberValue` is an integer. This will lead to a runtime failure. +In the test case above, `true` in the test case indicates that `numberValue` should be a boolean. However, the test +declares that `numberValue` is an integer. This will lead to a runtime failure. ### Fix @@ -65,7 +67,8 @@ public void SampleTest(int numberValue) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1002.md b/docs/articles/nunit-analyzers/NUnit1002.md index cfcd05c58..51207e8dd 100644 --- a/docs/articles/nunit-analyzers/NUnit1002.md +++ b/docs/articles/nunit-analyzers/NUnit1002.md @@ -16,7 +16,8 @@ The TestCaseSource should use nameof operator to specify target. ## Motivation -Prevent test rot by ensuring that future renames don't accidentally break tests in an unexpected way. `nameof` adds some compile-time support in these situations. +Prevent test rot by ensuring that future renames don't accidentally break tests in an unexpected way. `nameof` adds some +compile-time support in these situations. ## How to fix violations @@ -37,11 +38,13 @@ public static object[] MyTestSource() ### Problem -In this case, we're referring to `"MyTestSource"` as a string directly. This is brittle; should the name of the property change, the test case source would become invalid, and we would not know this until executing tests. +In this case, we're referring to `"MyTestSource"` as a string directly. This is brittle; should the name of the property +change, the test case source would become invalid, and we would not know this until executing tests. ### Fix -The fix is to use the C# `nameof` operator, which produces a string but references the field name. This way, when refactoring and changing the name of your test source, it would also update the name within the `nameof()` operator. +The fix is to use the C# `nameof` operator, which produces a string but references the field name. This way, when +refactoring and changing the name of your test source, it would also update the name within the `nameof()` operator. The fix in action: @@ -63,7 +66,8 @@ public static object[] MyTestSource() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1003.md b/docs/articles/nunit-analyzers/NUnit1003.md index a082a1a36..fd66bcc2f 100644 --- a/docs/articles/nunit-analyzers/NUnit1003.md +++ b/docs/articles/nunit-analyzers/NUnit1003.md @@ -33,7 +33,8 @@ public void NUnit1003SampleTest(string parameter1, string parameter2) ### Explanation -In the sample above, the test expects two parameters (`(string parameter1, string parameter2)`), but only one argument is supplied by the test case (`TestCase("1")`). +In the sample above, the test expects two parameters (`(string parameter1, string parameter2)`), but only one argument +is supplied by the test case (`TestCase("1")`). ### Fix @@ -63,7 +64,8 @@ public void NUnit1003SampleTest(string parameter1) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1004.md b/docs/articles/nunit-analyzers/NUnit1004.md index 4d32ff3a1..04926bc35 100644 --- a/docs/articles/nunit-analyzers/NUnit1004.md +++ b/docs/articles/nunit-analyzers/NUnit1004.md @@ -32,7 +32,8 @@ public void NUnit1004SampleTest(string parameter1) ### Explanation -In the sample above, there are two arguments provided by test case (`TestCase("1", "2")`), but only one parameter is being expected by the test itself (`(string parameter1)`). +In the sample above, there are two arguments provided by test case (`TestCase("1", "2")`), but only one parameter is +being expected by the test itself (`(string parameter1)`). ### Fix @@ -62,7 +63,8 @@ public void NUnit1003SampleTest(string parameter1) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1005.md b/docs/articles/nunit-analyzers/NUnit1005.md index b3996b42b..b208a4e34 100644 --- a/docs/articles/nunit-analyzers/NUnit1005.md +++ b/docs/articles/nunit-analyzers/NUnit1005.md @@ -12,7 +12,8 @@ ## Description -The type of the value specified via ExpectedResult must match the return type of the method. Otherwise, this will lead to an error at run-time. +The type of the value specified via ExpectedResult must match the return type of the method. Otherwise, this will lead +to an error at run-time. ## Motivation @@ -32,7 +33,8 @@ public int NUnit1005SampleTest(int inputValue) ### Explanation -The sample above uses NUnit's `ExpectedResult` syntax. It defines a result of `true` (a `bool`) but the return type of the method is `int`. +The sample above uses NUnit's `ExpectedResult` syntax. It defines a result of `true` (a `bool`) but the return type of +the method is `int`. ### Fix @@ -61,7 +63,8 @@ public bool NUnit1005SampleTest(int inputValue) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1006.md b/docs/articles/nunit-analyzers/NUnit1006.md index 0fef31cfb..caaaa4497 100644 --- a/docs/articles/nunit-analyzers/NUnit1006.md +++ b/docs/articles/nunit-analyzers/NUnit1006.md @@ -32,7 +32,8 @@ public void NUnit1006SampleTest(int inputValue) ### Explanation -An `ExpectedResult` was defined, but the return type of the method in our sample is of type `void`, meaning it does not return a result. +An `ExpectedResult` was defined, but the return type of the method in our sample is of type `void`, meaning it does not +return a result. ### Fix @@ -61,7 +62,8 @@ public string NUnit1006SampleTest(int inputValue) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1007.md b/docs/articles/nunit-analyzers/NUnit1007.md index 1754536e4..59eaed9e3 100644 --- a/docs/articles/nunit-analyzers/NUnit1007.md +++ b/docs/articles/nunit-analyzers/NUnit1007.md @@ -32,7 +32,8 @@ public string NUnit1007SampleTest(int inputValue) ### Explanation -No `ExpectedResult` was defined, but the return type of the method in our sample is of type `string`, meaning it does indeed return a result and we should use the `ExpectedResult` syntax in order to capture it. +No `ExpectedResult` was defined, but the return type of the method in our sample is of type `string`, meaning it does +indeed return a result and we should use the `ExpectedResult` syntax in order to capture it. ### Fix @@ -61,7 +62,8 @@ public void NUnit1007SampleTest(int inputValue) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1008.md b/docs/articles/nunit-analyzers/NUnit1008.md index 910eb119d..78ecc2ecc 100644 --- a/docs/articles/nunit-analyzers/NUnit1008.md +++ b/docs/articles/nunit-analyzers/NUnit1008.md @@ -16,7 +16,8 @@ Specifying ParallelScope.Self on assembly level has no effect. ## Motivation -Bring developers' attention to a scenario in which they may believe they are parallelizing something when in fact they are not and their efforts will have no effect. +Bring developers' attention to a scenario in which they may believe they are parallelizing something when in fact they +are not and their efforts will have no effect. ## How to fix violations @@ -51,7 +52,8 @@ Or: ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1009.md b/docs/articles/nunit-analyzers/NUnit1009.md index 2351c3ab2..88a1d7ac0 100644 --- a/docs/articles/nunit-analyzers/NUnit1009.md +++ b/docs/articles/nunit-analyzers/NUnit1009.md @@ -35,7 +35,8 @@ public void NUnit1009SampleTest() In the sample above, the `Parallelizable` attribute is used with `ParallelScope.Children`. -However, in a non-parameterized test, such as a `[Test]` and not a `[TestCase]`, there will be no children generated, and thus this type of parallelization does not make sense. +However, in a non-parameterized test, such as a `[Test]` and not a `[TestCase]`, there will be no children generated, +and thus this type of parallelization does not make sense. ### Fix @@ -66,7 +67,8 @@ public void NUnit1009SampleTest(int numberValue) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1010.md b/docs/articles/nunit-analyzers/NUnit1010.md index 29a42de34..5fd6c15f0 100644 --- a/docs/articles/nunit-analyzers/NUnit1010.md +++ b/docs/articles/nunit-analyzers/NUnit1010.md @@ -35,7 +35,8 @@ public void NUnit1010SampleTest() In the sample above, `ParallelScope.Fixtures` is specified. -However, in the context of a test method, a scope of `Fixtures` does not make sense. This scope [only applies at the assembly or class level](xref:parallelizableattribute). +However, in the context of a test method, a scope of `Fixtures` does not make sense. This scope [only applies at the +assembly or class level](xref:parallelizableattribute). ### Fix @@ -79,7 +80,8 @@ public void NUnit1010SampleTest() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1011.md b/docs/articles/nunit-analyzers/NUnit1011.md index 362935f4e..c0550a6f0 100644 --- a/docs/articles/nunit-analyzers/NUnit1011.md +++ b/docs/articles/nunit-analyzers/NUnit1011.md @@ -37,7 +37,8 @@ public static object[] MyTestSource() ### Explanation -In the example above, the test case source is named `MyIncorrectTestCaseSource`, but the test case source is actually named `MyTestSource`. Because the names don't match, this will be an error. +In the example above, the test case source is named `MyIncorrectTestCaseSource`, but the test case source is actually +named `MyTestSource`. Because the names don't match, this will be an error. ### Fix @@ -76,7 +77,8 @@ public static object[] MyTestSource() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1012.md b/docs/articles/nunit-analyzers/NUnit1012.md index 47b83f6e8..d2e970ef5 100644 --- a/docs/articles/nunit-analyzers/NUnit1012.md +++ b/docs/articles/nunit-analyzers/NUnit1012.md @@ -33,7 +33,9 @@ public async void NUnit1012SampleTest() ### Explanation -`async` methods should generally not return `void` in C#. For example if an exception is thrown (as they are in the case of an assertion violation), the exception is actually a part of the task object. If the return type is `void`, no such object exists, to the exception is effectively swallowed. +`async` methods should generally not return `void` in C#. For example if an exception is thrown (as they are in the case +of an assertion violation), the exception is actually a part of the task object. If the return type is `void`, no such +object exists, to the exception is effectively swallowed. ### Fix @@ -64,7 +66,8 @@ public void NUnit1012SampleTest() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1014.md b/docs/articles/nunit-analyzers/NUnit1014.md index ba3aab021..4c3d3b32c 100644 --- a/docs/articles/nunit-analyzers/NUnit1014.md +++ b/docs/articles/nunit-analyzers/NUnit1014.md @@ -32,7 +32,8 @@ public async Task NUnit1014SampleTest(int numberValue) ### Explanation -The NUnit `ExpectedResult` syntax is used, so this method needs to return a type that matches the type of expected result you're looking for. +The NUnit `ExpectedResult` syntax is used, so this method needs to return a type that matches the type of expected +result you're looking for. ### Fix @@ -61,7 +62,8 @@ public async Task NUnit1014SampleTest(int numberValue) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1019.md b/docs/articles/nunit-analyzers/NUnit1019.md index 7e442bc82..7504b8b5f 100644 --- a/docs/articles/nunit-analyzers/NUnit1019.md +++ b/docs/articles/nunit-analyzers/NUnit1019.md @@ -36,10 +36,11 @@ public class AnalyzeWhenSourceDoesProvideIEnumerable ### Explanation -In the sample above, the source specified by `TestCaseSource` - the field `testCases` - does not return an `IEnumerable` or a type that implements `IEnumerable`, -instead it returns an `int`. +In the sample above, the source specified by `TestCaseSource` - the field `testCases` - does not return an `IEnumerable` +or a type that implements `IEnumerable`, instead it returns an `int`. -However, sources specified by `TestCaseSource` [must return an `IEnumerable` or a type that implements `IEnumerable`.](xref:testcasesourceattribute). +However, sources specified by `TestCaseSource` [must return an `IEnumerable` or a type that implements +`IEnumerable`.](xref:testcasesourceattribute). ### Fix @@ -62,7 +63,8 @@ public class AnalyzeWhenSourceDoesProvideIEnumerable ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1020.md b/docs/articles/nunit-analyzers/NUnit1020.md index ffbaa51f6..111cf096d 100644 --- a/docs/articles/nunit-analyzers/NUnit1020.md +++ b/docs/articles/nunit-analyzers/NUnit1020.md @@ -42,7 +42,8 @@ public class MyTestClass ### Explanation -In the sample above, `DivideCases` is a field, and as such does not accept any arguments, so the `TestCaseSource` should not supply any parameters. +In the sample above, `DivideCases` is a field, and as such does not accept any arguments, so the `TestCaseSource` should +not supply any parameters. ### Fix @@ -74,7 +75,8 @@ public class MyTestClass ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1021.md b/docs/articles/nunit-analyzers/NUnit1021.md index cb19fcc64..b465976d1 100644 --- a/docs/articles/nunit-analyzers/NUnit1021.md +++ b/docs/articles/nunit-analyzers/NUnit1021.md @@ -16,7 +16,8 @@ The ValueSource should use nameof operator to specify target. ## Motivation -Prevent test rot by ensuring that future renames don't accidentally break tests in an unexpected way. `nameof` adds some compile-time support in these situations. +Prevent test rot by ensuring that future renames don't accidentally break tests in an unexpected way. `nameof` adds some +compile-time support in these situations. ## How to fix violations @@ -37,11 +38,13 @@ public static object[] MyTestSource() ### Problem -In this case, we're referring to `"MyTestSource"` as a string directly. This is brittle; should the name of the property change, the test case source would become invalid, and we would not know this until executing tests. +In this case, we're referring to `"MyTestSource"` as a string directly. This is brittle; should the name of the property +change, the test case source would become invalid, and we would not know this until executing tests. ### Fix -The fix is to use the C# `nameof` operator, which produces a string but references the field name. This way, when refactoring and changing the name of your test source, it would also update the name within the `nameof()` operator. +The fix is to use the C# `nameof` operator, which produces a string but references the field name. This way, when +refactoring and changing the name of your test source, it would also update the name within the `nameof()` operator. The fix in action: @@ -63,7 +66,8 @@ public static object[] MyTestSource() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1024.md b/docs/articles/nunit-analyzers/NUnit1024.md index bd6f89f91..af304e3f1 100644 --- a/docs/articles/nunit-analyzers/NUnit1024.md +++ b/docs/articles/nunit-analyzers/NUnit1024.md @@ -36,10 +36,11 @@ public class AnalyzeWhenSourceDoesProvideIEnumerable ### Explanation -In the sample above, the source specified by `ValueSource` - the field `testCases` - does not return an `IEnumerable` or a type that implements `IEnumerable`, -instead it returns an `int`. +In the sample above, the source specified by `ValueSource` - the field `testCases` - does not return an `IEnumerable` or +a type that implements `IEnumerable`, instead it returns an `int`. -However, sources specified by `ValueSource` [must return an `IEnumerable` or a type that implements `IEnumerable`.](xref:valuesource). +However, sources specified by `ValueSource` [must return an `IEnumerable` or a type that implements +`IEnumerable`.](xref:valuesource). ### Fix @@ -62,7 +63,8 @@ public class AnalyzeWhenSourceDoesProvideIEnumerable ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1025.md b/docs/articles/nunit-analyzers/NUnit1025.md index 887e971f6..40a3f5172 100644 --- a/docs/articles/nunit-analyzers/NUnit1025.md +++ b/docs/articles/nunit-analyzers/NUnit1025.md @@ -37,7 +37,8 @@ public static object[] MyTestSource() ### Explanation -In the example above, the test case source is named `MyIncorrectTestCaseSource`, but the test case source is actually named `MyTestSource`. Because the names don't match, this will be an error. +In the example above, the test case source is named `MyIncorrectTestCaseSource`, but the test case source is actually +named `MyTestSource`. Because the names don't match, this will be an error. ### Fix @@ -76,7 +77,8 @@ public static object[] MyTestSource() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1026.md b/docs/articles/nunit-analyzers/NUnit1026.md index 24dbaa350..d7811ecf7 100644 --- a/docs/articles/nunit-analyzers/NUnit1026.md +++ b/docs/articles/nunit-analyzers/NUnit1026.md @@ -46,13 +46,14 @@ private protected static void NUnit1026SampleTest2(int i) ### Explanation -In the example above, the test named `NUnit1026SampleTest` is not `public` - it has the default access modifier for a method, i.e. `internal`. -`NUnit1026SampleTest2` has the explicit access modifier `private protected`, which again is not `public`. -NUnit only runs `public` methods, so neither test can be run. +In the example above, the test named `NUnit1026SampleTest` is not `public` - it has the default access modifier for a +method, i.e. `internal`. `NUnit1026SampleTest2` has the explicit access modifier `private protected`, which again is not +`public`. NUnit only runs `public` methods, so neither test can be run. ### Fix -The analyzer comes with a code fix that will change the access modifier to `public`. So the tests above will be changed into. +The analyzer comes with a code fix that will change the access modifier to `public`. So the tests above will be changed +into. ```csharp private int Value; @@ -81,7 +82,8 @@ public static void NUnit1026SampleTest2(int i) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1027.md b/docs/articles/nunit-analyzers/NUnit1027.md index c4e1b0b9c..6a6734c4d 100644 --- a/docs/articles/nunit-analyzers/NUnit1027.md +++ b/docs/articles/nunit-analyzers/NUnit1027.md @@ -32,11 +32,13 @@ public void SampleTest(int numberValue) ### Problem -In the test case above, the declares that it expects one integer parameter, but no argument is supplied by the attributes. This will lead to a runtime failure. +In the test case above, the declares that it expects one integer parameter, but no argument is supplied by the +attributes. This will lead to a runtime failure. ### Fix -Ensure that the correct number of arguments - and of the correct type - is supplied to test methods that expect parameters. +Ensure that the correct number of arguments - and of the correct type - is supplied to test methods that expect +parameters. One possible fix to this problem would be to supply the argument using a `TestCase`: @@ -63,7 +65,8 @@ public void SampleTest([Range(1, 10)] int numberValue) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1029.md b/docs/articles/nunit-analyzers/NUnit1029.md index 53fc80a50..92906d520 100644 --- a/docs/articles/nunit-analyzers/NUnit1029.md +++ b/docs/articles/nunit-analyzers/NUnit1029.md @@ -18,7 +18,8 @@ Note that the current implementation only works for single parameters. ## Motivation -A `TestCaseSourceAttribute` is used to pass parameters to a test method, but the test method does not expect any or more parameters than supplied. +A `TestCaseSourceAttribute` is used to pass parameters to a test method, but the test method does not expect any or more +parameters than supplied. ```charp private static readonly IEnumerable NUnitNameSpaces = new[] { ".NUnit", ".NUnitExtensions" }; @@ -38,7 +39,8 @@ Match the number of parameters between the test data and the test method. ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1030.md b/docs/articles/nunit-analyzers/NUnit1030.md index 931bcbc11..45c765fe3 100644 --- a/docs/articles/nunit-analyzers/NUnit1030.md +++ b/docs/articles/nunit-analyzers/NUnit1030.md @@ -18,7 +18,8 @@ Note that the current implementation only works for single parameters. ## Motivation -A `TestCaseSourceAttribute` is used to pass parameters to a test method, but the test method expects a different type of parameter. +A `TestCaseSourceAttribute` is used to pass parameters to a test method, but the test method expects a different type of +parameter. ```charp private static readonly IEnumerable NUnitNameSpaces = new[] { ".NUnit", ".NUnitExtensions" }; @@ -38,7 +39,8 @@ Match the type of parameters between the test data and the test method. ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit1031.md b/docs/articles/nunit-analyzers/NUnit1031.md index 070b29b68..6583d0e7b 100644 --- a/docs/articles/nunit-analyzers/NUnit1031.md +++ b/docs/articles/nunit-analyzers/NUnit1031.md @@ -32,7 +32,8 @@ public void SampleTest([Values(0.0, 1.0)] int numberValue) ### Problem -In the test above, `numberValue` is declared as an integer. However, `[Values(0.0, 1.0)]` provides values as doubles. This will lead to a runtime failure. +In the test above, `numberValue` is declared as an integer. However, `[Values(0.0, 1.0)]` provides values as doubles. +This will lead to a runtime failure. ### Fix @@ -65,7 +66,8 @@ public void SampleTest([Values(0.0, 1.0)] double numberValue) ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2005.md b/docs/articles/nunit-analyzers/NUnit2005.md index c2ba1e046..023d5d2d1 100644 --- a/docs/articles/nunit-analyzers/NUnit2005.md +++ b/docs/articles/nunit-analyzers/NUnit2005.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.EqualTo(expected))`, instead of the classic model, `Assert.AreEqual(expected, actual)`. +Consider using the constraint model, `Assert.That(actual, Is.EqualTo(expected))`, instead of the classic model, +`Assert.AreEqual(expected, actual)`. ## Motivation -The classic Assert model, `Assert.AreEqual(expected, actual)`, makes it easy to mix the `expected` and the `actual` parameter, -so this analyzer marks usages of `Assert.AreEqual` from the classic Assert model. +The classic Assert model, `Assert.AreEqual(expected, actual)`, makes it easy to mix the `expected` and the `actual` +parameter, so this analyzer marks usages of `Assert.AreEqual` from the classic Assert model. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2006.md b/docs/articles/nunit-analyzers/NUnit2006.md index ef9b381e5..2fe0773eb 100644 --- a/docs/articles/nunit-analyzers/NUnit2006.md +++ b/docs/articles/nunit-analyzers/NUnit2006.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.Not.EqualTo(expected))`, instead of the classic model, `Assert.AreNotEqual(expected, actual)`. +Consider using the constraint model, `Assert.That(actual, Is.Not.EqualTo(expected))`, instead of the classic model, +`Assert.AreNotEqual(expected, actual)`. ## Motivation -The classic Assert model, `Assert.AreNotEqual(expected, actual)`, makes it easy to mix the `expected` and the `actual` parameter, -so this analyzer marks usages of `Assert.AreNotEqual` from the classic Assert model. +The classic Assert model, `Assert.AreNotEqual(expected, actual)`, makes it easy to mix the `expected` and the `actual` +parameter, so this analyzer marks usages of `Assert.AreNotEqual` from the classic Assert model. ```csharp [Test] @@ -29,8 +30,8 @@ public void Test() ## How to fix violations -The analyzer comes with a code fix that will replace `Assert.AreNotEqual(expression1, expression2)` -with `Assert.That(expression2, Is.Not.EqualTo(expression1))`. So the code block above will be changed into. +The analyzer comes with a code fix that will replace `Assert.AreNotEqual(expression1, expression2)` with +`Assert.That(expression2, Is.Not.EqualTo(expression1))`. So the code block above will be changed into. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2007.md b/docs/articles/nunit-analyzers/NUnit2007.md index e98ced4c1..8dddbabb1 100644 --- a/docs/articles/nunit-analyzers/NUnit2007.md +++ b/docs/articles/nunit-analyzers/NUnit2007.md @@ -12,11 +12,13 @@ ## Description -The actual value should not be a constant. This indicates that the actual value and the expected value have switched places. +The actual value should not be a constant. This indicates that the actual value and the expected value have switched +places. ## Motivation -Bring developers' attention to a scenario in which their test is most likely testing the wrong thing, or to cases where their actual and expected values may be accidentally swapped. +Bring developers' attention to a scenario in which their test is most likely testing the wrong thing, or to cases where +their actual and expected values may be accidentally swapped. ## How to fix violations @@ -34,15 +36,19 @@ public void NUnit2007SampleTest() ### Explanation -Both asserts above will trigger this warning. That's because the actual value should be the value produced by your code, not a constant value that you're expecting (which should be in the place of the expected value). +Both asserts above will trigger this warning. That's because the actual value should be the value produced by your code, +not a constant value that you're expecting (which should be in the place of the expected value). -In the case of equality, etc. this might seem like no big deal, but it really comes into play in the exceptions that are raised by error messages. It's important that if your test fails, the message can correctly tell you what the expected and actual values are. +In the case of equality, etc. this might seem like no big deal, but it really comes into play in the exceptions that are +raised by error messages. It's important that if your test fails, the message can correctly tell you what the expected +and actual values are. As an aside, this is another reason why the `Assert.That` syntax is often preferred when asserting equality. ### Fix -Flip the actual and expected values so that your expected value is the constant and your actual value has been generated by code. +Flip the actual and expected values so that your expected value is the constant and your actual value has been generated +by code. ```csharp [Test] @@ -59,7 +65,8 @@ public void NUnit2007SampleTest() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2008.md b/docs/articles/nunit-analyzers/NUnit2008.md index a69308f8d..1883bab11 100644 --- a/docs/articles/nunit-analyzers/NUnit2008.md +++ b/docs/articles/nunit-analyzers/NUnit2008.md @@ -12,11 +12,13 @@ ## Description -The IgnoreCase modifier should only be used for string or char arguments. Using it on another type will not have any effect. +The IgnoreCase modifier should only be used for string or char arguments. Using it on another type will not have any +effect. ## Motivation -To bring developers' attention to a scenario in which their code is actually having no effect and may reveal that their test is not doing what they expect. +To bring developers' attention to a scenario in which their code is actually having no effect and may reveal that their +test is not doing what they expect. ## How to fix violations @@ -33,7 +35,8 @@ public void NUnit2008SampleTest() ### Explanation -Using IgnoreCase here doesn't make any sense, because the types we're comparing don't have the concept of case. Therefore, it's only suitable to use on textual primitives (e.g. `string` and `char`). +Using IgnoreCase here doesn't make any sense, because the types we're comparing don't have the concept of case. +Therefore, it's only suitable to use on textual primitives (e.g. `string` and `char`). ### Fix @@ -64,7 +67,8 @@ public void NUnit2008SampleTest() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2009.md b/docs/articles/nunit-analyzers/NUnit2009.md index 6165c755c..2bf605122 100644 --- a/docs/articles/nunit-analyzers/NUnit2009.md +++ b/docs/articles/nunit-analyzers/NUnit2009.md @@ -16,7 +16,8 @@ The same value has been provided as both the actual and the expected argument. T ## Motivation -To bring developers' attention to a situation in which their code may not be operating as expected and their test may not be testing what they expect. +To bring developers' attention to a situation in which their code may not be operating as expected and their test may +not be testing what they expect. ## How to fix violations @@ -33,7 +34,8 @@ public void NUnit2009SampleTest() ### Explanation -In the above example, the test will always be correct, because we're comparing the same value. That is to say, we're not actually testing anything. +In the above example, the test will always be correct, because we're comparing the same value. That is to say, we're not +actually testing anything. ### Fix @@ -53,7 +55,8 @@ public void NUnit2009SampleTest() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2015.md b/docs/articles/nunit-analyzers/NUnit2015.md index 4a4040272..2ac9c72f6 100644 --- a/docs/articles/nunit-analyzers/NUnit2015.md +++ b/docs/articles/nunit-analyzers/NUnit2015.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.SameAs(expected))`, instead of the classic model, `Assert.AreSame(expected, actual)`. +Consider using the constraint model, `Assert.That(actual, Is.SameAs(expected))`, instead of the classic model, +`Assert.AreSame(expected, actual)`. ## Motivation -The assert `Assert.AreSame` from the classic Assert model makes it easy to confuse the `expected` and the `actual` argument, -so this analyzer marks usages of `Assert.AreSame`. +The assert `Assert.AreSame` from the classic Assert model makes it easy to confuse the `expected` and the `actual` +argument, so this analyzer marks usages of `Assert.AreSame`. ```csharp [Test] @@ -29,8 +30,8 @@ public void Test() ## How to fix violations -The analyzer comes with a code fix that will replace `Assert.AreSame(expected, actual)` with -`Assert.That(actual, Is.SameAs(expected))`. So the code block above will be changed into. +The analyzer comes with a code fix that will replace `Assert.AreSame(expected, actual)` with `Assert.That(actual, +Is.SameAs(expected))`. So the code block above will be changed into. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2023.md b/docs/articles/nunit-analyzers/NUnit2023.md index 9329a5c6e..1068bb84a 100644 --- a/docs/articles/nunit-analyzers/NUnit2023.md +++ b/docs/articles/nunit-analyzers/NUnit2023.md @@ -16,7 +16,8 @@ NullConstraint is allowed only for reference types or nullable value types. ## Motivation -Non-nullable value types cannot have `null` value, therefore `Is.Null` assertions will always fail (or will always pass for `Is.Not.Null`). +Non-nullable value types cannot have `null` value, therefore `Is.Null` assertions will always fail (or will always pass +for `Is.Not.Null`). ## How to fix violations @@ -27,7 +28,8 @@ Use suitable constraint. ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2025.md b/docs/articles/nunit-analyzers/NUnit2025.md index 613a43efa..0b3199611 100644 --- a/docs/articles/nunit-analyzers/NUnit2025.md +++ b/docs/articles/nunit-analyzers/NUnit2025.md @@ -16,7 +16,8 @@ The ContainsConstraint requires the type of the actual value to be either a stri ## Motivation -Using a ContainsConstraint with an actual argument, which is neither a string nor a collection of strings, leads to an assertion error. +Using a ContainsConstraint with an actual argument, which is neither a string nor a collection of strings, leads to an +assertion error. ## How to fix violations @@ -27,7 +28,8 @@ Fix the actual value or use appropriate constraint. ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2026.md b/docs/articles/nunit-analyzers/NUnit2026.md index a86ef1d6b..e3a2260ab 100644 --- a/docs/articles/nunit-analyzers/NUnit2026.md +++ b/docs/articles/nunit-analyzers/NUnit2026.md @@ -12,11 +12,13 @@ ## Description -The SomeItemsConstraint with EqualConstraint requires the actual argument to be a collection where the element type can match the type of the expected argument. +The SomeItemsConstraint with EqualConstraint requires the actual argument to be a collection where the element type can +match the type of the expected argument. ## Motivation -Using Does.Contain or Contains.Item constraints with actual argument, which is either not a collection, or has wrong element type, leads to assertion error. +Using Does.Contain or Contains.Item constraints with actual argument, which is either not a collection, or has wrong +element type, leads to assertion error. ## How to fix violations @@ -27,7 +29,8 @@ Fix the actual value or use appropriate constraint. ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2027.md b/docs/articles/nunit-analyzers/NUnit2027.md index 5ffe7088d..2ddcc53bc 100644 --- a/docs/articles/nunit-analyzers/NUnit2027.md +++ b/docs/articles/nunit-analyzers/NUnit2027.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.GreaterThan(expected))`, instead of the classic model, `Assert.Greater(actual, expected)`. +Consider using the constraint model, `Assert.That(actual, Is.GreaterThan(expected))`, instead of the classic model, +`Assert.Greater(actual, expected)`. ## Motivation -The assert `Assert.Greater` from the classic Assert model makes it easy to confuse the `expected` and the `actual` argument, -so this analyzer marks usages of `Assert.Greater`. +The assert `Assert.Greater` from the classic Assert model makes it easy to confuse the `expected` and the `actual` +argument, so this analyzer marks usages of `Assert.Greater`. ```csharp [Test] @@ -29,8 +30,8 @@ public void Test() ## How to fix violations -The analyzer comes with a code fix that will replace `Assert.Greater(actual, expected)` with -`Assert.That(actual, Is.GreaterThan(expected))`. So the code block above will be changed into. +The analyzer comes with a code fix that will replace `Assert.Greater(actual, expected)` with `Assert.That(actual, +Is.GreaterThan(expected))`. So the code block above will be changed into. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2028.md b/docs/articles/nunit-analyzers/NUnit2028.md index 15b6d683b..1793e6dec 100644 --- a/docs/articles/nunit-analyzers/NUnit2028.md +++ b/docs/articles/nunit-analyzers/NUnit2028.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.GreaterThanOrEqualTo(expected))`, instead of the classic model, `Assert.GreaterOrEqual(actual, expected)`. +Consider using the constraint model, `Assert.That(actual, Is.GreaterThanOrEqualTo(expected))`, instead of the classic +model, `Assert.GreaterOrEqual(actual, expected)`. ## Motivation -The assert `Assert.GreaterOrEqual` from the classic Assert model makes it easy to confuse the `expected` and the `actual` argument, -so this analyzer marks usages of `Assert.GreaterOrEqual`. +The assert `Assert.GreaterOrEqual` from the classic Assert model makes it easy to confuse the `expected` and the +`actual` argument, so this analyzer marks usages of `Assert.GreaterOrEqual`. ```csharp [Test] @@ -29,8 +30,8 @@ public void Test() ## How to fix violations -The analyzer comes with a code fix that will replace `Assert.GreaterOrEqual(actual, expected)` with -`Assert.That(actual, Is.GreaterThanOrEqualTo(expected))`. So the code block above will be changed into. +The analyzer comes with a code fix that will replace `Assert.GreaterOrEqual(actual, expected)` with `Assert.That(actual, +Is.GreaterThanOrEqualTo(expected))`. So the code block above will be changed into. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2029.md b/docs/articles/nunit-analyzers/NUnit2029.md index e14759074..d29d7ed7c 100644 --- a/docs/articles/nunit-analyzers/NUnit2029.md +++ b/docs/articles/nunit-analyzers/NUnit2029.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.LessThan(expected))`, instead of the classic model, `Assert.Less(actual, expected)`. +Consider using the constraint model, `Assert.That(actual, Is.LessThan(expected))`, instead of the classic model, +`Assert.Less(actual, expected)`. ## Motivation -The assert `Assert.Less` from the classic Assert model makes it easy to confuse the `expected` and the `actual` argument, -so this analyzer marks usages of `Assert.Less`. +The assert `Assert.Less` from the classic Assert model makes it easy to confuse the `expected` and the `actual` +argument, so this analyzer marks usages of `Assert.Less`. ```csharp [Test] @@ -29,8 +30,8 @@ public void Test() ## How to fix violations -The analyzer comes with a code fix that will replace `Assert.Less(actual, expected)` with -`Assert.That(actual, Is.LessThan(expected))`. So the code block above will be changed into. +The analyzer comes with a code fix that will replace `Assert.Less(actual, expected)` with `Assert.That(actual, +Is.LessThan(expected))`. So the code block above will be changed into. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2030.md b/docs/articles/nunit-analyzers/NUnit2030.md index ae3debac1..772c32f4b 100644 --- a/docs/articles/nunit-analyzers/NUnit2030.md +++ b/docs/articles/nunit-analyzers/NUnit2030.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.LessThanOrEqualTo(expected))`, instead of the classic model, `Assert.LessOrEqual(actual, expected)`. +Consider using the constraint model, `Assert.That(actual, Is.LessThanOrEqualTo(expected))`, instead of the classic +model, `Assert.LessOrEqual(actual, expected)`. ## Motivation -The assert `Assert.LessOrEqual` from the classic Assert model makes it easy to confuse the `expected` and the `actual` argument, -so this analyzer marks usages of `Assert.LessOrEqual`. +The assert `Assert.LessOrEqual` from the classic Assert model makes it easy to confuse the `expected` and the `actual` +argument, so this analyzer marks usages of `Assert.LessOrEqual`. ```csharp [Test] @@ -29,8 +30,8 @@ public void Test() ## How to fix violations -The analyzer comes with a code fix that will replace `Assert.LessOrEqual(actual, expected)` with -`Assert.That(actual, Is.LessThanOrEqualTo(expected))`. So the code block above will be changed into. +The analyzer comes with a code fix that will replace `Assert.LessOrEqual(actual, expected)` with `Assert.That(actual, +Is.LessThanOrEqualTo(expected))`. So the code block above will be changed into. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2031.md b/docs/articles/nunit-analyzers/NUnit2031.md index 13ccfb2a0..dcc720c4c 100644 --- a/docs/articles/nunit-analyzers/NUnit2031.md +++ b/docs/articles/nunit-analyzers/NUnit2031.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.Not.SameAs(expected))`, instead of the classic model, `Assert.AreNotSame(expected, actual)`. +Consider using the constraint model, `Assert.That(actual, Is.Not.SameAs(expected))`, instead of the classic model, +`Assert.AreNotSame(expected, actual)`. ## Motivation -The assert `Assert.AreNotSame` from the classic Assert model makes it easy to confuse the `expected` and the `actual` argument, -so this analyzer marks usages of `Assert.AreNotSame`. +The assert `Assert.AreNotSame` from the classic Assert model makes it easy to confuse the `expected` and the `actual` +argument, so this analyzer marks usages of `Assert.AreNotSame`. ```csharp [Test] @@ -29,8 +30,8 @@ public void Test() ## How to fix violations -The analyzer comes with a code fix that will replace `Assert.AreNotSame(expected, actual)` with -`Assert.That(actual, Is.Not.SameAs(expected))`. So the code block above will be changed into. +The analyzer comes with a code fix that will replace `Assert.AreNotSame(expected, actual)` with `Assert.That(actual, +Is.Not.SameAs(expected))`. So the code block above will be changed into. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2037.md b/docs/articles/nunit-analyzers/NUnit2037.md index d0ea6584f..b146b8fad 100644 --- a/docs/articles/nunit-analyzers/NUnit2037.md +++ b/docs/articles/nunit-analyzers/NUnit2037.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(collection, Does.Contain(instance))`, instead of the classic model, `Assert.Contains(instance, collection)`. +Consider using the constraint model, `Assert.That(collection, Does.Contain(instance))`, instead of the classic model, +`Assert.Contains(instance, collection)`. ## Motivation -The assert `Assert.Contains` from the classic Assert model makes it easy to confuse the `instance` and the `collection` argument, -so this analyzer marks usages of `Assert.Contains`. +The assert `Assert.Contains` from the classic Assert model makes it easy to confuse the `instance` and the `collection` +argument, so this analyzer marks usages of `Assert.Contains`. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2038.md b/docs/articles/nunit-analyzers/NUnit2038.md index da371a473..256b38ac3 100644 --- a/docs/articles/nunit-analyzers/NUnit2038.md +++ b/docs/articles/nunit-analyzers/NUnit2038.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.InstanceOf(expected))`, instead of the classic model, `Assert.IsInstanceOf(expected, actual)`. +Consider using the constraint model, `Assert.That(actual, Is.InstanceOf(expected))`, instead of the classic model, +`Assert.IsInstanceOf(expected, actual)`. ## Motivation -The assert `Assert.IsInstanceOf` from the classic Assert model makes it easy to confuse the `expected` and the `actual` argument, -so this analyzer marks usages of `Assert.IsInstanceOf`. +The assert `Assert.IsInstanceOf` from the classic Assert model makes it easy to confuse the `expected` and the `actual` +argument, so this analyzer marks usages of `Assert.IsInstanceOf`. ```csharp [Test] @@ -29,8 +30,8 @@ public void Test() ## How to fix violations -The analyzer comes with a code fix that will replace `Assert.IsInstanceOf(expected, actual)` with -`Assert.That(actual, Is.InstanceOf(expected))`. So the code block above will be changed into. +The analyzer comes with a code fix that will replace `Assert.IsInstanceOf(expected, actual)` with `Assert.That(actual, +Is.InstanceOf(expected))`. So the code block above will be changed into. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2039.md b/docs/articles/nunit-analyzers/NUnit2039.md index 49c15459e..c5827f221 100644 --- a/docs/articles/nunit-analyzers/NUnit2039.md +++ b/docs/articles/nunit-analyzers/NUnit2039.md @@ -12,12 +12,13 @@ ## Description -Consider using the constraint model, `Assert.That(actual, Is.Not.InstanceOf(expected))`, instead of the classic model, `Assert.IsNotInstanceOf(expected, actual)`. +Consider using the constraint model, `Assert.That(actual, Is.Not.InstanceOf(expected))`, instead of the classic model, +`Assert.IsNotInstanceOf(expected, actual)`. ## Motivation -The assert `Assert.IsNotInstanceOf` from the classic Assert model makes it easy to confuse the `expected` and the `actual` argument, -so this analyzer marks usages of `Assert.IsNotInstanceOf`. +The assert `Assert.IsNotInstanceOf` from the classic Assert model makes it easy to confuse the `expected` and the +`actual` argument, so this analyzer marks usages of `Assert.IsNotInstanceOf`. ```csharp [Test] @@ -45,7 +46,8 @@ public void Test() ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit2047.md b/docs/articles/nunit-analyzers/NUnit2047.md index e9cc23875..4db83880d 100644 --- a/docs/articles/nunit-analyzers/NUnit2047.md +++ b/docs/articles/nunit-analyzers/NUnit2047.md @@ -12,11 +12,13 @@ ## Description -The `Within` modifier should only be used for numeric or Date/Time arguments or tuples containing only these element types. Using it on other types will not have any effect. +The `Within` modifier should only be used for numeric or Date/Time arguments or tuples containing only these element +types. Using it on other types will not have any effect. ## Motivation -To bring developers' attention to a scenario in which their code is actually having no effect and may reveal that their test is not doing what they expect. +To bring developers' attention to a scenario in which their code is actually having no effect and may reveal that their +test is not doing what they expect. ## How to fix violations @@ -37,7 +39,8 @@ private sealed record Data(int number, double Value); ### Explanation -Using `Within` here doesn't make any sense, because NUnit cannot apply comparison with tolerance to the types we're comparing. +Using `Within` here doesn't make any sense, because NUnit cannot apply comparison with tolerance to the types we're +comparing. ### Fix @@ -61,7 +64,8 @@ private sealed record Data(int number, double Value); ### Via ruleset file -Configure the severity per project, for more info see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +Configure the severity per project, for more info see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit3002.md b/docs/articles/nunit-analyzers/NUnit3002.md index 3bd84f420..98d856d13 100644 --- a/docs/articles/nunit-analyzers/NUnit3002.md +++ b/docs/articles/nunit-analyzers/NUnit3002.md @@ -14,11 +14,12 @@ This rule check diagnostics reported by the CS8618 compiler error: -`CS8618: Non-nullable field '_name_' must contain a non-null value when exiting constructor. Consider declaring the field as nullable.` -`CS8618: Non-nullable property '_Name_' must contain a non-null value when exiting constructor. Consider declaring the property as nullable.` +`CS8618: Non-nullable field '_name_' must contain a non-null value when exiting constructor. Consider declaring the +field as nullable.` `CS8618: Non-nullable property '_Name_' must contain a non-null value when exiting constructor. +Consider declaring the property as nullable.` -If the violating field/property is set in the `SetUp` or `OneTimeSetUp` method. The rule suppresses the error. -This allows for non-nullable fields/properties to be used in a `TestFixture`. +If the violating field/property is set in the `SetUp` or `OneTimeSetUp` method. The rule suppresses the error. This +allows for non-nullable fields/properties to be used in a `TestFixture`. The rule does detect indirect calls, when the field is set in a method called by the `SetUp` or `OneTimeSetUp` methods. @@ -44,9 +45,9 @@ internal sealed class SomeClassFixture } ``` -In the above fixture the compiler would give a warning because `instance` is not set in the constructor. -The suggestion to mark `instance` as nullable would mean that we have to test for null in all `Test` methods -or use the null suppression operator (`!`) everywhere. +In the above fixture the compiler would give a warning because `instance` is not set in the constructor. The suggestion +to mark `instance` as nullable would mean that we have to test for null in all `Test` methods or use the null +suppression operator (`!`) everywhere. ## How to fix violations @@ -59,8 +60,8 @@ The rule has no severity, but can be disabled. ### Via ruleset file -To disable the rule for a project, you need to add a -[ruleset file](https://github.com/nunit/nunit.analyzers/blob/3.8.0/src/nunit.analyzers/DiagnosticSuppressors/NUnit.Analyzers.Suppressions.ruleset) +To disable the rule for a project, you need to add a [ruleset +file](https://github.com/nunit/nunit.analyzers/blob/3.8.0/src/nunit.analyzers/DiagnosticSuppressors/NUnit.Analyzers.Suppressions.ruleset) ```xml @@ -80,7 +81,8 @@ and add it to the project like: ``` -For more info about rulesets see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +For more info about rulesets see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-analyzers/NUnit3004.md b/docs/articles/nunit-analyzers/NUnit3004.md index 479a57fda..402bfdfac 100644 --- a/docs/articles/nunit-analyzers/NUnit3004.md +++ b/docs/articles/nunit-analyzers/NUnit3004.md @@ -16,8 +16,10 @@ Field/Property is Disposed in TearDown or OneTimeTearDown method ## Motivation -The Roslyn analyzer fires [CA1001](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1001) -for classes that have [`IDisposable`](https://learn.microsoft.com/en-us/dotnet/api/system.idisposable) members, but itself is not `IDisposable`. +The Roslyn analyzer fires +[CA1001](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca1001) for classes that have +[`IDisposable`](https://learn.microsoft.com/en-us/dotnet/api/system.idisposable) members, but itself is not +`IDisposable`. Many NUnit tests initialize fields in tests or a `SetUp` method and then `Dispose` them in the `TearDown` method. @@ -32,8 +34,8 @@ The rule has no severity, but can be disabled. ### Via ruleset file -To disable the rule for a project, you need to add a -[ruleset file](https://github.com/nunit/nunit.analyzers/blob/3.8.0/src/nunit.analyzers/DiagnosticSuppressors/NUnit.Analyzers.Suppressions.ruleset) +To disable the rule for a project, you need to add a [ruleset +file](https://github.com/nunit/nunit.analyzers/blob/3.8.0/src/nunit.analyzers/DiagnosticSuppressors/NUnit.Analyzers.Suppressions.ruleset) ```xml @@ -55,7 +57,8 @@ and add it to the project like: ``` -For more info about rulesets see [MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). +For more info about rulesets see +[MSDN](https://learn.microsoft.com/en-us/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules?view=vs-2022). ### Via .editorconfig file diff --git a/docs/articles/nunit-engine/Getting-Started.md b/docs/articles/nunit-engine/Getting-Started.md index 96ffc49c7..6ad1ce5b0 100644 --- a/docs/articles/nunit-engine/Getting-Started.md +++ b/docs/articles/nunit-engine/Getting-Started.md @@ -8,23 +8,35 @@ Building your own test runner? This guide covers the basics of getting up and ru ## Fundamentals -The engine is designed to be accessed through the methods exposed in the `nunit.engine.api` assembly - which is the only assembly which should be referenced by runners wishing to use the engine. The API exposed through this assembly will be maintained in a backwards-compatible way wherever possible. +The engine is designed to be accessed through the methods exposed in the `nunit.engine.api` assembly - which is the only +assembly which should be referenced by runners wishing to use the engine. The API exposed through this assembly will be +maintained in a backwards-compatible way wherever possible. -The actual engine itself is contained within the `nunit.engine` assembly, and its dependencies. This assembly should **not** be referenced by the runners, as methods exposed here could be subject to changes in future versions. Instead, the API should be used to locate and load an appropriate version of the engine, which will return an instance of the `ITestEngine` interface to the runner. +The actual engine itself is contained within the `nunit.engine` assembly, and its dependencies. This assembly should +**not** be referenced by the runners, as methods exposed here could be subject to changes in future versions. Instead, +the API should be used to locate and load an appropriate version of the engine, which will return an instance of the +`ITestEngine` interface to the runner. ## Packages -The NUnit Engine can be found in the [NUnit.Engine NuGet Package](https://www.nuget.org/packages/NUnit.Engine/). It is also included within the .zip file found in [nunit-console repository](https://github.com/nunit/nunit-console/releases) releases. +The NUnit Engine can be found in the [NUnit.Engine NuGet Package](https://www.nuget.org/packages/NUnit.Engine/). It is +also included within the .zip file found in [nunit-console repository](https://github.com/nunit/nunit-console/releases) +releases. ## Using the API -The `TestEngineActivator` class is first used to obtain an instance of the engine. Tests are specified inside a `TestPackage`, which can contain one or many different test assemblies. Settings related to how the tests should be run are attached to the test package. +The `TestEngineActivator` class is first used to obtain an instance of the engine. Tests are specified inside a +`TestPackage`, which can contain one or many different test assemblies. Settings related to how the tests should be run +are attached to the test package. -Once a test package has been created, the engine can generate an instance of an `ITestRunner`, which will be constructed to reflect the structure of your test package. +Once a test package has been created, the engine can generate an instance of an `ITestRunner`, which will be constructed +to reflect the structure of your test package. -Finally, `Run` can be called on the `ITestRunner`, to run tests in the specified package. This will return an `XmlNode` which contains the results of the test run, in the standard [NUnit Test Results](xref:testresultxmlformat) format. +Finally, `Run` can be called on the `ITestRunner`, to run tests in the specified package. This will return an `XmlNode` +which contains the results of the test run, in the standard [NUnit Test Results](xref:testresultxmlformat) format. -The following example shows the simplest path of how to get a copy of the engine, create a runner and run tests using the interfaces: +The following example shows the simplest path of how to get a copy of the engine, create a runner and run tests using +the interfaces: ```csharp // Get an interface to the engine diff --git a/docs/articles/nunit-engine/Index.md b/docs/articles/nunit-engine/Index.md index 1a3b482f7..bfba78136 100644 --- a/docs/articles/nunit-engine/Index.md +++ b/docs/articles/nunit-engine/Index.md @@ -4,9 +4,15 @@ uid: nunitengine # NUnit Engine -The NUnit Engine is the component used as the foundation of any test runner. It contains all the logic required to run tests built against both NUnit 3.X and other frameworks, and exposes an API allowing test runners to interact with the engine and run tests as required. +The NUnit Engine is the component used as the foundation of any test runner. It contains all the logic required to run +tests built against both NUnit 3.X and other frameworks, and exposes an API allowing test runners to interact with the +engine and run tests as required. > [!NOTE] -> The NUnit Engine is a component targeted at advanced users of NUnit, who are building their own test runner, rather than using one of the many existing test runners in the ecosystem. If you are looking to simply run tests that you have written, see the [running tests](xref:runningtests) section. +> The NUnit Engine is a component targeted at advanced users of NUnit, who are building their own test runner, +> rather than using one of the many existing test runners in the ecosystem. If you are looking to simply run tests that +> you have written, see the [running tests](xref:runningtests) section. -The engine exposes [an API](xref:testengineapi) designed to be used by test runners, which will be maintained in a backwards-compatible fashion wherever possible. The engine also hosts various extension points, to allow further customization. +The engine exposes [an API](xref:testengineapi) designed to be used by test runners, which will be maintained in a +backwards-compatible fashion wherever possible. The engine also hosts various extension points, to allow further +customization. diff --git a/docs/articles/nunit-engine/Test-Engine-API.md b/docs/articles/nunit-engine/Test-Engine-API.md index 8847d4787..4e67be25c 100644 --- a/docs/articles/nunit-engine/Test-Engine-API.md +++ b/docs/articles/nunit-engine/Test-Engine-API.md @@ -4,24 +4,31 @@ uid: testengineapi # Test Engine API -The NUnit Test Engine API is our published API for discovering, exploring and executing tests programmatically. Third-party test runners should use the Engine API as the supported method to execute NUnit tests. +The NUnit Test Engine API is our published API for discovering, exploring and executing tests programmatically. +Third-party test runners should use the Engine API as the supported method to execute NUnit tests. ## Overview -The static class [TestEngineActivator](https://github.com/nunit/nunit-console/blob/main/src/NUnitEngine/nunit.engine.api/TestEngineActivator.cs) is used to get an interface to the engine. Its `CreateInstance` member has two overloads, depending on whether a particular minimum version of the engine is required. +The static class +[TestEngineActivator](https://github.com/nunit/nunit-console/blob/main/src/NUnitEngine/nunit.engine.api/TestEngineActivator.cs) +is used to get an interface to the engine. Its `CreateInstance` member has two overloads, depending on whether a +particular minimum version of the engine is required. ```csharp public static ITestEngine CreateInstance(bool unused = false); public static ITestEngine CreateInstance(Version minVersion, bool unused = false); ``` -(The `unused` bool parameter previously allowed users to indicate if wished to restrict usage of global NUnit Engine installations. The latter functionality is no longer available.) +(The `unused` bool parameter previously allowed users to indicate if wished to restrict usage of global NUnit Engine +installations. The latter functionality is no longer available.) -The TestEngineActivator searches for an engine to load in two places. First, the current App Domain Base Directory is searched, and then any path set as the App Domain's `RelativeSearchPath`. +The TestEngineActivator searches for an engine to load in two places. First, the current App Domain Base Directory is +searched, and then any path set as the App Domain's `RelativeSearchPath`. ### Key Interfaces -The runner deals with the engine through a set of interfaces. These are quite general because we hope to avoid many changes to this API. +The runner deals with the engine through a set of interfaces. These are quite general because we hope to avoid many +changes to this API. #### ITestEngine @@ -86,9 +93,11 @@ engine.WorkDirectory = ...; // Defaults to the current directory engine.InternalTraceLevel = ...; // Defaults to off ``` -The engine provides a number of services, some internal and some public. Public services are those for which the interface is publicly defined in the nunit.engine.api assembly, listed later in this document. +The engine provides a number of services, some internal and some public. Public services are those for which the +interface is publicly defined in the nunit.engine.api assembly, listed later in this document. -The final and probably most frequently used method on the interface is `GetRunner`. It takes a `TestPackage` and returns an `ITestRunner` that is appropriate for the options specified. +The final and probably most frequently used method on the interface is `GetRunner`. It takes a `TestPackage` and returns +an `ITestRunner` that is appropriate for the options specified. #### ITestRunner @@ -172,15 +181,22 @@ namespace NUnit.Engine } ``` -For the most common use cases, it isn't necessary to call `Load`, `Unload` or `Reload`. Calling either `Explore`, `Run` or `RunAsync` will cause the tests to be loaded automatically. +For the most common use cases, it isn't necessary to call `Load`, `Unload` or `Reload`. Calling either `Explore`, `Run` +or `RunAsync` will cause the tests to be loaded automatically. -The `Explore` methods returns an `XmlNode` containing the description of all tests found. The `Run` method returns an `XmlNode` containing the results of every test. The XML format for results is the same as that for the exploration of tests, with additional nodes added to indicate the outcome of the test. `RunAsync` returns an `ITestRun` interface, which allows retrieving the XML result when it is complete. +The `Explore` methods returns an `XmlNode` containing the description of all tests found. The `Run` method returns an +`XmlNode` containing the results of every test. The XML format for results is the same as that for the exploration of +tests, with additional nodes added to indicate the outcome of the test. `RunAsync` returns an `ITestRun` interface, +which allows retrieving the XML result when it is complete. -The progress of a run is reported to the `ITestEventListener` passed to the run methods. Notifications received on this interface are strings in XML format, rather than XmlNodes, so that they may be passed directly across a Remoting interface. +The progress of a run is reported to the `ITestEventListener` passed to the run methods. Notifications received on this +interface are strings in XML format, rather than XmlNodes, so that they may be passed directly across a Remoting +interface. #### Engine Services -The engine `Services` property exposes the `IServiceLocator` interface, which allows the runner to use public services of the engine. +The engine `Services` property exposes the `IServiceLocator` interface, which allows the runner to use public services +of the engine. ```csharp namespace NUnit.Engine @@ -217,7 +233,8 @@ The following services are available publicly. | TestFilterService | [ITestFilterService](https://github.com/nunit/nunit-console/blob/main/src/NUnitEngine/nunit.engine.api/ITestFilterService.cs) | Creates properly formed test filters for use by runners | | LoggingService | [ILogging](https://github.com/nunit/nunit-console/blob/main/src/NUnitEngine/nunit.engine.api/ILogging.cs) | Provides centralized internal trace logging for both the engine and runners (Not Yet Implemented) | -The following services are used internally by the engine but are not currently exposed publicly. They potentially could be in the future: +The following services are used internally by the engine but are not currently exposed publicly. They potentially could +be in the future: | Service | Function | |--------------------------|-----------| @@ -230,4 +247,5 @@ The following services are used internally by the engine but are not currently e #### Extensibility Interfaces -The API also contains various interfaces used by engine extensions. More information on these can be found in the [Engine Extensions](xref:engineextensionsindex) section. +The API also contains various interfaces used by engine extensions. More information on these can be found in the +[Engine Extensions](xref:engineextensionsindex) section. diff --git a/docs/articles/nunit-engine/extensions/AvailableExtensions.md b/docs/articles/nunit-engine/extensions/AvailableExtensions.md index 8f0fe7576..5465bd1ea 100644 --- a/docs/articles/nunit-engine/extensions/AvailableExtensions.md +++ b/docs/articles/nunit-engine/extensions/AvailableExtensions.md @@ -4,14 +4,14 @@ uid: availableengineextensions # Available NUnit Engine Extensions -The NUnit team provides several extensions for the engine. They are all available individually as -packages for installation through NuGet and also as Chocolatey packages. Some extensions are also -bundled with specific distributions of the Console runner. +The NUnit team provides several extensions for the engine. They are all available individually as packages for +installation through NuGet and also as Chocolatey packages. Some extensions are also bundled with specific distributions +of the Console runner. ## V2 Result Writer -The V2 Result writer makes it possible to save test results in the older NUnit V2 format, for use -with report programs and integration servers that require that format. +The V2 Result writer makes it possible to save test results in the older NUnit V2 format, for use with report programs +and integration servers that require that format. ### Installation @@ -39,8 +39,8 @@ The V2 Framework Driver allows the engine to run NUnit V2 tests, which is not no ## NUnit Project Loader -The NUnit Project Loader allows the engine to run NUnit projects, which have a file extension of `.nunit`. -If it is not installed, the runner will give an error indicating the file type is unrecognized. +The NUnit Project Loader allows the engine to run NUnit projects, which have a file extension of `.nunit`. If it is not +installed, the runner will give an error indicating the file type is unrecognized. ### Installation @@ -50,17 +50,16 @@ If it is not installed, the runner will give an error indicating the file type i ### Usage - Create the project in any editor, following the NUnit project format specification. - You may also use the NUnit Project Editor, a legacy V2 program, since the format has - not changed in NUnit 3. + Create the project in any editor, following the NUnit project format specification. You may also use the NUnit Project + Editor, a legacy V2 program, since the format has not changed in NUnit 3. ## Visual Studio Project Loader -The VS Project Loader allows the engine to load tests from a Visual Studio -project or solution. +The VS Project Loader allows the engine to load tests from a Visual Studio project or solution. > [!NOTE] -> When used with a solution file, the extension tries to avoid loading assemblies that do not contain tests, through the use of heuristics. This may fail in certain circumstances. +> When used with a solution file, the extension tries to avoid loading assemblies that do not contain tests, +> through the use of heuristics. This may fail in certain circumstances. ### Installation @@ -74,8 +73,8 @@ project or solution. ## Teamcity Test Listener -The Teamcity Test Listener is used to run NUnit under TeamCity, providing -special output messages, which TeamCity is able to interpret. +The Teamcity Test Listener is used to run NUnit under TeamCity, providing special output messages, which TeamCity is +able to interpret. ### Installation @@ -84,9 +83,10 @@ special output messages, which TeamCity is able to interpret. * Also bundled with the `NUnit.Console` NuGet and MSI packages. > [!WARNING] -> We plan to stop bundling the TeamCity extension with the release of NUnit 4.0. When that happens, individual installation will be required in order to use it. +> We plan to stop bundling the TeamCity extension with the release of NUnit 4.0. When that happens, +> individual installation will be required in order to use it. ### Usage - This extension must be activated for a particular test run. When running under the - NUnit 3 Console runner, use the `--teamcity` option to activate it. + This extension must be activated for a particular test run. When running under the NUnit 3 Console runner, use the + `--teamcity` option to activate it. diff --git a/docs/articles/nunit-engine/extensions/Installing-Extensions.md b/docs/articles/nunit-engine/extensions/Installing-Extensions.md index d4193762b..7eed8df8e 100644 --- a/docs/articles/nunit-engine/extensions/Installing-Extensions.md +++ b/docs/articles/nunit-engine/extensions/Installing-Extensions.md @@ -6,15 +6,22 @@ uid: installingextensions Extensions are located by the engine by use of an `.addins` file. -For certain package managers, default `.addins` have been created such that when both engine and extensions are installed from the same package manager, all extensions are installed automatically. Currently, this includes NuGet and Chocolatey. +For certain package managers, default `.addins` have been created such that when both engine and extensions are +installed from the same package manager, all extensions are installed automatically. Currently, this includes NuGet and +Chocolatey. -In other cases, the user may need to create a new `.addins` file, or edit an existing one. The behavior of the `.addins` file is covered below. +In other cases, the user may need to create a new `.addins` file, or edit an existing one. The behavior of the `.addins` +file is covered below. ## The .addins file -`.addins` files are used to locate engine extensions. Either a single `.addins` file can be used to list all extensions and directories to be searched, or multiple files. `.addins` files can also be chained together -- allowing multiple levels of redirection. +`.addins` files are used to locate engine extensions. Either a single `.addins` file can be used to list all extensions +and directories to be searched, or multiple files. `.addins` files can also be chained together -- allowing multiple +levels of redirection. -Each line of the `.addins` file contains the path of an extension assembly or a directory containing assemblies. Wildcards may be used for assembly entries and relative paths are interpreted based on the location of the `.addins` file. +Each line of the `.addins` file contains the path of an extension assembly or a directory containing assemblies. +Wildcards may be used for assembly entries and relative paths are interpreted based on the location of the `.addins` +file. The following is an example of a possible `.addins` file, with comments indicating what each line does: @@ -29,6 +36,11 @@ special/myassembly.dll # include a specific dll in a special directory # in most cases ``` -Any assemblies specified in a `.addins` file will be scanned fully, looking for addins and extensions. Any directories specified will be browsed, first looking for any `.addins` files. If one or more files are found, the content of the files will direct all further browsing. If no such file is found, then all `.dll` files in the directory will be scanned, just as if a `.addins` file contained "*.dll." +Any assemblies specified in a `.addins` file will be scanned fully, looking for addins and extensions. Any directories +specified will be browsed, first looking for any `.addins` files. If one or more files are found, the content of the +files will direct all further browsing. If no such file is found, then all `.dll` files in the directory will be +scanned, just as if a `.addins` file contained "*.dll." -Note that if a specific assembly is listed in the `.addins` file which is found not to be a valid extension, an exception will be thrown by the engine. This exception is suppressed in the cases of wildcard paths, where it is considered valid to find no extensions under the path. +Note that if a specific assembly is listed in the `.addins` file which is found not to be a valid extension, an +exception will be thrown by the engine. This exception is suppressed in the cases of wildcard paths, where it is +considered valid to find no extensions under the path. diff --git a/docs/articles/nunit-engine/extensions/creating-extensions/Event-Listeners.md b/docs/articles/nunit-engine/extensions/creating-extensions/Event-Listeners.md index 254833363..488b34986 100644 --- a/docs/articles/nunit-engine/extensions/creating-extensions/Event-Listeners.md +++ b/docs/articles/nunit-engine/extensions/creating-extensions/Event-Listeners.md @@ -4,7 +4,9 @@ uid: eventlisteners # Event Listeners -**Event Listeners** are extensions that respond to specific events occurring during the running of a test. They implement the `ITestEventListener` interface. NUnit itself makes extensive use of this interface when running tests. By creating an extension, user code may also respond to test events. +**Event Listeners** are extensions that respond to specific events occurring during the running of a test. They +implement the `ITestEventListener` interface. NUnit itself makes extensive use of this interface when running tests. By +creating an extension, user code may also respond to test events. The definition of an Event Listener extension will look something like this: @@ -17,7 +19,9 @@ public class MyEventListener : ITestEventListener ``` > [!NOTE] -> The `EngineVersion` property is used to document the fact that the event listener extension point was only added to the engine with version 3.4. Its function here is purely documentary because the `EngineVersion` property itself was also added in version 3.4. Event listeners should not be installed with earlier versions. +> The `EngineVersion` property is used to document the fact that the event listener extension point was only +> added to the engine with version 3.4. Its function here is purely documentary because the `EngineVersion` property +> itself was also added in version 3.4. Event listeners should not be installed with earlier versions. The `ITestEventListener` interface is defined as follows: @@ -51,4 +55,6 @@ The argument to `OnTestEvent` is an XML-formatted string, with a different top-l * Start of a test case - `` * End of a test case - `` -The XML report signalling the end of a test case contains all available information, including the result. The start events only provide basic identifying information. See [XML Formats](xref:xmlformats) for a full description of each report +The XML report signalling the end of a test case contains all available information, including the result. The start +events only provide basic identifying information. See [XML Formats](xref:xmlformats) for a full description of each +report diff --git a/docs/articles/nunit-engine/extensions/creating-extensions/Framework-Drivers.md b/docs/articles/nunit-engine/extensions/creating-extensions/Framework-Drivers.md index 089ecd635..43c92c389 100644 --- a/docs/articles/nunit-engine/extensions/creating-extensions/Framework-Drivers.md +++ b/docs/articles/nunit-engine/extensions/creating-extensions/Framework-Drivers.md @@ -4,17 +4,25 @@ uid: frameworkdrivers # Framework Drivers -**Framework Drivers** are extensions that know how to create a driver for a particular framework. These allow the NUnit Engine to run tests for multiple different test frameworks. The NUnit engine provides drivers for both NUnit 3.x, whilst a separate extension can be installed to run NUnit 2.x frameworks. Third parties may provide drivers for other frameworks by creating extensions. +**Framework Drivers** are extensions that know how to create a driver for a particular framework. These allow the NUnit +Engine to run tests for multiple different test frameworks. The NUnit engine provides drivers for both NUnit 3.x, whilst +a separate extension can be installed to run NUnit 2.x frameworks. Third parties may provide drivers for other +frameworks by creating extensions. ## Implementation Details -The framework driver API is encapsulated in the `IDriverFactory` and `IFrameworkDriver` interfaces, which must be implemented by all framework driver extensions to the engine. +The framework driver API is encapsulated in the `IDriverFactory` and `IFrameworkDriver` interfaces, which must be +implemented by all framework driver extensions to the engine. ### IDriverFactory -The `IDriverFactory` interface is called by the engine to determine if a particular extension is able to create a driver for a particular framework assembly. The engine passes the AssemblyName of each assembly referenced by the test assembly to the factory to see if it is a supported framework. If it finds one, then it uses that driver. If not, it goes on to check the next driver extension. +The `IDriverFactory` interface is called by the engine to determine if a particular extension is able to create a driver +for a particular framework assembly. The engine passes the AssemblyName of each assembly referenced by the test assembly +to the factory to see if it is a supported framework. If it finds one, then it uses that driver. If not, it goes on to +check the next driver extension. -The `ExtensionPoint` for framework drivers uses the Path "NUnit.Engine.DriverService" and accepts an extension of Type `NUnit.Engine.Extensibility.IDriverFactory`. The definition of a driver factory might look like this: +The `ExtensionPoint` for framework drivers uses the Path "NUnit.Engine.DriverService" and accepts an extension of Type +`NUnit.Engine.Extensibility.IDriverFactory`. The definition of a driver factory might look like this: ```csharp [Extension] @@ -40,9 +48,12 @@ public interface IDriverFactory ### IFrameworkDriver -The `IFrameworkDriver` interface is returned from `IDriverFactory` and is the key interface for actually loading, exploring and running the tests in the test assembly. In theory, a single driver factory could return different drivers in different situations, but we expect a one-to-one mapping of factories to drivers to be most commonly used. +The `IFrameworkDriver` interface is returned from `IDriverFactory` and is the key interface for actually loading, +exploring and running the tests in the test assembly. In theory, a single driver factory could return different drivers +in different situations, but we expect a one-to-one mapping of factories to drivers to be most commonly used. -As designed, the `IFrameworkDriver` interface maps most directly to the requirements of the NUnit 3 framework. Drivers for other frameworks need to function as an adapter to run tests and return understandable results to the engine. +As designed, the `IFrameworkDriver` interface maps most directly to the requirements of the NUnit 3 framework. Drivers +for other frameworks need to function as an adapter to run tests and return understandable results to the engine. The `IFrameworkDriver` interface is defined as follows: @@ -68,13 +79,17 @@ public interface IFrameworkDriver void StopRun(bool force); ``` -The strings returned by Run and Explore are XML representations and the filter is also in XML format. See the source code for NUnit3FrameworkDriver and NUnit2FrameworkDriver for sample code. +The strings returned by Run and Explore are XML representations and the filter is also in XML format. See the source +code for NUnit3FrameworkDriver and NUnit2FrameworkDriver for sample code. -The filter argument passed to several of the interface methods is an XML string representing the filter. See [Test Filters](xref:testFilters) for a description of the format, which is directly understood by the NUnit 3 framework, but which must be converted by the driver to something that is understood by other frameworks. +The filter argument passed to several of the interface methods is an XML string representing the filter. See [Test +Filters](xref:testFilters) for a description of the format, which is directly understood by the NUnit 3 framework, but +which must be converted by the driver to something that is understood by other frameworks. ### ITestEventListener -The `ITestEventListener` interface is implemented by the Engine and used by each driver to report significant events during the execution of tests. +The `ITestEventListener` interface is implemented by the Engine and used by each driver to report significant events +during the execution of tests. ```csharp namespace NUnit.Engine diff --git a/docs/articles/nunit-engine/extensions/creating-extensions/Index.md b/docs/articles/nunit-engine/extensions/creating-extensions/Index.md index b8ce66ca2..472547c0a 100644 --- a/docs/articles/nunit-engine/extensions/creating-extensions/Index.md +++ b/docs/articles/nunit-engine/extensions/creating-extensions/Index.md @@ -4,7 +4,8 @@ uid: creatingengineextensionsindex # Creating Engine Extensions -The NUnit Test Engine uses a plugin architecture that allows users and third parties to add new functionality to the engine. The extensibility model defines a number of Extension Points to which Extensions may be added. +The NUnit Test Engine uses a plugin architecture that allows users and third parties to add new functionality to the +engine. The extensibility model defines a number of Extension Points to which Extensions may be added. There are currently four extension points: @@ -13,4 +14,6 @@ There are currently four extension points: * [Framework Drivers](Framework-Drivers.md) * [Event Listeners](Event-Listeners.md) -Extensions are generally created in their own assemblies, with some shared characteristics described in [Writing Engine Extensions](xref:writingengineextensions). They then need to be installed to the engine, which is covered in [Installing Engine Extensions](xref:installingextensions). +Extensions are generally created in their own assemblies, with some shared characteristics described in [Writing Engine +Extensions](xref:writingengineextensions). They then need to be installed to the engine, which is covered in [Installing +Engine Extensions](xref:installingextensions). diff --git a/docs/articles/nunit-engine/extensions/creating-extensions/Project-Loaders.md b/docs/articles/nunit-engine/extensions/creating-extensions/Project-Loaders.md index 169fc14db..ff0d13805 100644 --- a/docs/articles/nunit-engine/extensions/creating-extensions/Project-Loaders.md +++ b/docs/articles/nunit-engine/extensions/creating-extensions/Project-Loaders.md @@ -4,12 +4,15 @@ uid: projectloaders # Project Loaders -**Project Loaders** are extensions that know how to load a project in a particular format and create a package suitable for running tests under NUnit. The NUnit Organization itself provides two of them: +**Project Loaders** are extensions that know how to load a project in a particular format and create a package suitable +for running tests under NUnit. The NUnit Organization itself provides two of them: * NUnitProjectLoader * VisualStudioProjectLoader -The extension point for project loaders accepts extensions that implement the `NUnit.Engine.Extensibility.IProjectLoader` interface. The definition of a project loader extension might look something like the following... +The extension point for project loaders accepts extensions that implement the +`NUnit.Engine.Extensibility.IProjectLoader` interface. The definition of a project loader extension might look something +like the following... ```csharp [Extension] @@ -97,4 +100,5 @@ public interface IProject } ``` -`TestPackage` is defined in the `nunit.engine.api` assembly and includes a list of assemblies together with a dictionary of settings used by the package. +`TestPackage` is defined in the `nunit.engine.api` assembly and includes a list of assemblies together with a dictionary +of settings used by the package. diff --git a/docs/articles/nunit-engine/extensions/creating-extensions/Result-Writers.md b/docs/articles/nunit-engine/extensions/creating-extensions/Result-Writers.md index aa2866959..1fe8ce32b 100644 --- a/docs/articles/nunit-engine/extensions/creating-extensions/Result-Writers.md +++ b/docs/articles/nunit-engine/extensions/creating-extensions/Result-Writers.md @@ -4,7 +4,9 @@ uid: resultwriters # Result Writers -**Result Writers** take the result of a test run, in NUnit 3 XML format, and use it to create a result file in some other format. The NUnit Organization itself provides a two result writers, one to create output in NUnit V2 format and another to write test cases to the console. The definition of a result writer extension might look something like this: +**Result Writers** take the result of a test run, in NUnit 3 XML format, and use it to create a result file in some +other format. The NUnit Organization itself provides a two result writers, one to create output in NUnit V2 format and +another to write test cases to the console. The definition of a result writer extension might look something like this: ```csharp [Extension] @@ -15,7 +17,8 @@ public class CustomResultWriterFactory : IResultWriter } ``` -An `ExtensionPropertyAttribute` must be provided giving the name of the format you support. Users would access the format from the NUnit Console command-line by using that name in a result specification, such as: +An `ExtensionPropertyAttribute` must be provided giving the name of the format you support. Users would access the +format from the NUnit Console command-line by using that name in a result specification, such as: ```cmd nunit-console test.dll --result=CustomResult.xml;format=custom @@ -54,4 +57,6 @@ public interface IResultWriter } ``` -The engine calls the `CheckWritability` method at the start of the run, before executing any tests. The `WriteResultFile` method is called after the run is complete. The writer may check writability in any way desired, including writing an abbreviated output file, which it will later overwrite. +The engine calls the `CheckWritability` method at the start of the run, before executing any tests. The +`WriteResultFile` method is called after the run is complete. The writer may check writability in any way desired, +including writing an abbreviated output file, which it will later overwrite. diff --git a/docs/articles/nunit-engine/extensions/creating-extensions/Writing-Engine-Extensions.md b/docs/articles/nunit-engine/extensions/creating-extensions/Writing-Engine-Extensions.md index 78d71314d..f360ed378 100644 --- a/docs/articles/nunit-engine/extensions/creating-extensions/Writing-Engine-Extensions.md +++ b/docs/articles/nunit-engine/extensions/creating-extensions/Writing-Engine-Extensions.md @@ -4,7 +4,8 @@ uid: writingengineextensions # Writing Engine Extensions -This page gives general information that applies to all types of extensions you may want to write. The individual pages for each type of extension give specific details. +This page gives general information that applies to all types of extensions you may want to write. The individual pages +for each type of extension give specific details. ## Extension structure @@ -33,20 +34,27 @@ public class MyExtension : IProjectLoader The `ExtensionAttribute` has four named properties, all optional: -* **Path** This is a string that uniquely identifies the extension point to which the extension applies. It is only rarely needed, since NUnit can usually deduce the type of extension based on what interface is implemented by the extension class. +* **Path** This is a string that uniquely identifies the extension point to which the extension applies. It is only + rarely needed, since NUnit can usually deduce the type of extension based on what interface is implemented by the + extension class. * **Description** An optional description of what the extension does. -* **Enabled** A boolean flag indicating whether the extension is enabled. This defaults to true. The setting is used by advanced extensions with functionality that is turned on and off depending on user input. +* **Enabled** A boolean flag indicating whether the extension is enabled. This defaults to true. The setting is used by + advanced extensions with functionality that is turned on and off depending on user input. -* **EngineVersion** The minimum engine version supported by the extension. Although optional, you should use this property if your extension will not work with all versions of the engine. If you don't use it and your extension requires engine services that are not present, then it might throw an exception or cause other errors. +* **EngineVersion** The minimum engine version supported by the extension. Although optional, you should use this + property if your extension will not work with all versions of the engine. If you don't use it and your extension + requires engine services that are not present, then it might throw an exception or cause other errors. - > [!NOTE] - > Only engine versions 3.4 or later check the `EngineVersion` property. The only way to avoid errors in the case of lower engine versions is to not install such extensions. +> [!NOTE] +> Only engine versions 3.4 or later check the `EngineVersion` property. The only way to avoid errors in the +> case of lower engine versions is to not install such extensions. ## ExtensionPropertyAttribute -The `ExtensionPropertyAttribute` is used to provide additional meta-data to the engine, without the need for the engine to load each extension. The usages of `ExtensionPropertyAttribute` differ per type of extension. +The `ExtensionPropertyAttribute` is used to provide additional meta-data to the engine, without the need for the engine +to load each extension. The usages of `ExtensionPropertyAttribute` differ per type of extension. Below is an example of how the attribute would be used for an `IProjectLoader` extension: @@ -59,7 +67,10 @@ public class NUnitProjectLoader : IProjectLoader } ``` -By use of the `ExtensionPropertyAttribute` NUnit is able to postpone loading the extension until the user actually uses a file of type `.nunit`. If the extension is never needed, then it won't be loaded at all. For information about what properties are used by each extension point, see the individual pages for each type of extension. +By use of the `ExtensionPropertyAttribute` NUnit is able to postpone loading the extension until the user actually uses +a file of type `.nunit`. If the extension is never needed, then it won't be loaded at all. For information about what +properties are used by each extension point, see the individual pages for each type of extension. > [!NOTE] -> Extensions are usually created each in their own assembly for efficiency. It's possible to have several related extensions in the same assembly, but they will all be loaded into memory as soon as one is used. +> Extensions are usually created each in their own assembly for efficiency. It's possible to have several +> related extensions in the same assembly, but they will all be loaded into memory as soon as one is used. diff --git a/docs/articles/nunit-engine/release-notes.md b/docs/articles/nunit-engine/release-notes.md index a06e06e6a..78103fb2c 100644 --- a/docs/articles/nunit-engine/release-notes.md +++ b/docs/articles/nunit-engine/release-notes.md @@ -11,7 +11,8 @@ This release fixes several critical or high-priority bugs in the 3.16.0 release. ### Bugs - [__#1271__](https://github.com/nunit/nunit-console/issues/1271) Install dotnet tool failed -- [__#1274__](https://github.com/nunit/nunit-console/issues/1274) NUnit Console won't run unless .NET Desktop and ASP.NET Runtimes are installed +- [__#1274__](https://github.com/nunit/nunit-console/issues/1274) NUnit Console won't run unless .NET Desktop and + ASP.NET Runtimes are installed - [__#1275__](https://github.com/nunit/nunit-console/issues/1275) Missing assembly in NUnit.Engine nuget package - [__#1277__](https://github.com/nunit/nunit-console/issues/1277) NUnit does not work without .NET Core @@ -21,26 +22,37 @@ This release fixes several critical or high-priority bugs in the 3.16.0 release. ## NUnit Console & Engine 3.16.0 - November 14, 2022 -Further releases in the 3.x series were not anticipated after 3.15. However, since a number of new features and enhancements have been implemented, -we are releasing version 3.16 of the engine and console runner. +Further releases in the 3.x series were not anticipated after 3.15. However, since a number of new features and +enhancements have been implemented, we are releasing version 3.16 of the engine and console runner. -This release incorporates support for executing tests under .NET 7.0. The runner itself is now built for .NET 4.6.2 rather than .NET 2.0. -Substantial changes have been made in the location of dependencies when running under .NET Core. +This release incorporates support for executing tests under .NET 7.0. The runner itself is now built for .NET 4.6.2 +rather than .NET 2.0. Substantial changes have been made in the location of dependencies when running under .NET Core. ### Bugs -- [__#291__](https://github.com/nunit/nunit-console/issues/291) Error running tests from assembly built using VS2017 csproj file format -- [__#299__](https://github.com/nunit/nunit-console/issues/299) Attempting to target too low a framework throws exception -- [__#1130__](https://github.com/nunit/nunit-console/issues/1130) v3.14 fails with target framework net461 ... net48 on linux (ArgumentException: The net-4.6.1 framework is not available.), but v3.12 works well -- [__#1176__](https://github.com/nunit/nunit-console/issues/1176) Exception when targeting .NET Framework with .NET 7 installed -- [__#1178__](https://github.com/nunit/nunit-console/issues/1178) Running tests with nunit3-console version 3.15.0 generates empty log files +- [__#291__](https://github.com/nunit/nunit-console/issues/291) Error running tests from assembly built using VS2017 + csproj file format +- [__#299__](https://github.com/nunit/nunit-console/issues/299) Attempting to target too low a framework throws + exception +- [__#1130__](https://github.com/nunit/nunit-console/issues/1130) v3.14 fails with target framework net461 ... net48 on + linux (ArgumentException: The net-4.6.1 framework is not available.), but v3.12 works well +- [__#1176__](https://github.com/nunit/nunit-console/issues/1176) Exception when targeting .NET Framework with .NET 7 + installed +- [__#1178__](https://github.com/nunit/nunit-console/issues/1178) Running tests with nunit3-console version 3.15.0 + generates empty log files - [__#1180__](https://github.com/nunit/nunit-console/issues/1180) NUnit Engine 3.15.0 cannot load the test assembly -- [__#1182__](https://github.com/nunit/nunit-console/issues/1182) Running tests using the VS Solution results in an exception if any projects target .NET Standard -- [__#1183__](https://github.com/nunit/nunit-console/issues/1183) Build hangs when test spawns processes which do not terminate properly -- [__#1185__](https://github.com/nunit/nunit-console/issues/1185) 3.15.0 - MSI package is unable to acquire remote process agent -- [__#1203__](https://github.com/nunit/nunit-console/issues/1203) NUnit Console 3.15.2: Could not load file or assembly "System.Windows.Forms" -- [__#1206__](https://github.com/nunit/nunit-console/issues/1206) NUnit.Engine.NUnitEngineException when spaces in agent file path -- [__#1208__](https://github.com/nunit/nunit-console/issues/1208) Inconsistencies between nunit3-console and running the project via Visual Studio +- [__#1182__](https://github.com/nunit/nunit-console/issues/1182) Running tests using the VS Solution results in an + exception if any projects target .NET Standard +- [__#1183__](https://github.com/nunit/nunit-console/issues/1183) Build hangs when test spawns processes which do not + terminate properly +- [__#1185__](https://github.com/nunit/nunit-console/issues/1185) 3.15.0 - MSI package is unable to acquire remote + process agent +- [__#1203__](https://github.com/nunit/nunit-console/issues/1203) NUnit Console 3.15.2: Could not load file or assembly + "System.Windows.Forms" +- [__#1206__](https://github.com/nunit/nunit-console/issues/1206) NUnit.Engine.NUnitEngineException when spaces in agent + file path +- [__#1208__](https://github.com/nunit/nunit-console/issues/1208) Inconsistencies between nunit3-console and running the + project via Visual Studio - [__#1217__](https://github.com/nunit/nunit-console/issues/1217) Assembly loading deduplication - [__#1225__](https://github.com/nunit/nunit-console/issues/1225) Restore netcoreapp3.1 build to the engine package @@ -49,14 +61,17 @@ Substantial changes have been made in the location of dependencies when running - [__#1118__](https://github.com/nunit/nunit-console/issues/1118) Reorganize build output (bin) directories - [__#1244__](https://github.com/nunit/nunit-console/pull/1244) Upgrade Cake.Tool to 2.3.0 - [__#1246__](https://github.com/nunit/nunit-console/issues/1246) Reduce build targets for nunit.engine.core assembly -- [__#1254__](https://github.com/nunit/nunit-console/pull/1254) Get Linux build working under Azure - tests still not run +- [__#1254__](https://github.com/nunit/nunit-console/pull/1254) Get Linux build working under Azure - tests still not + run - [__#1255__](https://github.com/nunit/nunit-console/pull/1255) Get MacOS build working in Azure - [__#1257__](https://github.com/nunit/nunit-console/pull/1257) Enable testing under MacOS on Azure ### Enhancements -- [__#941__](https://github.com/nunit/nunit-console/issues/941) Allow netcoreapp agent to work with non-standard dotnet install locations -- [__#1223__](https://github.com/nunit/nunit-console/issues/1223) Exception when previously unknown .NET Core runtime is found on machine +- [__#941__](https://github.com/nunit/nunit-console/issues/941) Allow netcoreapp agent to work with non-standard dotnet + install locations +- [__#1223__](https://github.com/nunit/nunit-console/issues/1223) Exception when previously unknown .NET Core runtime is + found on machine - [__#1224__](https://github.com/nunit/nunit-console/issues/1224) Change name of NUnit Net Core Runner executable - [__#1243__](https://github.com/nunit/nunit-console/issues/1243) Upgrade our .Net 7.0 assemblies to RC 2 @@ -70,13 +85,16 @@ Substantial changes have been made in the location of dependencies when running Release primarily to correct a critical bug arising when .NET 7.0 is installed. -__Note:__ There is no 3.15.1 release because a 3.15.1 package identical to 3.15.0 was accidentally uploaded to NuGet.org when 3.15 was released. +__Note:__ There is no 3.15.1 release because a 3.15.1 package identical to 3.15.0 was accidentally uploaded to NuGet.org +when 3.15 was released. ### Bugs -* [__#1178__](https://github.com/nunit/nunit-console/issues/1178) Running tests with nunit3-console version 3.15.0 generates empty log files +* [__#1178__](https://github.com/nunit/nunit-console/issues/1178) Running tests with nunit3-console version 3.15.0 + generates empty log files * [__#1193__](https://github.com/nunit/nunit-console/issues/1193) Prevent Crash under .NET 7.0 in 3.15.1 build -* [__#1196__](https://github.com/nunit/nunit-console/issues/1196) Modify build script to support continued version 3 releases where needed +* [__#1196__](https://github.com/nunit/nunit-console/issues/1196) Modify build script to support continued version 3 + releases where needed ## NUnit Console & Engine 3.15 - February 10, 2022 @@ -86,16 +104,20 @@ Version 3.15.0 is expected to be the final release in the 3.x series. ## NUnit Console & Engine 3.15 Beta 1 - February 6, 2022 -Beta release of version 3.15.0 of the Console Runner. Both the standard runner and the dotnet CLI command are now able to run tests under .Net 6.0. +Beta release of version 3.15.0 of the Console Runner. Both the standard runner and the dotnet CLI command are now able +to run tests under .Net 6.0. * [__#1017__](https://github.com/nunit/nunit-console/issues/1017) Should we change 'master' to 'main'? -* [__#1026__](https://github.com/nunit/nunit-console/issues/1026) Make NUnit.Engine.Internal.Tests.PathUtilTests_Windows.SamePathOrUnder work under ubuntu-latest +* [__#1026__](https://github.com/nunit/nunit-console/issues/1026) Make + NUnit.Engine.Internal.Tests.PathUtilTests_Windows.SamePathOrUnder work under ubuntu-latest * [__#1044__](https://github.com/nunit/nunit-console/issues/1044) Agent for .NET 6.0 * [__#1050__](https://github.com/nunit/nunit-console/issues/1050) More discrete logging * [__#1087__](https://github.com/nunit/nunit-console/issues/1087) Switch all engine tests to NUnitLite -* [__#1094__](https://github.com/nunit/nunit-console/issues/1094) CreateDraftRelease command should run locally without a release branch +* [__#1094__](https://github.com/nunit/nunit-console/issues/1094) CreateDraftRelease command should run locally without + a release branch * [__#1095__](https://github.com/nunit/nunit-console/issues/1095) Allow single-letter options for cake script -* [__#1096__](https://github.com/nunit/nunit-console/issues/1096) Symbol package validation failing for NUnit.ConsoleRunner.NetCore +* [__#1096__](https://github.com/nunit/nunit-console/issues/1096) Symbol package validation failing for + NUnit.ConsoleRunner.NetCore * [__#1108__](https://github.com/nunit/nunit-console/issues/1108) Generate AssemblyInfo files from csproj * [__#1112__](https://github.com/nunit/nunit-console/issues/1112) Use VS2022 for CI Build * [__#1123__](https://github.com/nunit/nunit-console/issues/1123) NETCORE Console Runner should target .NET 6.0 @@ -103,35 +125,42 @@ Beta release of version 3.15.0 of the Console Runner. Both the standard runner a ## NUnit Console & Engine 3.14 - January 15, 2022 -This release features a new agent for tests targeting .NET 5.0. In addition, automation of our publication and release process -is now complete from creation of a draft release through releasing to production on GitHub. While this doesn't impact users directly, -it will allow us to speed up the introduction of new features in coming releases. +This release features a new agent for tests targeting .NET 5.0. In addition, automation of our publication and release +process is now complete from creation of a draft release through releasing to production on GitHub. While this doesn't +impact users directly, it will allow us to speed up the introduction of new features in coming releases. * [570](https://github.com/nunit/nunit-console/issues/570) Where are the checksums for your downloads? -* [1012](https://github.com/nunit/nunit-console/issues/1012) Automatically roll-forward if no .NET Core 3.1 runtime available +* [1012](https://github.com/nunit/nunit-console/issues/1012) Automatically roll-forward if no .NET Core 3.1 runtime + available * [1048](https://github.com/nunit/nunit-console/issues/1048) Agent for Net 5.0 * [1057](https://github.com/nunit/nunit-console/issues/1057) Automate all package publication and release * [1075](https://github.com/nunit/nunit-console/issues/1075) Separate nunit.engine.core.tests from nunit.engine.tests * [1084](https://github.com/nunit/nunit-console/issues/1084) Eliminate Packaging on Azure -* [1090](https://github.com/nunit/nunit-console/issues/1090) Test of --debug-agent option fails under linux Debug configuration +* [1090](https://github.com/nunit/nunit-console/issues/1090) Test of --debug-agent option fails under linux Debug + configuration ## NUnit Console & Engine 3.13 - November 30, 2021 -This is the first release of the NUnit Console Runner, `nunit3-console.exe`, which allows running of both .NET Framework and .NET Core tests, -either separately or in combination. The `nunit3-console.exe` runner executes under the .NET Framework but is able to launch .NET Core agents -and communicate with them over a TCP connection. +This is the first release of the NUnit Console Runner, `nunit3-console.exe`, which allows running of both .NET Framework +and .NET Core tests, either separately or in combination. The `nunit3-console.exe` runner executes under the .NET +Framework but is able to launch .NET Core agents and communicate with them over a TCP connection. -A second major feature in this release is engine support for preemptive cancellation when the normal approach of requesting the test run to -self-terminate doesn't work. This is an engine feature, available to any runners supporting cancellation. +A second major feature in this release is engine support for preemptive cancellation when the normal approach of +requesting the test run to self-terminate doesn't work. This is an engine feature, available to any runners supporting +cancellation. -* [382](https://github.com/nu__Bugs__nit/nunit-console/issues/382) Only 1 agent running with multiple projects and --process=Multiple -* [418](https://github.com/nunit/nunit-console/issues/418) .config files not loaded when using an .nunit project file and --process=Multiple +* [382](https://github.com/nu__Bugs__nit/nunit-console/issues/382) Only 1 agent running with multiple projects and + --process=Multiple +* [418](https://github.com/nunit/nunit-console/issues/418) .config files not loaded when using an + .nunit project file and --process=Multiple * [551](https://github.com/nunit/nunit-console/issues/551) Make engine easier to Debug * [609](https://github.com/nunit/nunit-console/issues/609) Run after Reload reports assemblies multiple times * [642](https://github.com/nunit/nunit-console/issues/642) Engine needs preemptive cancellation * [726](https://github.com/nunit/nunit-console/issues/726) Remove .NET Standard 1.6 build -* [764](https://github.com/nunit/nunit-console/issues/764) Error: Found two different objects associated with the same URI, /xxxxx/TestAgency -* [789](https://github.com/nunit/nunit-console/issues/789) DirectoryFinder.GetDirectories throws for a path with the drive specified +* [764](https://github.com/nunit/nunit-console/issues/764) Error: Found two different objects associated with the same + URI, /xxxxx/TestAgency +* [789](https://github.com/nunit/nunit-console/issues/789) DirectoryFinder.GetDirectories throws for a path with the + drive specified * [803](https://github.com/nunit/nunit-console/issues/803) Remove CHANGES.TXT to simplify release process * [828](https://github.com/nunit/nunit-console/issues/828) Reported issues with dependency loading in .NET Core Console * [852](https://github.com/nunit/nunit-console/issues/852) No tests of .NET Core 3.1 packages @@ -142,88 +171,122 @@ self-terminate doesn't work. This is an engine feature, available to any runners * [898](https://github.com/nunit/nunit-console/issues/898) Removed support for .NET Core 1.1 * [904](https://github.com/nunit/nunit-console/issues/904) The test-run element is missing a count of warnings * [908](https://github.com/nunit/nunit-console/issues/908) Known Vulnerability in System.Xml.XPath.XmlDocument -* [915](https://github.com/nunit/nunit-console/issues/915) StackOverflowException in console-runner when addins-file contains "./" or ".\" +* [915](https://github.com/nunit/nunit-console/issues/915) StackOverflowException in console-runner when addins-file + contains "./" or ".\" * [923](https://github.com/nunit/nunit-console/issues/923) Agent communication layer * [933](https://github.com/nunit/nunit-console/issues/933) Update TestCentric MetaData dependency * [943](https://github.com/nunit/nunit-console/issues/943) Remove Travis CI * [947](https://github.com/nunit/nunit-console/issues/947) Make default TestAgency URI unique per run (v2) * [949](https://github.com/nunit/nunit-console/issues/949) nunit.engine.tests are failing to unload on master branch -* [956](https://github.com/nunit/nunit-console/issues/956) fix for test assembly loading failure in NUnit.ConsoleRunner.NetCore -* [957](https://github.com/nunit/nunit-console/issues/957) Include pdbs with nuget and zip packages and publish source code +* [956](https://github.com/nunit/nunit-console/issues/956) fix for test assembly loading failure in + NUnit.ConsoleRunner.NetCore +* [957](https://github.com/nunit/nunit-console/issues/957) Include pdbs with nuget and zip packages and publish source + code * [964](https://github.com/nunit/nunit-console/issues/954) Update Code of Conduct * [1014](https://github.com/nunit/nunit-console/issues/1014) GetClrVersionForFramework throws if .Net6.0 is installed * [1025](https://github.com/nunit/nunit-console/issues/1025) chore(pipeline): Use ubuntu-latest * [1031](https://github.com/nunit/nunit-console/issues/1031) Fix incorrect MyGet push URL * [1033](https://github.com/nunit/nunit-console/issues/1033) Update to current version of TestCentric.Metadata package * [1037](https://github.com/nunit/nunit-console/issues/1037) Eliminate End of Life Check in builds -* [1039](https://github.com/nunit/nunit-console/issues/1039) Stop re-publishing deprecated packages with each new release +* [1039](https://github.com/nunit/nunit-console/issues/1039) Stop re-publishing deprecated packages with each new + release ## NUnit Console & Engine 3.12 - January 17, 2021 ## .NET Core NUnit Console 3.12 Beta 2 - January 17, 2021 -This release contains various improvements to running tests on .NET Core and Mono, and changes to -extension loading logic to allow the Engine to better support extensions which target multiple platforms. There are additionally -a number of fixes to issues that were identified with 3.12 Beta 1. Please also be aware that this will be the last version of -the NUnit Engine to support .NET Standard 1.6. +This release contains various improvements to running tests on .NET Core and Mono, and changes to extension loading +logic to allow the Engine to better support extensions which target multiple platforms. There are additionally a number +of fixes to issues that were identified with 3.12 Beta 1. Please also be aware that this will be the last version of the +NUnit Engine to support .NET Standard 1.6. -The .NET Core Console remains in Beta due to some unresolved dependency loading and framework targeting issues - contributions to -fix these issues would be very welcome! +The .NET Core Console remains in Beta due to some unresolved dependency loading and framework targeting issues - +contributions to fix these issues would be very welcome! -Code contributions in this release were included from [Charlie Poole](https://github.com/CharliePoole), [Chris Maddock](https://github.com/ChrisMaddock), [Christian Bay](https://github.com/tdctaz), [Eberhard Beilharz](https://github.com/ermshiperete), [Ed Ball](https://github.com/ejball), [Joseph Musser](https://github.com/jnm2), [Manohar Singh](https://github.com/mano-si), [Mattias Cavigelli](https://github.com/mcavigelli) and [Mikkel Nylander Bundgaard](https://github.com/mikkelbu). Thank you to all those who contributed both in code, and otherwise. +Code contributions in this release were included from [Charlie Poole](https://github.com/CharliePoole), [Chris +Maddock](https://github.com/ChrisMaddock), [Christian Bay](https://github.com/tdctaz), [Eberhard +Beilharz](https://github.com/ermshiperete), [Ed Ball](https://github.com/ejball), [Joseph +Musser](https://github.com/jnm2), [Manohar Singh](https://github.com/mano-si), [Mattias +Cavigelli](https://github.com/mcavigelli) and [Mikkel Nylander Bundgaard](https://github.com/mikkelbu). Thank you to all +those who contributed both in code, and otherwise. -Please note the below list includes only issues resolved between 3.12.0 Beta 1 and the final release. For those upgrading from 3.11.1 -or earlier, please also see the Beta release notes. +Please note the below list includes only issues resolved between 3.12.0 Beta 1 and the final release. For those +upgrading from 3.11.1 or earlier, please also see the Beta release notes. * [511](https://github.com/nunit/nunit-console/issues/511) [Build] Improve detection of installed .NET Core Runtimes * [718](https://github.com/nunit/nunit-console/issues/718) Eliminate use of Mono.Cecil * [810](https://github.com/nunit/nunit-console/issues/810) Build NUnit.ConsoleRunner.NetCore as a .NET Core Tool. * [811](https://github.com/nunit/nunit-console/issues/811) Use readonly modifier where possible -* [818](https://github.com/nunit/nunit-console/issues/818) Remove redundant dependency on Microsoft.DotNet.InternalAbstractions for platforms other than .NET Standard 1.6 +* [818](https://github.com/nunit/nunit-console/issues/818) Remove redundant dependency on + Microsoft.DotNet.InternalAbstractions for platforms other than .NET Standard 1.6 * [825](https://github.com/nunit/nunit-console/issues/825) Revert change to increment nunit.engine.api assembly version * [829](https://github.com/nunit/nunit-console/issues/829) Revert change made to IExtensionService in nunit.engine.api * [830](https://github.com/nunit/nunit-console/issues/830) [CI] Test on .NET 5.0 * [837](https://github.com/nunit/nunit-console/issues/837) Fully remove Microsoft.Dotnet.InternalAbstractions dependency -* [844](https://github.com/nunit/nunit-console/issues/844) .NET Core console runner fails to load extensions when netfx and netstandard versions conflict +* [844](https://github.com/nunit/nunit-console/issues/844) .NET Core console runner fails to load extensions when netfx + and netstandard versions conflict * [847](https://github.com/nunit/nunit-console/issues/847) [Build] Specify .NET 2.0 version of extensions for msi -* [853](https://github.com/nunit/nunit-console/issues/853) [Build] Allow local build to succeed even if all runtimes are not installed +* [853](https://github.com/nunit/nunit-console/issues/853) [Build] Allow local build to succeed even if all runtimes are + not installed * [863](https://github.com/nunit/nunit-console/issues/863) [Build] Use released version of NUnit Framework 3.13.0 ## NUnit Console & Engine 3.12 Beta 1 - August 1, 2020 -This is the first beta release of the NUnit Console able to run .NET Core Tests. In addition to this, this release also contains a number of bug fixes, improvements when running on Mono and significant refactoring work towards the goal of creating an engine able to run tests on a wider range of .NET platforms. +This is the first beta release of the NUnit Console able to run .NET Core Tests. In addition to this, this release also +contains a number of bug fixes, improvements when running on Mono and significant refactoring work towards the goal of +creating an engine able to run tests on a wider range of .NET platforms. -We're particularly interested in this beta release being tested by users of the .NET Core console and users running tests on Mono. Please feedback any issues to the [nunit-console repository](https://github.com/nunit/nunit-console/issues). +We're particularly interested in this beta release being tested by users of the .NET Core console and users running +tests on Mono. Please feedback any issues to the [nunit-console +repository](https://github.com/nunit/nunit-console/issues). -The .NET Core Console is a separate executable to the original version, and can be found in either the .zip file download, or the new [NUnit.ConsoleRunner.NetCore](https://www.nuget.org/packages/NUnit.ConsoleRunner.NetCore/) NuGet package. Our longer-term aim is to create a single console which is able to run both .NET Core and .NET Framework tests. +The .NET Core Console is a separate executable to the original version, and can be found in either the .zip file +download, or the new [NUnit.ConsoleRunner.NetCore](https://www.nuget.org/packages/NUnit.ConsoleRunner.NetCore/) NuGet +package. Our longer-term aim is to create a single console which is able to run both .NET Core and .NET Framework tests. -Code contributions in this release were included from [Charlie Poole](https://github.com/CharliePoole), [Chris Maddock](https://github.com/ChrisMaddock), [Christian Bay](https://github.com/tdctaz), [Eberhard Beilharz](https://github.com/ermshiperete), [Joseph Musser](https://github.com/jnm2), [Manohar Singh](https://github.com/mano-si) and [Mikkel Nylander Bundgaard](https://github.com/mikkelbu). Thank you to all those who contributed both in code, and other ways! +Code contributions in this release were included from [Charlie Poole](https://github.com/CharliePoole), [Chris +Maddock](https://github.com/ChrisMaddock), [Christian Bay](https://github.com/tdctaz), [Eberhard +Beilharz](https://github.com/ermshiperete), [Joseph Musser](https://github.com/jnm2), [Manohar +Singh](https://github.com/mano-si) and [Mikkel Nylander Bundgaard](https://github.com/mikkelbu). Thank you to all those +who contributed both in code, and other ways! -* [391](https://github.com/nunit/nunit-console/issues/391) Provide useful error message when agent crashes with a stack overflow exception +* [391](https://github.com/nunit/nunit-console/issues/391) Provide useful error message when agent crashes with a stack + overflow exception * [475](https://github.com/nunit/nunit-console/issues/475) Create .NET Core Console Runner * [662](https://github.com/nunit/nunit-console/issues/662) Mono: Stacktrace missing files and line numbers -* [710](https://github.com/nunit/nunit-console/issues/710) .NET Core engine only works when located in same directory as test assembly +* [710](https://github.com/nunit/nunit-console/issues/710) .NET Core engine only works when located in same directory as + test assembly * [733](https://github.com/nunit/nunit-console/issues/733) iconUrl is deprecated in NuGet packages * [740](https://github.com/nunit/nunit-console/issues/740) Create separate agents for .NET 2.0-3.5 and .NET 4.x * [747](https://github.com/nunit/nunit-console/issues/747) [CI] Change macOS image version * [748](https://github.com/nunit/nunit-console/issues/748) Make Project config information available to runners * [750](https://github.com/nunit/nunit-console/issues/750) .NET Core Console Packaging * [751](https://github.com/nunit/nunit-console/issues/751) Minor updates to Contributing.MD -* [757](https://github.com/nunit/nunit-console/issues/757) Unable to test net 3.5 assembly if there's incompatible extension installed +* [757](https://github.com/nunit/nunit-console/issues/757) Unable to test net 3.5 assembly if there's incompatible + extension installed * [758](https://github.com/nunit/nunit-console/issues/758) Carry CurrentDirectory over to agent Processes * [761](https://github.com/nunit/nunit-console/issues/761) Revert accidental debug message change -* [762](https://github.com/nunit/nunit-console/issues/762) Simplify agent communication in preparation for new wire protocol -* [765](https://github.com/nunit/nunit-console/issues/765) Split RuntimeFramework package setting into two: Requested and Target -* [768](https://github.com/nunit/nunit-console/issues/768) Test run exits with an exit code of 0 if a multiple of 256 tests fail -* [775](https://github.com/nunit/nunit-console/issues/775) Extension loading broken on Linux when installed from nuget package +* [762](https://github.com/nunit/nunit-console/issues/762) Simplify agent communication in preparation for new wire + protocol +* [765](https://github.com/nunit/nunit-console/issues/765) Split RuntimeFramework package setting into two: Requested + and Target +* [768](https://github.com/nunit/nunit-console/issues/768) Test run exits with an exit code of 0 if a multiple of 256 + tests fail +* [775](https://github.com/nunit/nunit-console/issues/775) Extension loading broken on Linux when installed from nuget + package * [777](https://github.com/nunit/nunit-console/issues/777) Remove unused code to locate engine from registry keys -* [778](https://github.com/nunit/nunit-console/issues/778) Add .NET Core 3.1 build of engine to access APIs for loading .NET Core assemblies correctly -* [779](https://github.com/nunit/nunit-console/issues/779) [CI] Revert to running .NET Standard Engine Tests via NUnitLite -* [783](https://github.com/nunit/nunit-console/issues/783) Refactor XMLTransformResultWriterTests to avoid initializing entire engine +* [778](https://github.com/nunit/nunit-console/issues/778) Add .NET Core 3.1 build of engine to access APIs for loading + .NET Core assemblies correctly +* [779](https://github.com/nunit/nunit-console/issues/779) [CI] Revert to running .NET Standard Engine Tests via + NUnitLite +* [783](https://github.com/nunit/nunit-console/issues/783) Refactor XMLTransformResultWriterTests to avoid initializing + entire engine * [784](https://github.com/nunit/nunit-console/issues/784) Fix DirectTestRunner to not give all drivers the same ID. * [790](https://github.com/nunit/nunit-console/issues/790) Fix agent debug logging -* [800](https://github.com/nunit/nunit-console/issues/800) TypeLoadException thrown when changes are made to the API assembly, with multiple versions of the engine available -* [801](https://github.com/nunit/nunit-console/issues/801) Begin incrementing EngineApiVersion with every release, as per Engine version +* [800](https://github.com/nunit/nunit-console/issues/800) TypeLoadException thrown when changes are made to the API + assembly, with multiple versions of the engine available +* [801](https://github.com/nunit/nunit-console/issues/801) Begin incrementing EngineApiVersion with every release, as + per Engine version ## NUnit Console & Engine 3.11.1 - February 15, 2020 @@ -234,12 +297,14 @@ This hotfix fixes a problem with NUnit Project file settings being ignored. ## NUnit Console 3.11 - January 26, 2020 -This release fixes a range of minor bugs, and includes a significant amount of internal restructuring work. In future, this will enable improved .NET Standard support in the engine, and a .NET Core build of the console. +This release fixes a range of minor bugs, and includes a significant amount of internal restructuring work. In future, +this will enable improved .NET Standard support in the engine, and a .NET Core build of the console. * [22](https://github.com/nunit/nunit-console/issues/22) Engine modifies TestPackage * [53](https://github.com/nunit/nunit-console/issues/53) Add project element to top-level sub-project before merging * [181](https://github.com/nunit/nunit-console/issues/181) XSLT Transform not honoring --encoding value -* [336](https://github.com/nunit/nunit-console/issues/336) Should legacyCorruptedStateExceptionsPolicy enabled=true in nunit3-console.exe.config? +* [336](https://github.com/nunit/nunit-console/issues/336) Should legacyCorruptedStateExceptionsPolicy enabled=true in + nunit3-console.exe.config? * [386](https://github.com/nunit/nunit-console/issues/386) nUnit project loader does not work when --inprocess is set * [453](https://github.com/nunit/nunit-console/issues/453) build-mono-docker.ps1 fails to run out the box * [514](https://github.com/nunit/nunit-console/issues/514) Add higher-level unit tests for structure of TestRunners @@ -252,18 +317,24 @@ This release fixes a range of minor bugs, and includes a significant amount of i * [603](https://github.com/nunit/nunit-console/issues/603) Engine returns assembly-level test-suite event twice * [605](https://github.com/nunit/nunit-console/issues/605) Trailing \ in --work argument causes agent to crash * [607](https://github.com/nunit/nunit-console/issues/607) Unload + Load changes TestPackage IDs -* [611](https://github.com/nunit/nunit-console/issues/611) Set DisableImplicitNuGetFallbackFolder and bump Ubuntu on Travis +* [611](https://github.com/nunit/nunit-console/issues/611) Set DisableImplicitNuGetFallbackFolder and bump Ubuntu on + Travis * [612](https://github.com/nunit/nunit-console/issues/612) Fix logging when including exception -* [617](https://github.com/nunit/nunit-console/issues/617) Consider expanding projects before building ITestRunner structure +* [617](https://github.com/nunit/nunit-console/issues/617) Consider expanding projects before building ITestRunner + structure * [625](https://github.com/nunit/nunit-console/issues/625) [Feature] Extend `start-run` data for ITestEventListener -* [628](https://github.com/nunit/nunit-console/issues/628) [Question] Possible to set both labels=After and labels=Before +* [628](https://github.com/nunit/nunit-console/issues/628) [Question] Possible to set both labels=After and + labels=Before * [634](https://github.com/nunit/nunit-console/issues/634) Remove unnecessary stream creation in XML Transform writer * [635](https://github.com/nunit/nunit-console/issues/635) Remove all #regions from codebase -* [636](https://github.com/nunit/nunit-console/issues/636) Labels option: Rename On as OnOutputOnly, and deprecate On and All +* [636](https://github.com/nunit/nunit-console/issues/636) Labels option: Rename On as OnOutputOnly, and deprecate On + and All * [637](https://github.com/nunit/nunit-console/issues/637) Refactor RunnerSelectionTests * [639](https://github.com/nunit/nunit-console/issues/639) Engine initializes DriverService too early -* [667](https://github.com/nunit/nunit-console/issues/667) Console Runner loads wrong .NET framework version when executing tests from multiple assemblies at once -* [669](https://github.com/nunit/nunit-console/issues/669) nunit.console-runner-with-extensions.nuspec: Remove outdated release notes +* [667](https://github.com/nunit/nunit-console/issues/667) Console Runner loads wrong .NET framework version when + executing tests from multiple assemblies at once +* [669](https://github.com/nunit/nunit-console/issues/669) nunit.console-runner-with-extensions.nuspec: Remove outdated + release notes * [671](https://github.com/nunit/nunit-console/issues/671) Manually updated .NET Core SDK on Linux build * [681](https://github.com/nunit/nunit-console/issues/681) Display path and version of extension assemblies * [683](https://github.com/nunit/nunit-console/issues/683) Safely encapsulating the atomic agent database operations @@ -273,42 +344,46 @@ This release fixes a range of minor bugs, and includes a significant amount of i * [696](https://github.com/nunit/nunit-console/issues/696) Minimal compilation/test of .NET Core Console * [698](https://github.com/nunit/nunit-console/issues/698) Update NUnit v2 driver extension in combined packages * [703](https://github.com/nunit/nunit-console/issues/703) Update Console options for .NET Core Console build -* [704](https://github.com/nunit/nunit-console/issues/704) Agent in nupkg should not be referenced and causes warnings in consuming projects +* [704](https://github.com/nunit/nunit-console/issues/704) Agent in nupkg should not be referenced and causes warnings + in consuming projects * [706](https://github.com/nunit/nunit-console/issues/706) build.cake maintenance * [707](https://github.com/nunit/nunit-console/issues/707) Set agent to reference core and not full engine * [713](https://github.com/nunit/nunit-console/issues/713) Engine will not recognize .NET Framework versions beyond 4.5 ## NUnit Console 3.10 - March 24, 2019 -This release merges the .NET Standard version of the engine back into the nunit.engine -NuGet package and adds a .NET Standard 2.0 version of the engine that re-enables most -services and extensions. This deprecates the `nunit.engine.netstandard` NuGet package. -Any test runners using the old .NET Standard version of the engine should switch to -this release. +This release merges the .NET Standard version of the engine back into the nunit.engine NuGet package and adds a .NET +Standard 2.0 version of the engine that re-enables most services and extensions. This deprecates the +`nunit.engine.netstandard` NuGet package. Any test runners using the old .NET Standard version of the engine should +switch to this release. -The `--params` command line option which took multiple test parameters separated by -a semicolon is now deprecated in favor of the new `--testparam` command line option. -One of the most common uses for test parameters was to pass connection strings into -tests but this required workarounds to handle the semicolons. Now you must pass in -each test parameter separately using a `--testparam` or `--tp` option for each. +The `--params` command line option which took multiple test parameters separated by a semicolon is now deprecated in +favor of the new `--testparam` command line option. One of the most common uses for test parameters was to pass +connection strings into tests but this required workarounds to handle the semicolons. Now you must pass in each test +parameter separately using a `--testparam` or `--tp` option for each. ### Issues Resolved * [8](https://github.com/nunit/nunit-console/issues/8) TempResourceFile.Dispose causes run to hang -* [23](https://github.com/nunit/nunit-console/issues/23) In nunit3-console you cannot pass parameters containing ';' because they always get split +* [23](https://github.com/nunit/nunit-console/issues/23) In nunit3-console you cannot pass parameters containing ';' + because they always get split * [178](https://github.com/nunit/nunit-console/issues/178) Add date and time to console output -* [282](https://github.com/nunit/nunit-console/issues/282) "Execution terminated after first error" does not fail the console runner +* [282](https://github.com/nunit/nunit-console/issues/282) "Execution terminated after first error" does not fail the + console runner * [388](https://github.com/nunit/nunit-console/issues/388) Merge .NET Standard Engine back into the main solution * [389](https://github.com/nunit/nunit-console/issues/389) Update Mono.Cecil to latest -* [433](https://github.com/nunit/nunit-console/issues/433) All messages from EventListenerTextWriter goes to console output independent on stream name +* [433](https://github.com/nunit/nunit-console/issues/433) All messages from EventListenerTextWriter goes to console + output independent on stream name * [454](https://github.com/nunit/nunit-console/issues/454) Misc improvements to ExtensionServiceTests * [455](https://github.com/nunit/nunit-console/issues/455) Remove CF, Silverlight and PORTABLE functionality -* [464](https://github.com/nunit/nunit-console/issues/464) NUnit Console Reports Successful Exit Code When there is an Exception on Dispose +* [464](https://github.com/nunit/nunit-console/issues/464) NUnit Console Reports Successful Exit Code When there is an + Exception on Dispose * [473](https://github.com/nunit/nunit-console/issues/473) ArgumentException: DTD is prohibited in this XML document * [476](https://github.com/nunit/nunit-console/issues/476) .NET Standard engine to load extensions * [479](https://github.com/nunit/nunit-console/issues/479) Merge .NET Standard Engine code back into the main solution * [483](https://github.com/nunit/nunit-console/issues/483) Error in SetUpFixture does not result in non-zero exit code -* [485](https://github.com/nunit/nunit-console/issues/485) Invalid integer arguments do not display properly in error message +* [485](https://github.com/nunit/nunit-console/issues/485) Invalid integer arguments do not display properly in error + message * [493](https://github.com/nunit/nunit-console/issues/493) Correct order of params to Guard.ArgumentValid() * [498](https://github.com/nunit/nunit-console/issues/498) Reset console colors after Ctrl-C * [501](https://github.com/nunit/nunit-console/issues/501) Create result directory if it does not exist @@ -319,9 +394,11 @@ each test parameter separately using a `--testparam` or `--tp` option for each. * [518](https://github.com/nunit/nunit-console/issues/518) Correct Refactoring Error * [519](https://github.com/nunit/nunit-console/issues/519) Break up multiple console error messages with color * [523](https://github.com/nunit/nunit-console/issues/523) Reloading multiple files causes exception -* [524](https://github.com/nunit/nunit-console/issues/524) .NET Standard 2.0 engine crashes when .NET Framework extensions are in Global NuGet Cache +* [524](https://github.com/nunit/nunit-console/issues/524) .NET Standard 2.0 engine crashes when .NET Framework + extensions are in Global NuGet Cache * [525](https://github.com/nunit/nunit-console/issues/525) Separate NuGet Restore for Appveyor build -* [531](https://github.com/nunit/nunit-console/issues/531) Building a forked master branch results in publishing artifacts +* [531](https://github.com/nunit/nunit-console/issues/531) Building a forked master branch results in publishing + artifacts * [533](https://github.com/nunit/nunit-console/issues/533) Duplicate ids when loading a project * [544](https://github.com/nunit/nunit-console/issues/544) Deprecate nunit.netstandard.engine NuGet package * [546](https://github.com/nunit/nunit-console/issues/546) Cannot run a project file using --process:Separate @@ -333,35 +410,38 @@ each test parameter separately using a `--testparam` or `--tp` option for each. * [565](https://github.com/nunit/nunit-console/issues/565) Eliminate -dbg suffix from version * [566](https://github.com/nunit/nunit-console/issues/566) SettingsService is not needed in agents * [567](https://github.com/nunit/nunit-console/issues/567) Unnecessary call to IProjectService -* [571](https://github.com/nunit/nunit-console/issues/571) Space characters in the work directory path are not properly handled +* [571](https://github.com/nunit/nunit-console/issues/571) Space characters in the work directory path are not properly + handled * [583](https://github.com/nunit/nunit-console/issues/583) NUnit Console NuGet Package Doesn't Load Extensions -* [587](https://github.com/nunit/nunit-console/issues/587) Disable new MSBuild GenerateSupportedRuntime functionality, which breaks framework targeting +* [587](https://github.com/nunit/nunit-console/issues/587) Disable new MSBuild GenerateSupportedRuntime functionality, + which breaks framework targeting ## NUnit Console 3.9 - September 5, 2018 -This release should stop the dreaded SocketException problem on shutdown. The -console also no longer returns -5 when AppDomains fail to unload at the end of a -test run. These fixes should make CI runs much more stable and predictable. +This release should stop the dreaded SocketException problem on shutdown. The console also no longer returns -5 when +AppDomains fail to unload at the end of a test run. These fixes should make CI runs much more stable and predictable. -For developers working on the NUnit Console and Engine project, Visual Studio -2017 update 5 or newer is now required to compile on the command line. This does -not effect developers using NUnit or the NUnit Console, both of which support building -and running your tests in any IDE and on any .NET Framework back to .NET 2.0. +For developers working on the NUnit Console and Engine project, Visual Studio 2017 update 5 or newer is now required to +compile on the command line. This does not effect developers using NUnit or the NUnit Console, both of which support +building and running your tests in any IDE and on any .NET Framework back to .NET 2.0. ### Issues Resolved -* [103](https://github.com/nunit/nunit-console/issues/103) The switch statement does not cover all values of the 'RuntimeType' enum: NetCF. +* [103](https://github.com/nunit/nunit-console/issues/103) The switch statement does not cover all values of the + 'RuntimeType' enum: NetCF. * [218](https://github.com/nunit/nunit-console/issues/218) Move Distribution back into the nunit-console project. * [253](https://github.com/nunit/nunit-console/issues/253) Master Chocolatey issue * [255](https://github.com/nunit/nunit-console/issues/255) SocketException thrown during console run * [312](https://github.com/nunit/nunit-console/issues/312) CI failure: SocketException -* [360](https://github.com/nunit/nunit-console/issues/360) CommandLineOption --err does not write error input to ErrorFile +* [360](https://github.com/nunit/nunit-console/issues/360) CommandLineOption --err does not write error input to + ErrorFile * [367](https://github.com/nunit/nunit-console/issues/367) nunit3-console loads nunit.framework with partial name * [370](https://github.com/nunit/nunit-console/issues/370) Nunit.Console 3.8 - Socket Exception * [371](https://github.com/nunit/nunit-console/issues/371) Remove -5 exit code on app domain unload failures * [394](https://github.com/nunit/nunit-console/issues/394) Multi-targeted Engine Extensions * [399](https://github.com/nunit/nunit-console/issues/399) Fix minor document issues -* [411](https://github.com/nunit/nunit-console/issues/411) Make output received when providing user friendly messages unloading the domain more user friendly +* [411](https://github.com/nunit/nunit-console/issues/411) Make output received when providing user friendly messages + unloading the domain more user friendly * [412](https://github.com/nunit/nunit-console/issues/412) Extensions not detected for version 3.9.0-dev-03997 * [436](https://github.com/nunit/nunit-console/issues/436) NUnitEngineException : Unable to acquire remote process agent * [446](https://github.com/nunit/nunit-console/issues/446) Output CI version info to console @@ -372,37 +452,48 @@ and running your tests in any IDE and on any .NET Framework back to .NET 2.0. ## NUnit Console 3.8 - January 27, 2018 -This release includes several fixes when unloading AppDomains and better error reporting. The -aggregate NuGet packages also include updated versions of several extensions. +This release includes several fixes when unloading AppDomains and better error reporting. The aggregate NuGet packages +also include updated versions of several extensions. ### Issues Resolved * [6](https://github.com/nunit/nunit-console/issues/6) TypeLoadException in nunit3-console 3.0.1 * [93](https://github.com/nunit/nunit-console/issues/93) Update Readme with information about the NuGet packages * [111](https://github.com/nunit/nunit-console/issues/111) Provide better info when AppDomain won't unload -* [116](https://github.com/nunit/nunit-console/issues/116) NUnit 3.5.0 defaults to single agent process when using an nunit project file +* [116](https://github.com/nunit/nunit-console/issues/116) NUnit 3.5.0 defaults to single agent process when using an + nunit project file * [191](https://github.com/nunit/nunit-console/issues/191) Exception encountered unloading AppDomain -* [228](https://github.com/nunit/nunit-console/issues/228) System.Reflection.TargetInvocationException with nunit3-console --debug on Mono +* [228](https://github.com/nunit/nunit-console/issues/228) System.Reflection.TargetInvocationException with + nunit3-console --debug on Mono * [246](https://github.com/nunit/nunit-console/issues/246) No way to specify app.config with console runner -* [256](https://github.com/nunit/nunit-console/issues/256) Rewrite ConsoleRunnerTests.ThrowsNUnitEngineExceptionWhenTestResultsAreNotWriteable() -* [259](https://github.com/nunit/nunit-console/issues/259) NUnit3 agent hangs after encountering an "CannotUnloadAppDomainException" -* [262](https://github.com/nunit/nunit-console/issues/262) Transform file existence check should check current directory instead of WorkDirectory +* [256](https://github.com/nunit/nunit-console/issues/256) Rewrite + ConsoleRunnerTests.ThrowsNUnitEngineExceptionWhenTestResultsAreNotWriteable() +* [259](https://github.com/nunit/nunit-console/issues/259) NUnit3 agent hangs after encountering an + "CannotUnloadAppDomainException" +* [262](https://github.com/nunit/nunit-console/issues/262) Transform file existence check should check current directory + instead of WorkDirectory * [267](https://github.com/nunit/nunit-console/issues/267) Fix possible NRE -* [273](https://github.com/nunit/nunit-console/issues/273) Insufficient error handling message in ProcessRunner -> RunTests method +* [273](https://github.com/nunit/nunit-console/issues/273) Insufficient error handling message in ProcessRunner -> + RunTests method * [275](https://github.com/nunit/nunit-console/issues/275) Integrate chocolatey packages with build script -* [284](https://github.com/nunit/nunit-console/issues/284) NUnit3: An exception occured in the driver while loading tests... bei NUnit.Engine.Runners.ProcessRunner.RunTests(ITestEventListener listener, TestFilter filter) +* [284](https://github.com/nunit/nunit-console/issues/284) NUnit3: An exception occured in the driver while loading + tests... bei NUnit.Engine.Runners.ProcessRunner.RunTests(ITestEventListener listener, TestFilter filter) * [285](https://github.com/nunit/nunit-console/issues/285) ColorConsoleWriter.WriteLabel causes NullReferenceException * [289](https://github.com/nunit/nunit-console/issues/289) Warnings not displayed * [298](https://github.com/nunit/nunit-console/issues/298) Invalid --framework option throws exception -* [300](https://github.com/nunit/nunit-console/issues/300) Agents do not respect the Console WORK parameter when writing log file -* [304](https://github.com/nunit/nunit-console/issues/304) Catch agent debugger launch exceptions, and improve agent crash handling -* [309](https://github.com/nunit/nunit-console/issues/309) No driver found if framework assembly reference has uppercase characters +* [300](https://github.com/nunit/nunit-console/issues/300) Agents do not respect the Console WORK parameter when writing + log file +* [304](https://github.com/nunit/nunit-console/issues/304) Catch agent debugger launch exceptions, and improve agent + crash handling +* [309](https://github.com/nunit/nunit-console/issues/309) No driver found if framework assembly reference has uppercase + characters * [314](https://github.com/nunit/nunit-console/issues/314) Update NUnit.Extension.VSProjectLoader to 3.7.0 * [318](https://github.com/nunit/nunit-console/issues/318) Update NUnit.Extension.TeamCityEventListener to 1.0.3 * [320](https://github.com/nunit/nunit-console/issues/320) Return error code -5 when AppDomain fails to unload * [323](https://github.com/nunit/nunit-console/issues/323) Assertion should not be ordered in AgentDatabaseTests * [343](https://github.com/nunit/nunit-console/issues/343) Superfluous unload error shown in console -* [349](https://github.com/nunit/nunit-console/issues/349) Get all TestEngine tests running under NUnitAdapter apart from those . +* [349](https://github.com/nunit/nunit-console/issues/349) Get all TestEngine tests running under NUnitAdapter apart + from those . * [350](https://github.com/nunit/nunit-console/issues/350) Invalid assemblies no longer give an error message * [355](https://github.com/nunit/nunit-console/issues/355) NuGet package links to outdated license @@ -418,17 +509,21 @@ aggregate NuGet packages also include updated versions of several extensions. * [10](https://github.com/nunit/nunit-console/issues/10) Create a .NET Standard version of the Engine * [11](https://github.com/nunit/nunit-console/issues/11) insufficient info on driver reflection exception * [12](https://github.com/nunit/nunit-console/issues/12) Upgrade Cake build to latest version -* [24](https://github.com/nunit/nunit-console/issues/24) Update --labels switch with option to show real-time pass/fail results in console runner +* [24](https://github.com/nunit/nunit-console/issues/24) Update --labels switch with option to show real-time pass/fail + results in console runner * [31](https://github.com/nunit/nunit-console/issues/31) Nunit 3.4.1 NUnit.Engine.Runners * [72](https://github.com/nunit/nunit-console/issues/72) TestContext.Progress.Write writes new line * [82](https://github.com/nunit/nunit-console/issues/82) Remove unused repository paths from repositories.config * [99](https://github.com/nunit/nunit-console/issues/99) Remove unused --verbose and --full command line options -* [126](https://github.com/nunit/nunit-console/issues/126) Resolve differences between NUnit Console and NUnitLite implementations of @filename +* [126](https://github.com/nunit/nunit-console/issues/126) Resolve differences between NUnit Console and NUnitLite + implementations of @filename * [162](https://github.com/nunit/nunit-console/issues/162) Add namespace keyword to Test Selection Language * [171](https://github.com/nunit/nunit-console/issues/171) Socket Exception when stopping Remote Agent * [172](https://github.com/nunit/nunit-console/issues/172) Limit Language level to C#6 -* [193](https://github.com/nunit/nunit-console/issues/193) Settings are stored with invariant culture but retrieved with CurrentCulture -* [194](https://github.com/nunit/nunit-console/issues/194) Better logging or error handling in SettingsStore.SaveSettings +* [193](https://github.com/nunit/nunit-console/issues/193) Settings are stored with invariant culture but retrieved with + CurrentCulture +* [194](https://github.com/nunit/nunit-console/issues/194) Better logging or error handling in + SettingsStore.SaveSettings * [196](https://github.com/nunit/nunit-console/issues/196) Allow comments in @FILE files * [200](https://github.com/nunit/nunit-console/issues/200) Remove obsolete warnings from build script * [206](https://github.com/nunit/nunit-console/issues/206) Remove reference to removed `noxml` option @@ -437,20 +532,21 @@ aggregate NuGet packages also include updated versions of several extensions. * [213](https://github.com/nunit/nunit-console/issues/213) Master build failing after merging .NET Standard Engine * [216](https://github.com/nunit/nunit-console/issues/216) Compiling mock-assembly in Visual Studio 2017 fails * [217](https://github.com/nunit/nunit-console/issues/217) NUnit .NET Standard NuGet package missing some values -* [219](https://github.com/nunit/nunit-console/issues/219) Runtime.Remoting.RemotingException in NUnit.Engine.Runners.ProcessRunner.Dispose +* [219](https://github.com/nunit/nunit-console/issues/219) Runtime.Remoting.RemotingException in + NUnit.Engine.Runners.ProcessRunner.Dispose * [221](https://github.com/nunit/nunit-console/issues/221) Added missing nuget package info * [222](https://github.com/nunit/nunit-console/issues/222) Improve missing agent error message * [225](https://github.com/nunit/nunit-console/issues/225) SocketException thrown by nunit3-console.exe --explore option * [248](https://github.com/nunit/nunit-console/issues/248) Agent TestEngine contains duplicate services -* [252](https://github.com/nunit/nunit-console/issues/252) Console crashes when specifying both format and transform for result +* [252](https://github.com/nunit/nunit-console/issues/252) Console crashes when specifying both format and transform for + result * [254](https://github.com/nunit/nunit-console/issues/254) Correct misprint ".con" -> ".com" ## NUnit Console 3.6.1 - March 6, 2017 ### Engine -* This hotfix release addresses a race condition in the Engine that caused - tests to intermittently fail. +* This hotfix release addresses a race condition in the Engine that caused tests to intermittently fail. ### Issues Resolved @@ -460,37 +556,43 @@ aggregate NuGet packages also include updated versions of several extensions. ### Console Runner -* Added command line option `--skipnontestassemblies` to skip assemblies that do - not contain tests without raising an error and to skip assemblies that contain - the NUnit.Framework.NonTestAssemblyAttribute. +* Added command line option `--skipnontestassemblies` to skip assemblies that do not contain tests without raising an + error and to skip assemblies that contain the NUnit.Framework.NonTestAssemblyAttribute. * Messages from the new Multiple Assert blocks will be displayed individually * Warnings from the new Warn.If, Warn.Unless and Assert.Warn are now displayed ### Engine -* NUnit agents now monitor the running engine process and will terminate themselves - if the parent runner process is killed or dies +* NUnit agents now monitor the running engine process and will terminate themselves if the parent runner process is + killed or dies ### Issues Resolved * [16](https://github.com/nunit/nunit-console/issues/16) NUnit Engine Tests fail if not run from test directory * [18](https://github.com/nunit/nunit-console/issues/18) Invalid file type is shown in XML as type="Assembly" -* [23](https://github.com/nunit/nunit-console/issues/23) In nunit3-console you cannot pass parameters containing ';' because they always get split -* [37](https://github.com/nunit/nunit-console/issues/37) NUnit 3 console should produce xml events for ITestEventListener which contain - unique id in the scope of all test agents for NUnit 2 tests -* [58](https://github.com/nunit/nunit-console/issues/58) System.Configuration.ConfigurationErrorsException thrown in multiple domain mode. +* [23](https://github.com/nunit/nunit-console/issues/23) In nunit3-console you cannot pass parameters containing ';' + because they always get split +* [37](https://github.com/nunit/nunit-console/issues/37) NUnit 3 console should produce xml events for + ITestEventListener which contain unique id in the scope of all test agents for NUnit 2 tests +* [58](https://github.com/nunit/nunit-console/issues/58) System.Configuration.ConfigurationErrorsException thrown in + multiple domain mode. * [62](https://github.com/nunit/nunit-console/issues/62) NUnit3 Fails on DLL with no Tests, Unlike NUnit2 -* [100](https://github.com/nunit/nunit-console/issues/100) Class NUnit.Engine.Services.ResultWriters.Tests.SchemaValidator is never used -* [101](https://github.com/nunit/nunit-console/issues/101) Method NUnit.Options.OptionSet.Unprocessed always returns "false" -* [104](https://github.com/nunit/nunit-console/issues/104) Type of variable enumerated in 'foreach' is not guaranteed to be cast-able +* [100](https://github.com/nunit/nunit-console/issues/100) Class + NUnit.Engine.Services.ResultWriters.Tests.SchemaValidator is never used +* [101](https://github.com/nunit/nunit-console/issues/101) Method NUnit.Options.OptionSet.Unprocessed always returns + "false" +* [104](https://github.com/nunit/nunit-console/issues/104) Type of variable enumerated in 'foreach' is not guaranteed to + be cast-able * [110](https://github.com/nunit/nunit-console/issues/110) Writability check could give a friendlier message. * [113](https://github.com/nunit/nunit-console/issues/113) Add task descriptions to Build.cake * [127](https://github.com/nunit/nunit-console/issues/127) Modify console runner to display multiple assert information * [128](https://github.com/nunit/nunit-console/issues/128) Terminate agent if main process has terminated -* [133](https://github.com/nunit/nunit-console/issues/133) NUnit downloadable packages zip file naming is confusing and non-intuitive +* [133](https://github.com/nunit/nunit-console/issues/133) NUnit downloadable packages zip file naming is confusing and + non-intuitive * [136](https://github.com/nunit/nunit-console/issues/136) Handle early termination of multiple assert block * [138](https://github.com/nunit/nunit-console/issues/138) Report Warnings in console runner -* [145](https://github.com/nunit/nunit-console/issues/145) MasterTestRunner.RunAsync no longer provides start-run and test-run events +* [145](https://github.com/nunit/nunit-console/issues/145) MasterTestRunner.RunAsync no longer provides start-run and + test-run events * [151](https://github.com/nunit/nunit-console/issues/151) Unexpected behavior from --framework flag * [153](https://github.com/nunit/nunit-console/issues/153) Remove some settings used by the engine * [156](https://github.com/nunit/nunit-console/issues/156) Use high-quality icon for nuspecs diff --git a/docs/articles/nunit/Towards-NUnit4.md b/docs/articles/nunit/Towards-NUnit4.md index a20f6ca95..d34d6b79a 100644 --- a/docs/articles/nunit/Towards-NUnit4.md +++ b/docs/articles/nunit/Towards-NUnit4.md @@ -4,11 +4,21 @@ uid: towardsnunit4 # Towards NUnit Version 4 -NUnit 4 has been long-awaited, and we are now starting to see its outline taking shape. With the introduction of NUnit 4, we are also making changes to the release cadence, shifting towards a [Semver](https://semver.org) based versioning scheme. This entails aiming to release version 4 as soon as possible and subsequently accelerating the pace of new major releases compared to previous versions. - -We'd like to bring your attention to several interesting aspects of NUnit 4. First and foremost, there is a crucial [NUnit 4 planning issue](https://github.com/nunit/nunit/issues/3325) that we want to highlight. Additionally, we have an upcoming [release notes page](https://github.com/nunit/docs/blob/62c43cbbd32b8424c974d5ec50d5463a5c4cd621/docs/articles/nunit/release-notes/framework.md), currently in the form of a PR (Pull Request). If you're interested in changes related to supported frameworks and assert messages, we've compiled a [list of issues](https://github.com/nunit/nunit/issues/4431) for your reference. - -Moreover, we have created a milestone for version 4, [which you can find a list of open issues for here](https://github.com/nunit/nunit/issues?q=is%3Aopen+is%3Aissue+milestone%3A4.0). This milestone could be useful in tracking the progress and development of version 4. +NUnit 4 has been long-awaited, and we are now starting to see its outline taking shape. With the introduction of NUnit +4, we are also making changes to the release cadence, shifting towards a [Semver](https://semver.org) based versioning +scheme. This entails aiming to release version 4 as soon as possible and subsequently accelerating the pace of new major +releases compared to previous versions. + +We'd like to bring your attention to several interesting aspects of NUnit 4. First and foremost, there is a crucial +[NUnit 4 planning issue](https://github.com/nunit/nunit/issues/3325) that we want to highlight. Additionally, we have +an upcoming [release notes +page](https://github.com/nunit/docs/blob/62c43cbbd32b8424c974d5ec50d5463a5c4cd621/docs/articles/nunit/release-notes/framework.md), +currently in the form of a PR (Pull Request). If you're interested in changes related to supported frameworks and assert +messages, we've compiled a [list of issues](https://github.com/nunit/nunit/issues/4431) for your reference. + +Moreover, we have created a milestone for version 4, [which you can find a list of open issues for +here](https://github.com/nunit/nunit/issues?q=is%3Aopen+is%3Aissue+milestone%3A4.0). This milestone could be useful in +tracking the progress and development of version 4. Now to some highlights -- not necessarily in chronological order. @@ -71,7 +81,10 @@ Message:  Note that the custom message is added before the Assert statement -Including the Assert statement that caused the failure becomes particularly valuable in scenarios involving Multiple Asserts. In such cases, with a list of results from various asserts, it can be challenging to determine precisely which assert is responsible for each message. The improved result messages now offer clearer insights, making it easier to identify the specific assert that led to each failure. +Including the Assert statement that caused the failure becomes particularly valuable in scenarios involving Multiple +Asserts. In such cases, with a list of results from various asserts, it can be challenging to determine precisely which +assert is responsible for each message. The improved result messages now offer clearer insights, making it easier to +identify the specific assert that led to each failure. Given the code: @@ -118,17 +131,25 @@ Multiple failures or warnings in test: ### Breaking change -* Please be aware of a breaking change regarding assert messages in NUnit. The previous format with params args is no longer supported. If you require a similar message format, it is now necessary to convert it to an interpolated string. +* Please be aware of a breaking change regarding assert messages in NUnit. The previous format with params args is no + longer supported. If you require a similar message format, it is now necessary to convert it to an interpolated + string. ### Developer details -The improved result messages have been implemented using the new [CallerArgumentExpression](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-10.0/caller-argument-expression) together with using a [FormattableString](https://learn.microsoft.com/en-us/dotnet/api/system.formattablestring?view=net-6.0) as the class for the message. +The improved result messages have been implemented using the new +[CallerArgumentExpression](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-10.0/caller-argument-expression) +together with using a +[FormattableString](https://learn.microsoft.com/en-us/dotnet/api/system.formattablestring?view=net-6.0) as the class for +the message. ## Proper async/await, you can now await the Asserts -NUnit 3 has implemented async functionality using a pattern called 'sync-over-async.' This approach allowed for its implementation without requiring significant underlying changes. +NUnit 3 has implemented async functionality using a pattern called 'sync-over-async.' This approach allowed for its +implementation without requiring significant underlying changes. -In version 4 proper async/await has been implemented with a series of new assert methods, `Assert.ThatAsync` which can be `await`'ed. +In version 4 proper async/await has been implemented with a series of new assert methods, `Assert.ThatAsync` which can +be `await`'ed. ```cs [Test] @@ -138,7 +159,10 @@ public async Task AssertionPasses_CompletedTaskWithResult_EqualsResult() } ``` -Version 4 also introduces a new feature called Assert.MultipleAsync, which allows you to mix async and sync asserts within the same block. This enables you to perform multiple assertions, both asynchronous and synchronous, in a more concise and streamlined manner. Moreover, it's important to note that Assert.MultipleAsync is awaitable, providing flexibility in handling asynchronous operations and assertions. +Version 4 also introduces a new feature called Assert.MultipleAsync, which allows you to mix async and sync asserts +within the same block. This enables you to perform multiple assertions, both asynchronous and synchronous, in a more +concise and streamlined manner. Moreover, it's important to note that Assert.MultipleAsync is awaitable, providing +flexibility in handling asynchronous operations and assertions. ```cs [Test] @@ -155,7 +179,8 @@ public async Task AssertMultipleAsyncSucceeds() ## Cooperative Cancellation -For later versions of .NET it is not possible to abort a hanging thread -- and even though it's technically allowed in the classic .NET Framework, it prevents `finally` clauses and other cleanup routines from running. +For later versions of .NET it is not possible to abort a hanging thread -- and even though it's technically allowed in +the classic .NET Framework, it prevents `finally` clauses and other cleanup routines from running. Cancellation is supposed to be done in a cooperative way. @@ -163,12 +188,15 @@ To achieve this in NUnit v4, we introduce a [CancelAfter Attribute](./writing-te ## Nullability -Version 4 has implemented stricter nullability throughout the codebase. While there are still some areas that require fixing, overall, it should now conform to the nullability requirements. See [3376](https://github.com/nunit/nunit/issues/3376) for details. +Version 4 has implemented stricter nullability throughout the codebase. While there are still some areas that require +fixing, overall, it should now conform to the nullability requirements. See +[3376](https://github.com/nunit/nunit/issues/3376) for details. -These changes, along with the improved assert messages, have resulted in null values no longer being allowed for messages. As a consequence, code like the example below will not compile and will result in [CS0121](https://learn.microsoft.com/en-us/dotnet/csharp/misc/cs0121?f1url=%3FappId%3Droslyn%26k%3Dk(CS0121))): +These changes, along with the improved assert messages, have resulted in null values no longer being allowed for +messages. As a consequence, code like the example below will not compile and will result in +[CS0121](https://learn.microsoft.com/en-us/dotnet/csharp/misc/cs0121?f1url=%3FappId%3Droslyn%26k%3Dk(CS0121))): -![AssertNull](~/images/AssertNull.png) -It's important to update such code to use valid non-null message strings +![AssertNull](~/images/AssertNull.png) It's important to update such code to use valid non-null message strings ## Platform support @@ -176,8 +204,9 @@ The lowest framework platforms support in Version 4 are **.net framework 4.6.2** ## Classic/Legacy asserts -The classic/legacy asserts, like `Assert.AreEqual`, have now been moved into their own project, and will later be released as a separate package. They are now in the namespace `NUnit.Framework.Legacy`, and the `Assert` class has been renamed to `ClassicAssert`. -In the early V4 versions they will be delivered in the standard NUnit package. +The classic/legacy asserts, like `Assert.AreEqual`, have now been moved into their own project, and will later be +released as a separate package. They are now in the namespace `NUnit.Framework.Legacy`, and the `Assert` class has been +renamed to `ClassicAssert`. In the early V4 versions they will be delivered in the standard NUnit package. This means that the default assertion syntax going forward will be the "constraint-based" asserts. @@ -185,7 +214,8 @@ See [Assertions](xref:assertions) for more details. ## Testing it out -We have development packages deployed to a Myget feed, and now we have also added a github packages feed. If you're using the latter you need to authenticate yourself, once that is done anyone can grab from that feed. +We have development packages deployed to a Myget feed, and now we have also added a github packages feed. If you're +using the latter you need to authenticate yourself, once that is done anyone can grab from that feed. ### Myget @@ -237,4 +267,6 @@ Then, replace your current NUnit `PackageReference` with: We do appreciate feedback on these version 4 features. -You can join in on the [discussion here](https://github.com/nunit/nunit/discussions/4437), comment in our [slack channel](https://nunit.slack.com), or if it is a bug or suggestion for improvement you can also raise an issue in our [github repo](https://github.com/nunit/nunit/issues). +You can join in on the [discussion here](https://github.com/nunit/nunit/discussions/4437), comment in our [slack +channel](https://nunit.slack.com), or if it is a bug or suggestion for improvement you can also raise an issue in our +[github repo](https://github.com/nunit/nunit/issues). diff --git a/docs/articles/nunit/extending-nunit/Action-Attributes.md b/docs/articles/nunit/extending-nunit/Action-Attributes.md index 4ae9951a4..a470929b3 100644 --- a/docs/articles/nunit/extending-nunit/Action-Attributes.md +++ b/docs/articles/nunit/extending-nunit/Action-Attributes.md @@ -5,20 +5,37 @@ uid: actionattributes # Action Attributes > [!NOTE] -> `Action Attributes` are a feature of NUnit V2, designed to better enable composability of test logic. They are carried over to NUnit 3, but are not the recommended approach for most new work. Instead, for most problems of extensibility, NUnit 3 [Custom Attributes](Custom-Attributes.md) are a better approach and are more likely to be supported in future releases. -> However, at this time, `Action Attributes` provide the only approach that allows placing an attribute on a higher-level element and having it affect the behavior of lower-level elements. The rest of this page describes `Action Attribute` usage in NUnit 3. +> `Action Attributes` are a feature of NUnit V2, designed to better enable composability of test logic. They are +> carried over to NUnit 3, but are not the recommended approach for most new work. Instead, for most problems of +> extensibility, NUnit 3 [Custom Attributes](Custom-Attributes.md) are a better approach and are more likely to be +> supported in future releases. However, at this time, `Action Attributes` provide the only approach that allows placing +> an attribute on a higher-level element and having it affect the behavior of lower-level elements. The rest of this +> page describes `Action Attribute` usage in NUnit 3. -Often when writing unit tests we have logic that we want to run upon certain events in the test cycle (e.g. SetUp, TearDown, FixtureSetUp, FixtureTearDown, etc.). NUnit has had the ability to execute code upon these events by decorating fixture classes and methods with the appropriate NUnit- provided attributes. +Often when writing unit tests we have logic that we want to run upon certain events in the test cycle (e.g. SetUp, +TearDown, FixtureSetUp, FixtureTearDown, etc.). NUnit has had the ability to execute code upon these events by +decorating fixture classes and methods with the appropriate NUnit- provided attributes. -`Action Attributes` allow the user to create custom attributes to encapsulate specific actions for use before or after any test is run. +`Action Attributes` allow the user to create custom attributes to encapsulate specific actions for use before or after +any test is run. ## The Problem of Composability -Suppose we have some tests in multiple fixtures that need the same in-memory test database to be created and destroyed on each test run. We could create a base fixture class and derive each fixture that depends on the test from that class. Alternatively, we could create a `SetUpFixture` class at the level of a common namespace shared by each fixture. +Suppose we have some tests in multiple fixtures that need the same in-memory test database to be created and destroyed +on each test run. We could create a base fixture class and derive each fixture that depends on the test from that class. +Alternatively, we could create a `SetUpFixture` class at the level of a common namespace shared by each fixture. -This works fine, until we need some other reusable functionality, say the ability to configure or reset a ServiceLocator. We could put that functionality in the base fixture class or setup fixture, but now we're mixing two different responsibilities into the base class. In the case of a setup fixture, this only works if all classes requiring both features are located in a common namespace. In some cases we may *not* want the test database, but we do want ServiceLocator configuration; and sometimes we want the opposite. Still other times we'll want both - so we'd have to make the base class configurable. +This works fine, until we need some other reusable functionality, say the ability to configure or reset a +ServiceLocator. We could put that functionality in the base fixture class or setup fixture, but now we're mixing two +different responsibilities into the base class. In the case of a setup fixture, this only works if all classes requiring +both features are located in a common namespace. In some cases we may *not* want the test database, but we do want +ServiceLocator configuration; and sometimes we want the opposite. Still other times we'll want both - so we'd have to +make the base class configurable. -If we now discover a third piece of functionality we need to reuse, like configuring the Thread's CurrentPrincipal in arbitrary ways, the complexity of the solution very quickly. We've violated the Single Responsibility Principle and are suffering for it. What we really want is the ability to separate the different pieces of reusable test logic and compose them together as our tests need them. +If we now discover a third piece of functionality we need to reuse, like configuring the Thread's CurrentPrincipal in +arbitrary ways, the complexity of the solution very quickly. We've violated the Single Responsibility Principle and are +suffering for it. What we really want is the ability to separate the different pieces of reusable test logic and compose +them together as our tests need them. ## Resolving the Problem @@ -42,8 +59,8 @@ public class MyTests } ``` -Here we have used user-defined attributes to identify five different actions -that we want to compose together in different ways for different tests: +Here we have used user-defined attributes to identify five different actions that we want to compose together in +different ways for different tests: * ResetServiceLocator * CreateTestDatabase @@ -51,14 +68,13 @@ that we want to compose together in different ways for different tests: * AsNamedPrincipal * AsGuestPrincipal -We can reuse these actions in other test fixtures, simply by decorating -them with the appropriate attributes.without having to inherit from a base class. -We can even develop and distribute a library of common test actions. +We can reuse these actions in other test fixtures, simply by decorating them with the appropriate attributes.without +having to inherit from a base class. We can even develop and distribute a library of common test actions. ## Implementing an Action Attribute -Action attributes are defined by the programmer. They implement the `ITestAction` -interface, which is defined as follows: +Action attributes are defined by the programmer. They implement the `ITestAction` interface, which is defined as +follows: ```csharp public interface ITestAction @@ -71,14 +87,14 @@ public interface ITestAction } ``` -For convenience, you may derive your own action attribute from NUnit's `TestActionAttribute`, -an abstract class with virtual implementations of each member of the interface. Alternatively, you -may derive from `System.Attribute` and implement the interface directly. +For convenience, you may derive your own action attribute from NUnit's `TestActionAttribute`, an abstract class with +virtual implementations of each member of the interface. Alternatively, you may derive from `System.Attribute` and +implement the interface directly. ### Action Targets -The value returned from the `Targets` property determines when the `BeforeTest` and -`AfterTest` methods will be called. The ActionTargets enum is defined as follows: +The value returned from the `Targets` property determines when the `BeforeTest` and `AfterTest` methods will be called. +The ActionTargets enum is defined as follows: ```csharp [Flags] @@ -92,23 +108,25 @@ public enum ActionTargets } ``` -When an attribute that returns `ActionTargets.Suite` is applied to either a class or a parameterized method, NUnit will execute the attribute's `BeforeTest` method prior to executing the test suite and then execute the `AfterTest` method after the test suite has finished executing. This is similar to how the `OneTimeSetUp` and `OneTimeTearDown` attributes work. +When an attribute that returns `ActionTargets.Suite` is applied to either a class or a parameterized method, NUnit will +execute the attribute's `BeforeTest` method prior to executing the test suite and then execute the `AfterTest` method +after the test suite has finished executing. This is similar to how the `OneTimeSetUp` and `OneTimeTearDown` attributes +work. -On the other hand, when an attribute that returns `ActionTargets.Test` is used in the same -situations, NUnit will execute the attribute's `BeforeTest` method prior to each contained -test case and the `AfterTest` method after each test case. This is similar to how the `SetUp` -and `TearDown` attributes work. +On the other hand, when an attribute that returns `ActionTargets.Test` is used in the same situations, NUnit will +execute the attribute's `BeforeTest` method prior to each contained test case and the `AfterTest` method after each test +case. This is similar to how the `SetUp` and `TearDown` attributes work. -Action attributes that return `ActionTargets.Default` target the particular code item to -which they are attached. When attached to a method, they behave as if `ActionTargets.Test` had been -specified. When attached to a class or assembly, they behave as if `ActionTargets.Suite` was returned. +Action attributes that return `ActionTargets.Default` target the particular code item to which they are attached. When +attached to a method, they behave as if `ActionTargets.Test` had been specified. When attached to a class or assembly, +they behave as if `ActionTargets.Suite` was returned. ### ITest Interface -The `BeforeTest` and `AfterTest` methods are provided with information -about the test that is about to run (before) or has just run (after). The `ITest` -interface is an internal NUnit interface to the representation of a test, which may be -either a test case or a suite. The before and after methods may use the interface to decide what actions to take or retrieve information about the test. +The `BeforeTest` and `AfterTest` methods are provided with information about the test that is about to run (before) or +has just run (after). The `ITest` interface is an internal NUnit interface to the representation of a test, which may be +either a test case or a suite. The before and after methods may use the interface to decide what actions to take or +retrieve information about the test. ```csharp public interface ITest : IXmlNodeBuilder @@ -195,7 +213,10 @@ public class ConsoleActionAttribute : Attribute, ITestAction } ``` -Note that the above Action Attribute returns the union of ActionTargets.Test and ActionTargets.Suite. This is permitted, but will probably not be the normal case. It is done here so we can reuse the attribute in multiple examples. The attribute takes a single constructor argument, a message, that will be used to write output to the console. All of the Before and After methods write output via the WriteToConsole method. +Note that the above Action Attribute returns the union of ActionTargets.Test and ActionTargets.Suite. This is permitted, +but will probably not be the normal case. It is done here so we can reuse the attribute in multiple examples. The +attribute takes a single constructor argument, a message, that will be used to write output to the console. All of the +Before and After methods write output via the WriteToConsole method. ## Method Attached Actions @@ -248,9 +269,8 @@ public class ActionAttributeSampleTests #### Remarks -You are permitted to apply the same attribute multiple times. Note -that the order in which attributes are applied is indeterminate, although -it will generally be stable for a single release of .NET. +You are permitted to apply the same attribute multiple times. Note that the order in which attributes are applied is +indeterminate, although it will generally be stable for a single release of .NET. #### Example 3 (applied to a test method with test cases) @@ -284,9 +304,9 @@ public class ActionAttributeSampleTests #### Remarks When one or more [TestCase] attributes are applied to a method, NUnit treats the method as a test suite. -You'll notice that BeforeTest was run once before the suite and AfterTest was run once after it. -In addition, BeforeTest and AfterTest are run again for each individual test case. -Note that the order in which test cases are executed is indeterminate. +You'll notice that BeforeTest was run once before the suite and AfterTest was run once after it. In addition, BeforeTest +and AfterTest are run again for each individual test case. Note that the order in which test cases are executed is +indeterminate. ## Type Attached Actions @@ -325,7 +345,8 @@ public class ActionAttributeSampleTests #### Remarks -In this case, the class is the test suite. BeforeTest and AfterTest are run once each for this class and then again for each test. +In this case, the class is the test suite. BeforeTest and AfterTest are run once each for this class and then again for +each test. #### Example 2 (attached to interface) @@ -358,7 +379,9 @@ public class ActionAttributeSampleTests : IHaveAnAction #### Remarks -Action attributes can be applied to an interface. If a class marked with [TestFixture] implements an interface that has an action attribute applied to the interface, the class inherits the action attribute from the interface. It behaves as if you applied the action attribute to the class itself. +Action attributes can be applied to an interface. If a class marked with [TestFixture] implements an interface that has +an action attribute applied to the interface, the class inherits the action attribute from the interface. It behaves as +if you applied the action attribute to the class itself. ### Example 3 (action attribute is applied to interface and attribute uses interface to provide data to tests) @@ -407,10 +430,15 @@ public class ActionAttributeSampleTests : IHaveAnAction #### Remarks -Here we see a new action attribute, `InterfaceAwareAction`. This attribute uses the Fixture property of the TestDetails passed into BeforeTest and casts it to an interface, IHaveAnAction. If the fixture implements the IHaveAnAction interface, the attribute sets the Message property to the string passed into the constructor of the attribute. Since the attribute is applied to the interface, any class that implements this interface gets its Message property set to the string provided to the constructor of the attribute. This is useful when the action attribute provides some data or service to the tests. +Here we see a new action attribute, `InterfaceAwareAction`. This attribute uses the Fixture property of the TestDetails +passed into BeforeTest and casts it to an interface, IHaveAnAction. If the fixture implements the IHaveAnAction +interface, the attribute sets the Message property to the string passed into the constructor of the attribute. Since +the attribute is applied to the interface, any class that implements this interface gets its Message property set to the +string provided to the constructor of the attribute. This is useful when the action attribute provides some data or +service to the tests. -Note that this attribute inherits from `TestActionAttribute`. It uses the default (do-nothing) implementation -of `AfterTest` and overrides both `BeforeTest` and `Target`. +Note that this attribute inherits from `TestActionAttribute`. It uses the default (do-nothing) implementation of +`AfterTest` and overrides both `BeforeTest` and `Target`. ### Assembly Attached Action @@ -442,4 +470,11 @@ public class ActionAttributeSampleTests #### Remarks -The `ConsoleAction` attribute in this example is applied to the entire assembly. NUnit treats an assembly as a test suite (in fact, a suite of suites). Since the `ConsoleAction` attribute implements both ITestSuiteAction and ITestCaseAction, NUnit will run BeforeTest once before any tests are run in the assembly, and AfterTest after all tests are run in the assembly. Additionally, BeforeTest and AfterTest will be run for every test case in the assembly. It is unlikely that action attributes are applied to assemblies often. However, it is useful to build action attributes that ensure state gets cleaned up before and after each tests to prevent individual tests from affecting the outcome of other test. For example, if you have any static or cached data or services, an action attribute can be used to clean them up for each test. +The `ConsoleAction` attribute in this example is applied to the entire assembly. NUnit treats an assembly as a test +suite (in fact, a suite of suites). Since the `ConsoleAction` attribute implements both ITestSuiteAction and +ITestCaseAction, NUnit will run BeforeTest once before any tests are run in the assembly, and AfterTest after all tests +are run in the assembly. Additionally, BeforeTest and AfterTest will be run for every test case in the assembly. It is +unlikely that action attributes are applied to assemblies often. However, it is useful to build action attributes that +ensure state gets cleaned up before and after each tests to prevent individual tests from affecting the outcome of other +test. For example, if you have any static or cached data or services, an action attribute can be used to clean them up +for each test. diff --git a/docs/articles/nunit/extending-nunit/Custom-Attributes.md b/docs/articles/nunit/extending-nunit/Custom-Attributes.md index c5e3d39b5..8ca9a98fc 100644 --- a/docs/articles/nunit/extending-nunit/Custom-Attributes.md +++ b/docs/articles/nunit/extending-nunit/Custom-Attributes.md @@ -1,12 +1,17 @@ # Custom Attributes -NUnit 3 implements a great deal of its functionality in its attributes. This functionality is accessed through a number of standard interfaces, which are implemented by the attributes. Users may create their own attributes by implementing these interfaces. +NUnit 3 implements a great deal of its functionality in its attributes. This functionality is accessed through a number +of standard interfaces, which are implemented by the attributes. Users may create their own attributes by implementing +these interfaces. -For ease of understanding, the interfaces are grouped according to the stage in the life-cycle of a test at which they are used. The two primary stages in the life of a test are Load-Time and Execution-Time. +For ease of understanding, the interfaces are grouped according to the stage in the life-cycle of a test at which they +are used. The two primary stages in the life of a test are Load-Time and Execution-Time. ## Load-Time Interfaces -_Loading_ tests means loading the assembly into memory and examining its content to discover the classes and fixtures that represent tests. The internal structures that represent tests are built at this time. If requested by the application, information about the tests may be returned for display, as is done in the NUnit GUI runner. +_Loading_ tests means loading the assembly into memory and examining its content to discover the classes and fixtures +that represent tests. The internal structures that represent tests are built at this time. If requested by the +application, information about the tests may be returned for display, as is done in the NUnit GUI runner. The following interfaces are called at load time. @@ -21,7 +26,8 @@ The following interfaces are called at load time. ### Execution-Time Interfaces -At execution-time, some or all of the tests that were previously loaded are actually run. Their results are returned and made available to the application. +At execution-time, some or all of the tests that were previously loaded are actually run. Their results are returned and +made available to the application. The following interfaces are called at execution time. diff --git a/docs/articles/nunit/extending-nunit/Custom-Constraints.md b/docs/articles/nunit/extending-nunit/Custom-Constraints.md index 65a91176f..63172c375 100644 --- a/docs/articles/nunit/extending-nunit/Custom-Constraints.md +++ b/docs/articles/nunit/extending-nunit/Custom-Constraints.md @@ -7,12 +7,14 @@ uid: customconstraints > [!NOTE] > Page Under Development -You can implement your own custom constraints by creating a class that inherits from the `Constraint` abstract class, which supports performing a test on an actual value and generating appropriate messages. +You can implement your own custom constraints by creating a class that inherits from the `Constraint` abstract class, +which supports performing a test on an actual value and generating appropriate messages. ## `Constraint` Abstract Class -Implementations must override the one abstract method `ApplyTo` which -evaluates the previously stored expected value (if any) against the method's parameter, the actual value. There are also several virtual methods that may be overridden to change some default behaviors. +Implementations must override the one abstract method `ApplyTo` which evaluates the previously stored expected +value (if any) against the method's parameter, the actual value. There are also several virtual methods that may be +overridden to change some default behaviors. The relevant portions of the `Constraint` class are represented below. @@ -35,21 +37,18 @@ namespace NUnit.Framework.Constraints ## `Constraint` Constructor -The `Constraint` constructor accepts zero or more arguments and saves them to be used -in the printed description later. Constraints like `NullConstraint` or `UniqueItemsConstraint` -take no arguments and simply state some condition about the actual value supplied. Constraints -with a single argument usually treat it as the expected value resulting from some operation. -Multiple arguments can be provided where the semantics of the constraint call for it. +The `Constraint` constructor accepts zero or more arguments and saves them to be used in the printed description later. +Constraints like `NullConstraint` or `UniqueItemsConstraint` take no arguments and simply state some condition about the +actual value supplied. Constraints with a single argument usually treat it as the expected value resulting from some +operation. Multiple arguments can be provided where the semantics of the constraint call for it. ## `ApplyTo` Implementation -The `ApplyTo(TActual actual)` method must be overridden and provides for the -core implementation of the custom constraint. Whatever logic defines pass or fail -of the constraint and actual/expected values goes into the `ApplyTo(TActual actual)` -method. +The `ApplyTo(TActual actual)` method must be overridden and provides for the core implementation of the custom +constraint. Whatever logic defines pass or fail of the constraint and actual/expected values goes into the +`ApplyTo(TActual actual)` method. -For example, a very naive implementation of a reference equality constraint might look -like this: +For example, a very naive implementation of a reference equality constraint might look like this: ```csharp public override ConstraintResult ApplyTo(TActual actual) @@ -58,30 +57,33 @@ public override ConstraintResult ApplyTo(TActual actual) } ``` -The key here is there needs to be some evaluation of the constraint logic, and the return value -must be a `ConstraintResult` or subclass thereof. Custom subclasses of `ConstraintResult` may -be used to further customize the message provided upon failure, as described below. +The key here is there needs to be some evaluation of the constraint logic, and the return value must be a +`ConstraintResult` or subclass thereof. Custom subclasses of `ConstraintResult` may be used to further customize the +message provided upon failure, as described below. ## `ApplyTo` Overloads -Constraints may be called with a delegate to return the actual value instead of the actual -value itself. This serves to delay evaluation of the value. The default implementation -of `ApplyTo(ActualValueDelegate del)` waits for the delegate to -complete if it's an async operation, other immediately calls the delegate if synchronous, and then calls the abstract `ApplyTo(TActual actual)` method with the value. +Constraints may be called with a delegate to return the actual value instead of the actual value itself. This serves to +delay evaluation of the value. The default implementation of `ApplyTo(ActualValueDelegate del)` waits +for the delegate to complete if it's an async operation, other immediately calls the delegate if synchronous, and then +calls the abstract `ApplyTo(TActual actual)` method with the value. -Another overload also exists, `ApplyTo(ref TActual actual)`. The default implementation -dereferences the value and then calls the abstract `ApplyTo(TActual actual)` method with the value. This public virtual method is available by use from calling code but currently is not used from any framework calls within NUnit itself. +Another overload also exists, `ApplyTo(ref TActual actual)`. The default implementation dereferences the value +and then calls the abstract `ApplyTo(TActual actual)` method with the value. This public virtual method is +available by use from calling code but currently is not used from any framework calls within NUnit itself. ## `GetTestObject` Optional Override -The default implementation of `ApplyTo(ActualValueDelegate del)` does not -simply execute the delegate but actually calls out to another virtual method, `GetTestObject(ActualValueDelegate del)`. This method can be overridden to keep the default behavior of `ApplyTo(ActualValueDelegate del)` while still customizing how the actual value delegate is invoked. +The default implementation of `ApplyTo(ActualValueDelegate del)` does not simply execute the delegate +but actually calls out to another virtual method, `GetTestObject(ActualValueDelegate del)`. This +method can be overridden to keep the default behavior of `ApplyTo(ActualValueDelegate del)` while +still customizing how the actual value delegate is invoked. ## `Description` Property -This virtual property is used to provide a description of the constraint for messages. Simple -constant values can be set in the custom constraint's constructor. If more complex logic is -needed, override the property and provide a custom implementation of `get`. +This virtual property is used to provide a description of the constraint for messages. Simple constant values can be set +in the custom constraint's constructor. If more complex logic is needed, override the property and provide a custom +implementation of `get`. Here are a few simple examples from built-in constraints. @@ -131,15 +133,16 @@ public abstract class PrefixConstraint : Constraint ## `GetStringRepresentation` Method -NUnit calls the `GetStringRepresentation` method to return a string representation of the -constraint, including the expected value(s). The default implementation returns the lowercase -display name of the constraint followed by all expected values, separated by a space. +NUnit calls the `GetStringRepresentation` method to return a string representation of the constraint, including the +expected value(s). The default implementation returns the lowercase display name of the constraint followed by all +expected values, separated by a space. -For example, a custom constraint `ReferenceEqualsConstraint` with an instance of a custom -`MyObject` class as expected value would result in a default string representation of ``. +For example, a custom constraint `ReferenceEqualsConstraint` with an instance of a custom `MyObject` class as expected +value would result in a default string representation of ``. -You can override the initial display name only by setting `DisplayName` in your constructor. -This public property cannot be overridden, but the `Constraint` base class sets it in the base constructor to be the name of the class, minus the "Constraint" suffix and minus any generic suffixes. +You can override the initial display name only by setting `DisplayName` in your constructor. This public property cannot +be overridden, but the `Constraint` base class sets it in the base constructor to be the name of the class, minus the +"Constraint" suffix and minus any generic suffixes. ## Custom Constraint Usage Syntax @@ -155,15 +158,15 @@ You may also use it in expressions through NUnit's `Matches` syntax element: Assert.That(myObject, Is.Not.Null.And.Matches(new CustomConstraint()); ``` -The direct construction approach is not very convenient or easy to read. -For its built-in constraints, NUnit includes classes that implement a special constraint syntax, allowing you to write things like... +The direct construction approach is not very convenient or easy to read. For its built-in constraints, NUnit includes +classes that implement a special constraint syntax, allowing you to write things like... ```csharp Assert.That(actual, Is.All.InRange(1, 100)); ``` -Custom constraints can support this syntax by providing a static helper class and -extension method on `ConstraintExpression`, such as this. +Custom constraints can support this syntax by providing a static helper class and extension method on +`ConstraintExpression`, such as this. ```csharp public static class CustomConstraintExtensions @@ -177,13 +180,12 @@ public static class CustomConstraintExtensions } ``` -To fully utilize your custom constraint the same way built-in constraints are used, you'll -need to implement two additional classes (which can cover all your constraints, not -for each custom constraint). +To fully utilize your custom constraint the same way built-in constraints are used, you'll need to implement two +additional classes (which can cover all your constraints, not for each custom constraint). -* Provide a static class patterned after NUnit's `Is` class, with properties - or methods that construct your custom constructor. If you like, you can even call it - `Is` and extend NUnit's `Is`, provided you place it in your own namespace and avoid any conflicts. This allows you to write things like: +* Provide a static class patterned after NUnit's `Is` class, with properties or methods that construct your custom + constructor. If you like, you can even call it `Is` and extend NUnit's `Is`, provided you place it in your own + namespace and avoid any conflicts. This allows you to write things like: ```csharp Assert.That(actual, Is.Custom(x, y)); @@ -201,8 +203,7 @@ public class Is : NUnit.Framework.Is } ``` -* Provide an extension method for NUnit's `ConstraintExpression`, allowing - you to write things like: +* Provide an extension method for NUnit's `ConstraintExpression`, allowing you to write things like: ```csharp Assert.That(actual, Is.Not.Custom(x, y)); diff --git a/docs/articles/nunit/extending-nunit/Framework-Extensibility.md b/docs/articles/nunit/extending-nunit/Framework-Extensibility.md index c298cf875..04f97958e 100644 --- a/docs/articles/nunit/extending-nunit/Framework-Extensibility.md +++ b/docs/articles/nunit/extending-nunit/Framework-Extensibility.md @@ -1,14 +1,22 @@ # Framework Extensibility -The NUnit Framework is the part of NUnit that is referenced by user tests. It contains the definition of all of NUnit's Attributes, Constraints and Asserts as well as the code that discovers and executes tests. Most extensions to exactly how tests are recognized and how they execute are Framework extensions. +The NUnit Framework is the part of NUnit that is referenced by user tests. It contains the definition of all of NUnit's +Attributes, Constraints and Asserts as well as the code that discovers and executes tests. Most extensions to exactly +how tests are recognized and how they execute are Framework extensions. In this documentation, we refer to three different types of Framework extension: -[Custom Attributes](Custom-Attributes.md) allow creation of new types of tests and suites, new sources of data and modification of the environment in which a test runs as well as its final result. +[Custom Attributes](Custom-Attributes.md) allow creation of new types of tests and suites, new sources of data and +modification of the environment in which a test runs as well as its final result. -[Action Attributes](Action-Attributes.md) are an NUnit V2 feature, still supported in NUnit 3. They were designed to better enable composability of test logic by creating attributes that encapsulate specific actions to be taken before or after a test is run. For most work, [Custom Attributes](Custom-Attributes.md) are the way to go, but [Action Attributes](Action-Attributes.md) continue to be the only way to apply an attribute at a higher level and have it apply to many tests. +[Action Attributes](Action-Attributes.md) are an NUnit V2 feature, still supported in NUnit 3. They were designed to +better enable composability of test logic by creating attributes that encapsulate specific actions to be taken before or +after a test is run. For most work, [Custom Attributes](Custom-Attributes.md) are the way to go, but [Action +Attributes](Action-Attributes.md) continue to be the only way to apply an attribute at a higher level and have it apply +to many tests. -[Custom Constraints](Custom-Constraints.md) allow the user to define new constraints for use in tests along with the associated fluent syntax that allows them to be used with `Assert.That`. +[Custom Constraints](Custom-Constraints.md) allow the user to define new constraints for use in tests along with the +associated fluent syntax that allows them to be used with `Assert.That`. ## Links to Blog Posts diff --git a/docs/articles/nunit/extending-nunit/IApplyToContext-Interface.md b/docs/articles/nunit/extending-nunit/IApplyToContext-Interface.md index fda1ce461..22a1265e0 100644 --- a/docs/articles/nunit/extending-nunit/IApplyToContext-Interface.md +++ b/docs/articles/nunit/extending-nunit/IApplyToContext-Interface.md @@ -1,6 +1,10 @@ # IApplyToContext Interface -NUnit tests run within a context, known as the `TestExecutionContext`. The context for a test case is nested within the context for its containing suite and so on, up to the assembly level. Attributes that implement `IApplyToContext` are called immediately after the context is created and before the test is run in order to make changes to the context. Once the test execution has completed, the context is discarded so that - effectively - any changes are reverted to their original values. +NUnit tests run within a context, known as the `TestExecutionContext`. The context for a test case is nested within the +context for its containing suite and so on, up to the assembly level. Attributes that implement `IApplyToContext` are +called immediately after the context is created and before the test is run in order to make changes to the context. Once +the test execution has completed, the context is discarded so that - effectively - any changes are reverted to their +original values. The `IApplyToContext` interface is defined as follows: @@ -11,9 +15,14 @@ public interface IApplyToContext } ``` -An example of the use of the context may be helpful. One item in the `TestExecutionContext` is the default timeout value for test cases. When any test is marked with `[Timeout(nnn)]` the context value is replaced by the supplied argument. The new timeout applies for any test case it appears on and any test case that is contained in a suite that it appears on. When the test or suite completes, the new value is discarded and the value contained in the original context is once against used. +An example of the use of the context may be helpful. One item in the `TestExecutionContext` is the default timeout value +for test cases. When any test is marked with `[Timeout(nnn)]` the context value is replaced by the supplied argument. +The new timeout applies for any test case it appears on and any test case that is contained in a suite that it appears +on. When the test or suite completes, the new value is discarded and the value contained in the original context is once +against used. -Custom attributes that implement `IApplyToContext` should modify the TestExecutionContext in accordance with the arguments supplied to them. They are not called after the test is run and have no cleanup to perform. +Custom attributes that implement `IApplyToContext` should modify the TestExecutionContext in accordance with the +arguments supplied to them. They are not called after the test is run and have no cleanup to perform. The NUnit attributes that implement `IApplyToContext` are as follows: diff --git a/docs/articles/nunit/extending-nunit/IApplyToTest-Interface.md b/docs/articles/nunit/extending-nunit/IApplyToTest-Interface.md index cfbb3ddf1..4721c1575 100644 --- a/docs/articles/nunit/extending-nunit/IApplyToTest-Interface.md +++ b/docs/articles/nunit/extending-nunit/IApplyToTest-Interface.md @@ -1,6 +1,7 @@ # IApplyToTest Interface -The `IApplyToTest` interface is used to make modifications to a test immediately after it is constructed. It is defined as follows: +The `IApplyToTest` interface is used to make modifications to a test immediately after it is constructed. It is defined +as follows: ```csharp public interface IApplyToTest @@ -9,13 +10,19 @@ public interface IApplyToTest } ``` -The `Test` Type is quite general and the argument may represent a suite or an individual test case. If the distinction is important, then you must code the attribute to examine the argument and react accordingly. +The `Test` Type is quite general and the argument may represent a suite or an individual test case. If the distinction +is important, then you must code the attribute to examine the argument and react accordingly. -The interface may appear on the same attribute that is used to construct the test or on a separate attribute. In either case, it will only be called after the test is built. +The interface may appear on the same attribute that is used to construct the test or on a separate attribute. In either +case, it will only be called after the test is built. -The order in which `ApplyToTest` is called on multiple attributes is indeterminate. If two attributes make completely independent changes to a test, then the order is not relevant. But if they both change the same property, or related properties, then it may necessary to make tests in the attribute code to ensure that the correct value 'wins'. +The order in which `ApplyToTest` is called on multiple attributes is indeterminate. If two attributes make completely +independent changes to a test, then the order is not relevant. But if they both change the same property, or related +properties, then it may necessary to make tests in the attribute code to ensure that the correct value 'wins'. -The most common example of this is for attributes that change the RunState of a test. If one attribute is trying to set it to `RunState.Ignore`, while the other wants it to be `RunState.NotRunnable`, we would normally expect the 'worst' value to win and for the test to be non-runnable. We can achieve that by code like the following: +The most common example of this is for attributes that change the RunState of a test. If one attribute is trying to set +it to `RunState.Ignore`, while the other wants it to be `RunState.NotRunnable`, we would normally expect the 'worst' +value to win and for the test to be non-runnable. We can achieve that by code like the following: ```csharp // In the attribute setting NotRunnable diff --git a/docs/articles/nunit/extending-nunit/ICommandWrapper-Interface.md b/docs/articles/nunit/extending-nunit/ICommandWrapper-Interface.md index 66317f91e..72c00f72e 100644 --- a/docs/articles/nunit/extending-nunit/ICommandWrapper-Interface.md +++ b/docs/articles/nunit/extending-nunit/ICommandWrapper-Interface.md @@ -1,8 +1,12 @@ # ICommandWrapper Interface -In NUnit 3, test execution is done using command objects, which are constructed for each test case. Execution of a single test case will generally require multiple nested commands. Some attributes placed on a test method are able to contribute to the chain of commands. For example, `MaxTimeAttribute` adds a command, which examines the elapsed time to complete a test and fails it if a specified maximum was exceeded. +In NUnit 3, test execution is done using command objects, which are constructed for each test case. Execution of a +single test case will generally require multiple nested commands. Some attributes placed on a test method are able to +contribute to the chain of commands. For example, `MaxTimeAttribute` adds a command, which examines the elapsed time to +complete a test and fails it if a specified maximum was exceeded. -Attributes add to the command chain by implementing one of the two interfaces that derive from the `ICommandWrapper` interface. The interfaces are defined as follows: +Attributes add to the command chain by implementing one of the two interfaces that derive from the `ICommandWrapper` +interface. The interfaces are defined as follows: ```csharp public interface ICommandWrapper @@ -19,9 +23,13 @@ public interface IWrapSetUpTearDown : ICommandWrapper } ``` -Attributes should __not__ implement the `ICommandWrapper` interface directly but should select one of the derived interfaces. NUnit applies the `IWrapSetUpTearDown` interface before SetUp and after TearDown. It applies the `IWrapTestMethod` interface after SetUp and before the test is run. +Attributes should __not__ implement the `ICommandWrapper` interface directly but should select one of the derived +interfaces. NUnit applies the `IWrapSetUpTearDown` interface before SetUp and after TearDown. It applies the +`IWrapTestMethod` interface after SetUp and before the test is run. -Attributes implementing one of these interfaces must be placed on a test method. Otherwise, they have no effect. The `Wrap` method should return an appropriate command in which the original command has been nested. For an example, see the implementation of `MaxTimeAttribute`. +Attributes implementing one of these interfaces must be placed on a test method. Otherwise, they have no effect. The +`Wrap` method should return an appropriate command in which the original command has been nested. For an example, see +the implementation of `MaxTimeAttribute`. The following NUnit attributes implement the `IWrapSetUpTearDown` interface: diff --git a/docs/articles/nunit/extending-nunit/IFixtureBuilder-Interface.md b/docs/articles/nunit/extending-nunit/IFixtureBuilder-Interface.md index 6e6417ffc..4436a96dc 100644 --- a/docs/articles/nunit/extending-nunit/IFixtureBuilder-Interface.md +++ b/docs/articles/nunit/extending-nunit/IFixtureBuilder-Interface.md @@ -1,6 +1,7 @@ # IFixtureBuilder Interface -This interface is used by attributes that know how to build a fixture from a user class. `IFixtureBuilder` is defined as follows: +This interface is used by attributes that know how to build a fixture from a user class. `IFixtureBuilder` is defined as +follows: ```csharp public interface IFixtureBuilder @@ -9,7 +10,9 @@ public interface IFixtureBuilder } ``` -Custom fixture builders should examine the provided `ITypeInfo` and return an appropriate type of fixture based on it. If the fixture is intended to be an NUnit `TestFixture`, then the helper class `NUnitTestFixtureBuilder` may be used to create it. +Custom fixture builders should examine the provided `ITypeInfo` and return an appropriate type of fixture based on it. +If the fixture is intended to be an NUnit `TestFixture`, then the helper class `NUnitTestFixtureBuilder` may be used to +create it. The following NUnit attributes currently implement this interface: @@ -19,6 +22,9 @@ The following NUnit attributes currently implement this interface: **Notes:** -1. `ITypeInfo` is an internal interface used by NUnit to wrap a Type. See [source code](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/ITypeInfo.cs) for details. +1. `ITypeInfo` is an internal interface used by NUnit to wrap a Type. See [source + code](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/ITypeInfo.cs) for details. -2. It would make more sense for this interface method to return `TestFixture` rather than `TestSuite`. We use `TestSuite` because it is the common base for both `TestFixture` and `SetupFixture`. In a future version, we will try to adjust the hierarchy so that all suites based on a class are derived from `TestFixture`. +2. It would make more sense for this interface method to return `TestFixture` rather than `TestSuite`. We use + `TestSuite` because it is the common base for both `TestFixture` and `SetupFixture`. In a future version, we will try + to adjust the hierarchy so that all suites based on a class are derived from `TestFixture`. diff --git a/docs/articles/nunit/extending-nunit/IImplyFixture-Interface.md b/docs/articles/nunit/extending-nunit/IImplyFixture-Interface.md index 8ea4aed6f..e4497cb90 100644 --- a/docs/articles/nunit/extending-nunit/IImplyFixture-Interface.md +++ b/docs/articles/nunit/extending-nunit/IImplyFixture-Interface.md @@ -8,7 +8,9 @@ public interface IImplyFixture } ``` -If a class contains any method with an attribute that implements this interface, that class is treated as an NUnit TestFixture without any `TestFixture` attribute being specified. The following NUnit attributes currently implement this interface: +If a class contains any method with an attribute that implements this interface, that class is treated as an NUnit +TestFixture without any `TestFixture` attribute being specified. The following NUnit attributes currently implement this +interface: * `TestAttribute` * `TestCaseAttribute` diff --git a/docs/articles/nunit/extending-nunit/IParameterDataSource-Interface.md b/docs/articles/nunit/extending-nunit/IParameterDataSource-Interface.md index a6df64615..752abeb3a 100644 --- a/docs/articles/nunit/extending-nunit/IParameterDataSource-Interface.md +++ b/docs/articles/nunit/extending-nunit/IParameterDataSource-Interface.md @@ -1,7 +1,8 @@ # IParameterDataSource Interface -The `IParameterDataSource` interface is implemented by attributes that provide data for use as an argument to a single parameter. Other attributes and test builders combine the values in various ways to produce test cases. -The interface is defined as follows: +The `IParameterDataSource` interface is implemented by attributes that provide data for use as an argument to a single +parameter. Other attributes and test builders combine the values in various ways to produce test cases. The interface is +defined as follows: ```csharp public interface IParameterDataSource @@ -10,9 +11,13 @@ public interface IParameterDataSource } ``` -`IParameterInfo` is an NUnit internal class used to wrap a `ParameterInfo`. See the [source code](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/IParameterInfo.cs) for more info. +`IParameterInfo` is an NUnit internal class used to wrap a `ParameterInfo`. See the [source +code](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/IParameterInfo.cs) for more +info. -A custom attribute implementing this interface should examine the `IParameterInfo` and return data values that are compatible with the parameter. The attribute has no control over how this data is combined with other arguments - that's up to other attributes and ultimately NUnit itself. +A custom attribute implementing this interface should examine the `IParameterInfo` and return data values that are +compatible with the parameter. The attribute has no control over how this data is combined with other arguments - that's +up to other attributes and ultimately NUnit itself. The following NUnit attributes currently implement `IParameterDataSource`: diff --git a/docs/articles/nunit/extending-nunit/ISimpleTestBuilder-Interface.md b/docs/articles/nunit/extending-nunit/ISimpleTestBuilder-Interface.md index 007d9cb68..c9001661b 100644 --- a/docs/articles/nunit/extending-nunit/ISimpleTestBuilder-Interface.md +++ b/docs/articles/nunit/extending-nunit/ISimpleTestBuilder-Interface.md @@ -1,6 +1,7 @@ # ISimpleTestBuilder -This interface is used by attributes that know how to build a single, non-parameterized test from a `MethodInfo`. `ISimpleTestBuilder` is defined as follows: +This interface is used by attributes that know how to build a single, non-parameterized test from a `MethodInfo`. +`ISimpleTestBuilder` is defined as follows: ```csharp public interface ISimpleTestBuilder @@ -9,10 +10,18 @@ public interface ISimpleTestBuilder } ``` -`IMethodInfo` is an NUnit internal class used to wrap a `MethodInfo`. See the [source code](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/IMethodInfo.cs) for more info. The `suite` argument is the test suite that contains the method in question. +`IMethodInfo` is an NUnit internal class used to wrap a `MethodInfo`. See the [source +code](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/IMethodInfo.cs) for more info. +The `suite` argument is the test suite that contains the method in question. -Custom attributes implementing `ISimpleTestFixture` should examine the IMethodInfo provided and return a single `TestMethod` instance, as appropriate to that method. The BuildFrom method should never return null, even if the specified method is not valid for a test. In that case, it should return a `TestMethod` with a RunState of NonRunnable, in order to provide feedback to the user who placed the attribute on the method. +Custom attributes implementing `ISimpleTestFixture` should examine the IMethodInfo provided and return a single +`TestMethod` instance, as appropriate to that method. The BuildFrom method should never return null, even if the +specified method is not valid for a test. In that case, it should return a `TestMethod` with a RunState of NonRunnable, +in order to provide feedback to the user who placed the attribute on the method. -NUnit treats attributes implementing this interface specially. They are ignored if any other attributes are present that implement `ITestBuilder`. This allows, for example, use of `[Test]` on a method that also has `[Combinatorial]` specified, without any error arising. Such usage has existed in NUnit for some time and this special handling of the interface allows us to preserve it. +NUnit treats attributes implementing this interface specially. They are ignored if any other attributes are present that +implement `ITestBuilder`. This allows, for example, use of `[Test]` on a method that also has `[Combinatorial]` +specified, without any error arising. Such usage has existed in NUnit for some time and this special handling of the +interface allows us to preserve it. In the current build, only `TestAttribute` implements this interface. diff --git a/docs/articles/nunit/extending-nunit/ITestBuilder-Interface.md b/docs/articles/nunit/extending-nunit/ITestBuilder-Interface.md index f1d984f58..834777aa6 100644 --- a/docs/articles/nunit/extending-nunit/ITestBuilder-Interface.md +++ b/docs/articles/nunit/extending-nunit/ITestBuilder-Interface.md @@ -1,6 +1,7 @@ # ITestBuilder Interface -This interface is used by attributes that know how to build one or more parameterized `TestMethod` instances from a `MethodInfo`. `ITestMethodBuilder` is defined as follows: +This interface is used by attributes that know how to build one or more parameterized `TestMethod` instances from a +`MethodInfo`. `ITestMethodBuilder` is defined as follows: ```csharp public interface ITestBuilder @@ -9,11 +10,17 @@ public interface ITestBuilder } ``` -`IMethodInfo` is an NUnit internal class used to wrap a MethodInfo. See the [source code](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/IMethodInfo.cs) for more info. The `suite` argument is the test suite that contains the method in question. +`IMethodInfo` is an NUnit internal class used to wrap a MethodInfo. See the [source +code](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/IMethodInfo.cs) for more info. +The `suite` argument is the test suite that contains the method in question. -A custom attribute implementing this interface should examine the IMethodInfo and return as many `TestMethod` instances as it is able to construct, using the parameters available to it. Some attributes will only return a single test, just as `TestCaseAttribute` does. Others, working like `TheoryAttribute` may return multiple tests. If no data is available to create tests, an empty collection should be returned. +A custom attribute implementing this interface should examine the IMethodInfo and return as many `TestMethod` instances +as it is able to construct, using the parameters available to it. Some attributes will only return a single test, just +as `TestCaseAttribute` does. Others, working like `TheoryAttribute` may return multiple tests. If no data is available +to create tests, an empty collection should be returned. -If the returned tests are standard NUnit TestMethods, the helper class `NUnitTestCaseBuilder` may be used to create them. +If the returned tests are standard NUnit TestMethods, the helper class `NUnitTestCaseBuilder` may be used to create +them. The following NUnit attributes currently implement `ITestBuilder`: diff --git a/docs/articles/nunit/extending-nunit/Index.md b/docs/articles/nunit/extending-nunit/Index.md index 008c28c91..3dc10d3bb 100644 --- a/docs/articles/nunit/extending-nunit/Index.md +++ b/docs/articles/nunit/extending-nunit/Index.md @@ -1,6 +1,9 @@ # Extending NUnit -NUnit is intended to be extensible. We can't do everything for everybody but we want to make it reasonably easy to extend NUnit. In many cases, users will be able to implement a special feature outside of our scope by simply creating a new attribute that embeds the required logic. In other cases, particularly in extending the engine, we rely on a plugin-architecture. +NUnit is intended to be extensible. We can't do everything for everybody but we want to make it reasonably easy to +extend NUnit. In many cases, users will be able to implement a special feature outside of our scope by simply creating a +new attribute that embeds the required logic. In other cases, particularly in extending the engine, we rely on a +plugin-architecture. ## Types of Extensibility 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 index a086d5764..d2f073bee 100644 --- a/docs/articles/nunit/getting-started/dotnet-core-and-dotnet-standard.md +++ b/docs/articles/nunit/getting-started/dotnet-core-and-dotnet-standard.md @@ -1,18 +1,29 @@ # .NET Core and .NET Standard -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. +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. -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. +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. -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. +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. ## 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. +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. +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. -You can create a new NUnit test project using `dotnet new nunit`. It will create an ItemGroup in the csproj file with the necessary references. +You can create a new NUnit test project using `dotnet new nunit`. It will create an ItemGroup in the csproj file with +the necessary references. ```xml @@ -44,7 +55,8 @@ Or you can specify the csproj file you want to test dotnet test .\test\NetCore10Tests\NetCore10Tests.csproj ``` -For a more complete walk-through, please see [Testing .NET Core with NUnit in Visual Studio 2017](https://alteridem.net/2017/05/04/test-net-core-nunit-vs2017/) +For a more complete walk-through, please see [Testing .NET Core with NUnit in Visual Studio +2017](https://alteridem.net/2017/05/04/test-net-core-nunit-vs2017/) ## Using the NUnit project templates @@ -56,9 +68,15 @@ You can run `dotnet new nunit` to create an NUnit test project. #### Why can't my tests target .NET Standard -Visual Studio and VSTest require that the tests target a specific platform. .NET Standard is like a Portable library in that it does not target any specific platform, but can run on any supported platform. Microsoft decided that your tests should be compiled to target a platform so they know which platform to run your tests under and you get the behavior you expect for the platform you are targeting. You can however target multiple platforms in your tests and compile and run each from the command line. It still only runs one platform from Visual Studio, but I would hope that is being worked on. I haven't tested 15.3 yet. +Visual Studio and VSTest require that the tests target a specific platform. .NET Standard is like a Portable library in +that it does not target any specific platform, but can run on any supported platform. Microsoft decided that your tests +should be compiled to target a platform so they know which platform to run your tests under and you get the behavior you +expect for the platform you are targeting. You can however target multiple platforms in your tests and compile and run +each from the command line. It still only runs one platform from Visual Studio, but I would hope that is being worked +on. I haven't tested 15.3 yet. -It is similar to a console application, it cannot be .NET Standard, it must target a platform, .NET Core or .NET Framework. +It is similar to a console application, it cannot be .NET Standard, it must target a platform, .NET Core or .NET +Framework. This limitation is the same for all test adapters including xUnit and MSTest2. @@ -74,11 +92,16 @@ This limitation is the same for all test adapters including xUnit and MSTest2. This is a limitation of Visual Studio, hopefully it will be fixed in a future release. -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) +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 -`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). +`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). You run it by adding the setting on the command line (or in a runsettings file): @@ -86,6 +109,9 @@ You run it by adding the setting on the command line (or in a runsettings file): dotnet test -- NUnit.TestOutputXml=yourfoldername ``` -The folder is relative to a base folder determined by the OutputXmlFolder settings, or you can use an absolute path. The latter is useful in CI scenarios. +The folder is relative to a base folder determined by the OutputXmlFolder settings, or you can use an absolute path. The +latter is useful in CI scenarios. -Alternatively, there is a 3rd party package, [NUnitXml.TestLogger](https://www.nuget.org/packages/NunitXml.TestLogger/) which also produces a NUnit3 xml format. Details for [use see here](https://github.com/spekt/nunit.testlogger). Note that this is a re-implementation of the NUnit3 format, and may differ. +Alternatively, there is a 3rd party package, [NUnitXml.TestLogger](https://www.nuget.org/packages/NunitXml.TestLogger/) +which also produces a NUnit3 xml format. Details for [use see here](https://github.com/spekt/nunit.testlogger). Note +that this is a re-implementation of the NUnit3 format, and may differ. diff --git a/docs/articles/nunit/getting-started/installation.md b/docs/articles/nunit/getting-started/installation.md index 39e508d0f..1b4a45149 100644 --- a/docs/articles/nunit/getting-started/installation.md +++ b/docs/articles/nunit/getting-started/installation.md @@ -4,37 +4,44 @@ uid: installation # Installation -To install NUnit, you can use various installation approaches, depending upon your preferred development environment and preferences. +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. +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. +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. +> 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. +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. ## 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. +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. Rider has built-in support for NUnit, and is using the same template, so you'll achieve the same result. ## 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. +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): +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 @@ -93,15 +100,23 @@ 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 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. +If you need to update an existing test project to use NUnit -- perhaps a .NET 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. +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. +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. +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 @@ -119,41 +134,56 @@ Open the Browser tab, and Scroll or use search to locate the **NUnit** and **NUn ### NUnit and NUnit.Console -Install both packages. The **NUnit** package should be referenced by each of your test assemblies, but not by any others. +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. +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. [See here for more details of using the NUnit Console app](https://github.com/nunit/nunit-console#readme). ## NUnit3TestAdapter -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. +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. See [the Visual Studio Test Adapter](xref:vstestadapterinstallation) for details. > [!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. +> 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. ### Using NuGet NUnitLite Package -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. +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. -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. +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. -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. +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. +Download the latest binary zip of the NUnit Framework from our [Download page](https://nunit.org/download/). Unzip the +file into any convenient directory. -You can also download the latest binary zip or an MSI installer of the NUnit Console from [GitHub](https://github.com/nunit/nunit-console/releases). Unzip the file or install the MSI and then if you would like be able to run nunit3-console from the command line, put the bin directory, containing nunit3-console.exe on your path. +You can also download the latest binary zip or an MSI installer of the NUnit Console from +[GitHub](https://github.com/nunit/nunit-console/releases). Unzip the file or install the MSI and then if you would like +be able to run nunit3-console from the command line, put the bin directory, containing nunit3-console.exe on your path. -In your test assemblies, add a reference to nunit.framework.dll, using the copy in the subdirectory for the appropriate runtime version. For example, if you are targeting .NET 4.0, you should reference the framework assembly in the net-4.0 subdirectory. +In your test assemblies, add a reference to nunit.framework.dll, using the copy in the subdirectory for the appropriate +runtime version. For example, if you are targeting .NET 4.0, you should reference the framework assembly in the net-4.0 +subdirectory. -Run nunit3-console from the command line, giving it the path to your test assembly. To run NUnit's own framework tests from within the NUnit bin directory, enter: +Run nunit3-console from the command line, giving it the path to your test assembly. To run NUnit's own framework tests +from within the NUnit bin directory, enter: ```cmd nunit3-console net-2.0/nunit.framework.tests.dll @@ -161,6 +191,9 @@ Run nunit3-console from the command line, giving it the path to your test assemb ### Combined Approach -This approach is useful if you would like to use a single copy of nunit3-console with individual copies of the framework in each project. +This approach is useful if you would like to use a single copy of nunit3-console with individual copies of the framework +in each project. -Simply follow the zip file procedure to get a central copy of NUnit on your system. Then install the **NUnit Version 3** NuGet package in each of your test assemblies. For desktop use by developers, this approach may give you the best of both worlds. +Simply follow the zip file procedure to get a central copy of NUnit on your system. Then install the **NUnit Version 3** +NuGet package in each of your test assemblies. For desktop use by developers, this approach may give you the best of +both worlds. diff --git a/docs/articles/nunit/getting-started/upgrading.md b/docs/articles/nunit/getting-started/upgrading.md index 10cee1961..ed2109fdc 100644 --- a/docs/articles/nunit/getting-started/upgrading.md +++ b/docs/articles/nunit/getting-started/upgrading.md @@ -1,39 +1,34 @@ # Upgrading -This document assumes you are upgrading to NUnit 3.0 from NUnit 2.6 or -later. While it's possible to upgrade from an earlier version, you will -need to take into account many additional changes in NUnit, which are not -described here. If this is your situation, be sure to check the release -notes for earlier versions of NUnit as well. +This document assumes you are upgrading to NUnit 3.0 from NUnit 2.6 or later. While it's possible to upgrade from an +earlier version, you will need to take into account many additional changes in NUnit, which are not described here. If +this is your situation, be sure to check the release notes for earlier versions of NUnit as well. ## Review Breaking Changes -The [Breaking Changes](xref:breakingchanges) page -lists missing and changed functionality in NUnit 3.0. You should review this -page to see which items are likely to affect your own tests. +The [Breaking Changes](xref:breakingchanges) page lists missing and changed functionality in NUnit 3.0. You should +review this page to see which items are likely to affect your own tests. ## Update Your Code -In many cases, the items being removed have been deprecated for some time -and an alternate approach may already be available in your current release -of NUnit. If that is the case, it will probably save you time and effort if -you modify the code in your current environment before switching to NUnit 3.0. +In many cases, the items being removed have been deprecated for some time and an alternate approach may already be +available in your current release of NUnit. If that is the case, it will probably save you time and effort if you modify +the code in your current environment before switching to NUnit 3.0. -For example, NUnit 3.0 no longer supports **ExpectedExceptionAttribute**. -However, preferred alternatives **Assert.Throws** and the **ThrowsConstraint** -have been available for several years. If you remove the attribute from your -tests and use one of the alternatives instead, you can verify that they work -in your present environment and they will continue to work after conversion.** +For example, NUnit 3.0 no longer supports **ExpectedExceptionAttribute**. However, preferred alternatives +**Assert.Throws** and the **ThrowsConstraint** have been available for several years. If you remove the attribute from +your tests and use one of the alternatives instead, you can verify that they work in your present environment and they +will continue to work after conversion.** ## Switch to NUnit 3.0 -Remove references to your old version of NUnit and replace them with references -to NUnit 3.0. In the case of NUnitLite executable tests, you will need to reference -both the nunit.framework and NUnitLite assemblies. Compile your code. It's possible that you will find compiler errors due to breaking changes in NUnit 3.0, which you missed in the prior step. Make the necessary changes until it all works. +Remove references to your old version of NUnit and replace them with references to NUnit 3.0. In the case of NUnitLite +executable tests, you will need to reference both the nunit.framework and NUnitLite assemblies. Compile your code. It's +possible that you will find compiler errors due to breaking changes in NUnit 3.0, which you missed in the prior step. +Make the necessary changes until it all works. ## Make the Tests Pass -Hopefully, you aren't converting tests that were not passing when you started! -If all goes well, they will continue to pass under NUnit 3.0. If not, investigate -each case and make necessary changes. If something isn't working as advertised, -please let us know. +Hopefully, you aren't converting tests that were not passing when you started! If all goes well, they will continue to +pass under NUnit 3.0. If not, investigate each case and make necessary changes. If something isn't working as +advertised, please let us know. diff --git a/docs/articles/nunit/intro.md b/docs/articles/nunit/intro.md index 41a3ae123..fbb52ed31 100644 --- a/docs/articles/nunit/intro.md +++ b/docs/articles/nunit/intro.md @@ -8,6 +8,7 @@ This documentation covers NUnit 3.0 and higher. Where applicable, we have marked sections with the version in which a feature first appeared. -If you are new to NUnit, we suggest you begin by reading the Getting Started section of this site. Those who have used earlier releases may want to begin with the Upgrading section. +If you are new to NUnit, we suggest you begin by reading the Getting Started section of this site. Those who have used +earlier releases may want to begin with the Upgrading section. See the [Release Notes](xref:frameworkreleasenotes) for more information on each release. diff --git a/docs/articles/nunit/release-notes/Pre-3.5-Release-Notes.md b/docs/articles/nunit/release-notes/Pre-3.5-Release-Notes.md index 77c67dbd6..5e4b30154 100644 --- a/docs/articles/nunit/release-notes/Pre-3.5-Release-Notes.md +++ b/docs/articles/nunit/release-notes/Pre-3.5-Release-Notes.md @@ -5,21 +5,21 @@ uid: pre35releasenotes # Pre 3.5 Release Notes > [!NOTE] -> Combined Release Notes for the NUnit framework, console and engine, up to version 3.5. For later releases, see: +> Combined Release Notes for the NUnit framework, console and engine, up to version 3.5. For later releases, +> see: > > * [Framework Release Notes](framework.md) > * [Console Release Notes](xref:consoleenginereleasenotes) ## NUnit 3.5 - October 3, 2016 -This is the last version of NUnit where the framework, console runner, engine and extensions are being -released together. From this point forward, the NUnit Framework will be -released on its own schedule that is not bound to that of any other NUnit project and version numbers -may diverge over time. +This is the last version of NUnit where the framework, console runner, engine and extensions are being released +together. From this point forward, the NUnit Framework will be released on its own schedule that is not bound to that of +any other NUnit project and version numbers may diverge over time. -This is also the first release where the NUnit Framework will not be included in the installer. Only -the console runner, engine and extensions will be available as an MSI installer. We recommend that you -use the NUnit NuGet packages for the framework, but a ZIP file with the binaries will also be available. +This is also the first release where the NUnit Framework will not be included in the installer. Only the console runner, +engine and extensions will be available as an MSI installer. We recommend that you use the NUnit NuGet packages for the +framework, but a ZIP file with the binaries will also be available. ### Framework @@ -63,8 +63,7 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Console Runner -* A new option, --list-extensions, will display all the engine extensions that - have been installed by the engine. +* A new option, --list-extensions, will display all the engine extensions that have been installed by the engine. ### Issues Resolved @@ -78,10 +77,10 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Framework * Improvements in comparing equality using `IEquatable` -* Test case names will only be truncated if the runner requests it or it is overridden on the command line - with the --test-name-format option -* The .NET 2.0 version of the framework now includes LINQ. If your tests target .NET 2.0, you can now use - LINQ queries in your tests +* Test case names will only be truncated if the runner requests it or it is overridden on the command line with the + --test-name-format option +* The .NET 2.0 version of the framework now includes LINQ. If your tests target .NET 2.0, you can now use LINQ queries + in your tests ### Engine @@ -92,10 +91,9 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Console Runner -* There is a new --params command line option that allows you to pass parameters to your tests - which can be retrieved using TestContext.Parameters -* Another new command line option `--loaduserprofile` causes the User Profile to be loaded into the - NUnit Agent process. +* There is a new --params command line option that allows you to pass parameters to your tests which can be retrieved + using TestContext.Parameters +* Another new command line option `--loaduserprofile` causes the User Profile to be loaded into the NUnit Agent process. #### Issues Resolved @@ -244,7 +242,8 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries * 1171 A bug when using Assert.That() with Is.Not.Empty * 1185 Engine finds .NET 4.0 Client Profile twice * 1187 ITestAssemblyRunner.StopRun as implemented by NUnitTestAssemblyRunner -* 1195 name attribute in test-suite and test-results element of output xml is different to nunit 2.6.4 using nunit2-format +* 1195 name attribute in test-suite and test-results element of output xml is different to nunit 2.6.4 using + nunit2-format * 1196 Custom value formatter for v3 via MsgUtils * 1210 Available runtimes issues * 1230 Add ability for `testcasedatasource` to have parameters passed to methods @@ -266,7 +265,8 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Console Runner * The NUnit.Runners NuGet package was updated to become a meta-package that pulls in the NUnit.Console package -* Reinstated the --pause command line option that will display a message box allowing you to attach a debugger if the --debug option does not work +* Reinstated the --pause command line option that will display a message box allowing you to attach a debugger if the + --debug option does not work ### Issues Resolved @@ -286,7 +286,8 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries * 1055 nunit3 console runner --where option does not return error on invalid selection string * 1060 Remove "Version 3" from NUnit Nuget Package * 1061 Nunit30Settings.xml becomes corrupted -* 1062 Console.WriteLine statements in "OneTimeSetUp" and "OneTimeTearDown" annotated methods are not directed to the console when using nunit3-console.exe runner +* 1062 Console.WriteLine statements in "OneTimeSetUp" and "OneTimeTearDown" annotated methods are not directed to the + console when using nunit3-console.exe runner * 1063 Error in Random Test ## NUnit 3.0.0 Final Release (3.0.5797) - November 15, 2015 @@ -299,10 +300,12 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Engine -* The engine now only sets the config file for project.nunit to project.config if project.config exists. Otherwise, each assembly uses its own config, provided it is run in a separate AppDomain by itself. +* The engine now only sets the config file for project.nunit to project.config if project.config exists. Otherwise, each + assembly uses its own config, provided it is run in a separate AppDomain by itself. > [!NOTE] -> It is not possible for multiple assemblies in the same AppDomain to use different configs. This is not an NUnit limitation, it's just how configs work! +> It is not possible for multiple assemblies in the same AppDomain to use different configs. This is not an +> NUnit limitation, it's just how configs work! ### Issues Resolved @@ -337,7 +340,8 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries * The portable build now supports ASP.NET 5 and the new Core CLR. > [!NOTE] -> The `nunit3-console` runner cannot run tests that reference the portable build. You may run such tests using NUnitLite or a platform-specific runner. +> The `nunit3-console` runner cannot run tests that reference the portable build. You may run such tests using +> NUnitLite or a platform-specific runner. * `TestCaseAttribute` and `TestCaseData` now allow modifying the test name without replacing it entirely. * The SilverLight packages for are now separate downloads. @@ -391,20 +395,27 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Framework * Parameterized test cases now support nullable arguments. -* The NUnit framework may now be built for the .NET Core framework. Note that this is only available through building the source code. A binary will be available in the next release. +* The NUnit framework may now be built for the .NET Core framework. Note that this is only available through building + the source code. A binary will be available in the next release. ### Engine * The engine now runs multiple test assemblies in parallel by default -* The output XML now includes more information about the test run, including the text of the command used, any engine settings and the filter used to select tests. -* Extensions may now specify data in an identifying attribute, for use by the engine in deciding whether to load that extension. +* The output XML now includes more information about the test run, including the text of the command used, any engine + settings and the filter used to select tests. +* Extensions may now specify data in an identifying attribute, for use by the engine in deciding whether to load that + extension. ### Console Runner * The console now displays all settings used by the engine to run tests as well as the filter used to select tests. -* The console runner accepts a new option `--maxagents`. If multiple assemblies are run in separate processes, this value may be used to limit the number that are executed simultaneously in parallel. -* The console runner no longer accepts the --include and --exclude options. Instead, the new --where option provides a more general way to express which tests will be executed, such as --where "cat==Fast && Priority==High". See the docs for details of the syntax. -* The new --debug option causes NUnit to break in the debugger immediately before tests are run. This simplifies debugging, especially when the test is run in a separate process. +* The console runner accepts a new option `--maxagents`. If multiple assemblies are run in separate processes, this + value may be used to limit the number that are executed simultaneously in parallel. +* The console runner no longer accepts the --include and --exclude options. Instead, the new --where option provides a + more general way to express which tests will be executed, such as --where "cat==Fast && Priority==High". See the docs + for details of the syntax. +* The new --debug option causes NUnit to break in the debugger immediately before tests are run. This simplifies + debugging, especially when the test is run in a separate process. ### Issues Resolved @@ -418,7 +429,8 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries * 669 TeamCity service message should have assembly name as a part of test name. * 689 The TeamCity service message "testFinished" should have an integer value in the "duration" attribute * 713 Include command information in XML -* 719 We have no way to configure tests for several assemblies using NUnit project file and the common installation from msi file +* 719 We have no way to configure tests for several assemblies using NUnit project file and the common installation from + msi file * 735 Workers number in xml report file cannot be found * 784 Build Portable Framework on Linux * 790 Allow Extensions to provide data through an attribute @@ -493,24 +505,24 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Framework * The RangeAttribute has been extended to support more data types including uint, long and ulong -* Added platform support for Windows 10 and fixed issues with Windows 8 and - 8.1 support +* Added platform support for Windows 10 and fixed issues with Windows 8 and 8.1 support * Added async support to the portable version of NUnit Framework -* The named members of the TestCaseSource and ValueSource attributes must now be - static. -* RandomAttribute has been extended to add support for new data types including uint, long, ulong, short, ushort, float, byte and sbyte -* TestContext.Random has also been extended to add support for new data types including uint, long, ulong, short, ushort, float, byte, sbyte and decimal -* Removed the dependency on Microsoft.Bcl.Async from the NUnit Framework assembly - targeting .NET 4.0. If you want to write async tests in .NET 4.0, you will need - to reference the NuGet package yourself. -* Added a new TestFixtureSource attribute which is the equivalent to TestCaseSource - but provides for instantiation of fixtures. -* Significant improvements have been made in how NUnit deduces the type arguments of generic methods based on the arguments provided. +* The named members of the TestCaseSource and ValueSource attributes must now be static. +* RandomAttribute has been extended to add support for new data types including uint, long, ulong, short, ushort, float, + byte and sbyte +* TestContext.Random has also been extended to add support for new data types including uint, long, ulong, short, + ushort, float, byte, sbyte and decimal +* Removed the dependency on Microsoft.Bcl.Async from the NUnit Framework assembly targeting .NET 4.0. If you want to + write async tests in .NET 4.0, you will need to reference the NuGet package yourself. +* Added a new TestFixtureSource attribute which is the equivalent to TestCaseSource but provides for instantiation of + fixtures. +* Significant improvements have been made in how NUnit deduces the type arguments of generic methods based on the + arguments provided. ### Engine -* If the target framework is not specified, test assemblies that are compiled - to target .NET 4.5 will no longer run in .NET 4.0 compatibility mode +* If the target framework is not specified, test assemblies that are compiled to target .NET 4.5 will no longer run in + .NET 4.0 compatibility mode ### Console @@ -550,19 +562,19 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Framework -* The Compact Framework version of the framework is now packaged separately - and will be distributed as a ZIP file and as a NuGet package. +* The Compact Framework version of the framework is now packaged separately and will be distributed as a ZIP file and as + a NuGet package. * The NUnit 2.x RepeatAttribute was added back into the framework. * Added Throws.ArgumentNullException * Added GetString methods to NUnit.Framework.Internal.RandomGenerator to create repeatable random strings for testing * When checking the equality of DateTimeOffset, you can now use the WithSameOffset modifier -* Some classes intended for internal usage that were public for testing - have now been made internal. Additional classes will be made internal - for the final 3.0 release. +* Some classes intended for internal usage that were public for testing have now been made internal. Additional classes + will be made internal for the final 3.0 release. ### Engine -* Added a core engine which is a non-extensible, minimal engine for use by devices and similar situations where reduced functionality is compensated for by reduced size and simplicity of usage. +* Added a core engine which is a non-extensible, minimal engine for use by devices and similar situations where reduced + functionality is compensated for by reduced size and simplicity of usage. ### Issues Resolved @@ -613,8 +625,10 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Framework -* We no longer create a separate framework build for .NET 3.5. The 2.0 and 3.5 builds were essentially the same, so the former should now be used under both runtimes. -* A new Constraint, **DictionaryContainsKeyConstraint**, may be used to test that a specified key is present in a dictionary. +* We no longer create a separate framework build for .NET 3.5. The 2.0 and 3.5 builds were essentially the same, so the + former should now be used under both runtimes. +* A new Constraint, **DictionaryContainsKeyConstraint**, may be used to test that a specified key is present in a + dictionary. * **LevelOfParallelizationAttribute** has been renamed to **LevelOfParallelismAttribute**. * The SilverLight runner now displays output in color and includes any text output created by the tests. * The class and method names of each test are included in the output xml where applicable. @@ -622,8 +636,12 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Engine -* The engine API has now been finalized. It permits specifying a minimum version of the engine that a runner is able to use. The best installed version of the engine will be loaded. Third-party runners may override the selection process by including a copy of the engine in their installation directory and specifying that it must be used. -* The V2 framework driver now uses the event listener and test listener passed to it by the runner. This corrects several outstanding issues caused by events not being received and allows selecting V2 tests to be run from the command-line, in the same way that V3 tests are selected. +* The engine API has now been finalized. It permits specifying a minimum version of the engine that a runner is able to + use. The best installed version of the engine will be loaded. Third-party runners may override the selection process + by including a copy of the engine in their installation directory and specifying that it must be used. +* The V2 framework driver now uses the event listener and test listener passed to it by the runner. This corrects + several outstanding issues caused by events not being received and allows selecting V2 tests to be run from the + command-line, in the same way that V3 tests are selected. ### Console @@ -664,14 +682,17 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Framework -* TestCaseAttribute now allows arguments with default values to be omitted. Additionally, it accepts IncludePlatform and ExcludePlatform properties to specify the platforms on which the test case should be run. -* TestFixture and TestCase attributes now enforce the requirement that a reason needs to be provided when ignoring a test. +* TestCaseAttribute now allows arguments with default values to be omitted. Additionally, it accepts IncludePlatform and + ExcludePlatform properties to specify the platforms on which the test case should be run. +* TestFixture and TestCase attributes now enforce the requirement that a reason needs to be provided when ignoring a + test. * SetUp, TearDown, OneTimeSetUp and OneTimeTearDown methods may now be async. * String arguments over 20 characters in length are truncated when used as part of a test name. ### Engine -* The engine is now extensible using Mono.Addins. In this release, extension points are provided for FrameworkDrivers, ProjectLoaders and OutputWriters. The following addins are bundled as a part of NUnit: +* The engine is now extensible using Mono.Addins. In this release, extension points are provided for FrameworkDrivers, + ProjectLoaders and OutputWriters. The following addins are bundled as a part of NUnit: * A FrameworkDriver that allows running NUnit V2 tests under NUnit 3.0. * ProjectLoaders for NUnit and Visual Studio projects. * An OutputWriter that creates XML output in NUnit V2 format. @@ -723,8 +744,8 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries * Visual Studio solutions (.sln) * Legacy C++ and Visual JScript projects (.csproj and .vjsproj) are also supported * Support for the current C++ format (.csxproj) is not yet available -* Creation of output files like TestResult.xml in various formats is now a - service of the engine, available to any runner. +* Creation of output files like TestResult.xml in various formats is now a service of the engine, available to any + runner. ### Console @@ -761,11 +782,11 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Framework -* The NUnit and NUnitLite frameworks have now been merged. There is no longer any distinction - between them in terms of features, although some features are not available on all platforms. -* The release includes two new framework builds: compact framework 3.5 and portable. The portable - library is compatible with .NET 4.5, SilverLight 5.0, Windows 8, Windows Phone 8.1, - Windows Phone SilverLight 8, Mono for Android and MonoTouch. +* The NUnit and NUnitLite frameworks have now been merged. There is no longer any distinction between them in terms of + features, although some features are not available on all platforms. +* The release includes two new framework builds: compact framework 3.5 and portable. The portable library is compatible + with .NET 4.5, SilverLight 5.0, Windows 8, Windows Phone 8.1, Windows Phone SilverLight 8, Mono for Android and + MonoTouch. * A number of previously unsupported features are available for the Compact Framework: * Generic methods as tests * RegexConstraint @@ -774,17 +795,17 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Engine -* The logic of runtime selection has now changed so that each assembly runs by default - in a separate process using the runtime for which it was built. -* On 64-bit systems, each test process is automatically created as 32-bit or 64-bit, - depending on the platform specified for the test assembly. +* The logic of runtime selection has now changed so that each assembly runs by default in a separate process using the + runtime for which it was built. +* On 64-bit systems, each test process is automatically created as 32-bit or 64-bit, depending on the platform specified + for the test assembly. ### Console -* The console runner now runs tests in a separate process per assembly by default. They may - still be run in process or in a single separate process by use of command-line options. -* The console runner now starts in the highest version of the .NET runtime available, making - it simpler to debug tests by specifying that they should run in-process on the command-line. +* The console runner now runs tests in a separate process per assembly by default. They may still be run in process or + in a single separate process by use of command-line options. +* The console runner now starts in the highest version of the .NET runtime available, making it simpler to debug tests + by specifying that they should run in-process on the command-line. * The -x86 command-line option is provided to force execution in a 32-bit process on a 64-bit system. * A writability check is performed for each output result file before trying to run the tests. * The -teamcity option is now supported. @@ -826,7 +847,8 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries * The console runner no longer displays test results in the debugger. * The NUnitLite compact framework 2.0 build has been removed. -* All addin support has been removed from the framework. Documentation of NUnit 3.0 extensibility features will be published in time for the beta release. In the interim, please ask for support on the nunit-discuss list. +* All addin support has been removed from the framework. Documentation of NUnit 3.0 extensibility features will be + published in time for the beta release. In the interim, please ask for support on the nunit-discuss list. ### General @@ -840,9 +862,12 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries * The NUnitLite report output has been standardized to match that of nunit-console. * The NUnitLite command-line has been standardized to match that of nunit-console where they share the same options. * Both nunit-console and NUnitLite now display output in color. -* ActionAttributes now allow specification of multiple targets on the attribute as designed. This didn't work in the first alpha. -* OneTimeSetUp and OneTimeTearDown failures are now shown on the test report. Individual test failures after OneTimeSetUp failure are no longer shown. -* The console runner refuses to run tests build with older versions of NUnit. A plugin will be available to run older tests in the future. +* ActionAttributes now allow specification of multiple targets on the attribute as designed. This didn't work in the + first alpha. +* OneTimeSetUp and OneTimeTearDown failures are now shown on the test report. Individual test failures after + OneTimeSetUp failure are no longer shown. +* The console runner refuses to run tests build with older versions of NUnit. A plugin will be available to run older + tests in the future. ### Issues Resolved @@ -930,16 +955,20 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries ### Breaking Changes * NUnit no longer supports void async test methods. You should use a Task return Type instead. -* The ExpectedExceptionAttribute is no longer supported. Use Assert.Throws() or Assert.That(..., Throws) instead for a more precise specification of where the exception is expected to be thrown. +* The ExpectedExceptionAttribute is no longer supported. Use Assert.Throws() or Assert.That(..., Throws) instead for a + more precise specification of where the exception is expected to be thrown. ### New Features -* Parallel test execution is supported down to the Fixture level. Use ParallelizableAttribute to indicate types that may be run in parallel. +* Parallel test execution is supported down to the Fixture level. Use ParallelizableAttribute to indicate types that may + be run in parallel. * Async tests are supported for .NET 4.0 if the user has installed support for them. * A new FileExistsConstraint has been added along with FileAssert.Exists and FileAssert.DoesNotExist * ExpectedResult is now supported on simple (non-TestCase) tests. -* The Ignore attribute now takes a named parameter Until, which allows specifying a date after which the test is no longer ignored. -* The following new values are now recognized by PlatformAttribute: Win7, Win8, Win8.1, Win2012Server, Win2012ServerR2, NT6.1, NT6.2, 32-bit, 64-bit +* The Ignore attribute now takes a named parameter Until, which allows specifying a date after which the test is no + longer ignored. +* The following new values are now recognized by PlatformAttribute: Win7, Win8, Win8.1, Win2012Server, Win2012ServerR2, + NT6.1, NT6.2, 32-bit, 64-bit * TimeoutAttribute is now supported under SilverLight * ValuesAttribute may be used without any values on an enum or boolean argument. All possible values are used. * You may now specify a tolerance using Within when testing equality of DateTimeOffset values. @@ -986,7 +1015,8 @@ use the NUnit NuGet packages for the framework, but a ZIP file with the binaries * Separate projects for nunit-console and nunit.engine * New builds for .NET 4.5 and SilverLight -* TestContext is now supported and includes an additional property, **Random**, which may be used to generate repeatable random values for use in a test. +* TestContext is now supported and includes an additional property, **Random**, which may be used to generate repeatable + random values for use in a test. * The external framework API is now stable; internal interfaces are separate from API * Tests may be run in parallel on separate threads * Solutions and projects now use VS2012 (except for Compact framework) diff --git a/docs/articles/nunit/release-notes/breaking-changes.md b/docs/articles/nunit/release-notes/breaking-changes.md index d41ca6124..50507a48b 100644 --- a/docs/articles/nunit/release-notes/breaking-changes.md +++ b/docs/articles/nunit/release-notes/breaking-changes.md @@ -26,23 +26,35 @@ uid: breakingchanges ## NUnit 3.7 -* The AssertionHelper class has now been deprecated. Users can use the [NUnit.StaticExpect](https://github.com/fluffynuts/NUnit.StaticExpect) library as a near drop-in replacement. +* The AssertionHelper class has now been deprecated. Users can use the + [NUnit.StaticExpect](https://github.com/fluffynuts/NUnit.StaticExpect) library as a near drop-in replacement. ## NUnit 3.4 Breaking changes introduced in NUnit 3.4 -* The `--teamcity` console command-line option now requires the TeamCityEventListener extension to be installed. This only affects users who install the extensions individually or copy them to another directory. If you install using the Windows installer or the NUnit.Console NuGet package the TeamCity extension is included. +* The `--teamcity` console command-line option now requires the TeamCityEventListener extension to be installed. This + only affects users who install the extensions individually or copy them to another directory. If you install using the + Windows installer or the NUnit.Console NuGet package the TeamCity extension is included. * String arguments in the names of test cases are no longer truncated to 40 characters. -* The .NET 2.0 build of the nunit framework uses a private implementation of System.Linq. NUnit installs the NUnit.System.Linq assembly alongside the nunit.framework assembly. If you copy the framework to another location, you must ensure that both are copied. The extra assembly is not used in other builds because System.Linq is already supported in those environments. +* The .NET 2.0 build of the nunit framework uses a private implementation of System.Linq. NUnit installs the + NUnit.System.Linq assembly alongside the nunit.framework assembly. If you copy the framework to another location, you + must ensure that both are copied. The extra assembly is not used in other builds because System.Linq is already + supported in those environments. ## NUnit 3.0 -A relatively large number of features present in NUnit 2.6, were either removed in NUnit 3.0 or had their behavior modified in a way that will break existing code. +A relatively large number of features present in NUnit 2.6, were either removed in NUnit 3.0 or had their behavior +modified in a way that will break existing code. -A key change is that the NUnit Test Engine will not recognize a test assembly that does not reference the NUnit framework directly. Normally, test assemblies use NUnit Asserts, attributes and other Types and methods. However, certain third-party frameworks are designed to completely isolate the user from the details of NUnit. They mediate between the test assembly and the NUnit framework in order to run tests. In such a case, NUnit will indicate that the assembly either contains no tests or the proper driver could not be found. To resolve this situation, simply add one NUnit attribute or other reference. An assembly-level `ParallelizableAttribute` is useful for this purpose. +A key change is that the NUnit Test Engine will not recognize a test assembly that does not reference the NUnit +framework directly. Normally, test assemblies use NUnit Asserts, attributes and other Types and methods. However, +certain third-party frameworks are designed to completely isolate the user from the details of NUnit. They mediate +between the test assembly and the NUnit framework in order to run tests. In such a case, NUnit will indicate that the +assembly either contains no tests or the proper driver could not be found. To resolve this situation, simply add one +NUnit attribute or other reference. An assembly-level `ParallelizableAttribute` is useful for this purpose. Other breaking changes are grouped in the following tables. @@ -102,7 +114,8 @@ Other breaking changes are grouped in the following tables. ### Console Features -The console runner is now called `nunit3-console`. The following breaking changes apply to the options that the new runner supports. +The console runner is now called `nunit3-console`. The following breaking changes apply to the options that the new +runner supports. | Option | Function | Notes | |-------------------|-----------------------------------------|--------------------------| diff --git a/docs/articles/nunit/release-notes/framework.md b/docs/articles/nunit/release-notes/framework.md index 0d06941a1..14d1695cd 100644 --- a/docs/articles/nunit/release-notes/framework.md +++ b/docs/articles/nunit/release-notes/framework.md @@ -6,145 +6,266 @@ uid: frameworkreleasenotes ## NUnit 4.0.0-beta.1 - October 8. 2023 -This is the first beta release of version 4 of NUnit. This is an incremental improvement of version 3, and can be used with the same runners as before, although a minor upgrade might be needed for some. For the `NUnit3TestAdapter`, you will need version 4.5 to run tests with NUnit 4. +This is the first beta release of version 4 of NUnit. This is an incremental improvement of version 3, and can be used +with the same runners as before, although a minor upgrade might be needed for some. For the `NUnit3TestAdapter`, you +will need version 4.5 to run tests with NUnit 4. This release has more than 50 fixes and improvements implemented. The minimum target framework supported is now dotnet framework 4.6.2, and .net 6.0. -See the [planning notes](../Towards-NUnit4.md) for more information about the changes, and also information on the breaking changes in this release. +See the [planning notes](../Towards-NUnit4.md) for more information about the changes, and also information on the +breaking changes in this release. (The list below is work in progress, and includes issues that is fixed in the upcoming next release, beta.2 or final) ### Credits -All issues marked "Fixed by team" has been done by [the guys in the frameworkteam](https://docs.nunit.org/articles/developer-info/The-Teams.html#current-team-memberships-listed-in-a-kind-of-chronological-order). Issues marked "Thanks to" has been done by external contributors. We appreciate all the work all these people have been doing! +All issues marked "Fixed by team" has been done by [the members of the framework team][TeamLink]. +Issues marked "Thanks to" has been done by external contributors. We appreciate all the work all these people have been +doing! There are 108 issues fixed in this release. ### Enhancements -* [4521](https://github.com/nunit/nunit/issues/4521) Proposal: Async test case sources . Fixed by team [PR 4389](https://github.com/nunit/nunit/pull/4389) -* [4489](https://github.com/nunit/nunit/issues/4489) Use buffer pooling when calculating partition filters. Fixed by team [PR 4500](https://github.com/nunit/nunit/pull/4500) -* [4476](https://github.com/nunit/nunit/issues/4476) Add support to `StreamsComparer` for non-seekable streams. Thanks to [Michael Render](https://github.com/RenderMichael) for [PR 4483](https://github.com/nunit/nunit/pull/4483) -* [4433](https://github.com/nunit/nunit/issues/4433) Add string syntax attributes (.NET 7+). Thanks to [Michael Render](https://github.com/RenderMichael) for [PR 4425](https://github.com/nunit/nunit/pull/4425) -* [4431](https://github.com/nunit/nunit/issues/4431) Improving error message handling and performing assert consolidation. Fixed by team [PR 4430](https://github.com/nunit/nunit/pull/4430) -* [4421](https://github.com/nunit/nunit/issues/4421) Add support for native .NET-6.0 target . Fixed by team [PR 4431](https://github.com/nunit/nunit/pull/4431) -* [4413](https://github.com/nunit/nunit/issues/4413) Assert.That methods should autogenerate message, if null. Fixed by team [PR 4419](https://github.com/nunit/nunit/pull/4419) -* [4394](https://github.com/nunit/nunit/issues/4394) Expand NUnitEquality to use Equality of all Properties. Fixed by team [PR 4436](https://github.com/nunit/nunit/pull/4436) -* [4391](https://github.com/nunit/nunit/issues/4391) Hash/Partition based Test Filter. Thanks to [Andrew Armstrong](https://github.com/Plasma) for [PR 4392](https://github.com/nunit/nunit/pull/4392) -* [4385](https://github.com/nunit/nunit/issues/4385) Add support for Test Cancellation. Fixed by team [PR 4386](https://github.com/nunit/nunit/pull/4386) -* [4355](https://github.com/nunit/nunit/issues/4355) Allow Is.AnyOf to be called with arrays or other collections. Fixed by team [PR 4356](https://github.com/nunit/nunit/pull/4356) -* [4149](https://github.com/nunit/nunit/issues/4149) Distribute optimized framework builds with easy debugging. Thanks to [Marko Lahma](https://github.com/lahma) for [PR 4350](https://github.com/nunit/nunit/pull/4350) -* [4144](https://github.com/nunit/nunit/issues/4144) Stderr/Console.Error will hold back unicode escaped log messages. Thanks to [Max Schmitt](https://github.com/mxschmitt) for [PR 4145](https://github.com/nunit/nunit/pull/4145) -* [4101](https://github.com/nunit/nunit/issues/4101) Expose ExpectedResult to the TestContext. Fixed by team [PR 4239](https://github.com/nunit/nunit/pull/4239) -* [4086](https://github.com/nunit/nunit/issues/4086) Perform case-insensitive string comparisons in-place. Fixed by team [PR 4088](https://github.com/nunit/nunit/pull/4088) -* [4053](https://github.com/nunit/nunit/issues/4053) Cache method discovery by migrating PR 4034 to main. Fixed by team [PR 4208](https://github.com/nunit/nunit/pull/4208) -* [3984](https://github.com/nunit/nunit/issues/3984) Add net6.0 targets. Fixed by team [PR 3988](https://github.com/nunit/nunit/pull/3988) -* [3936](https://github.com/nunit/nunit/issues/3936) Is there any way we could make use of CallerArgumentExpressionAttribute?. Fixed by team [PR 4419](https://github.com/nunit/nunit/pull/4419) -* [3899](https://github.com/nunit/nunit/issues/3899) Allow randomizing 'Guid' test arguments with [Random]. Thanks to [Arnaud TAMAILLON](https://github.com/Greybird) for [PR 3951](https://github.com/nunit/nunit/pull/3951) -* [3866](https://github.com/nunit/nunit/issues/3866) SupportedOSPlatform. Fixed by team [PR 3926](https://github.com/nunit/nunit/pull/3926) -* [3856](https://github.com/nunit/nunit/issues/3856) Theories in nested Testfixtures. Thanks to [Felix Kr”ner](https://github.com/Crown0815) for [PR 3857](https://github.com/nunit/nunit/pull/3857) -* [3718](https://github.com/nunit/nunit/issues/3718) Improve readability of "assert failed" message for DictionaryContainsKeyValuePairConstraint WithValue(). Fixed by team [PR 3778](https://github.com/nunit/nunit/pull/3778) -* [3457](https://github.com/nunit/nunit/issues/3457) Add DefaultConstraint. Thanks to [Oleksandr Liakhevych](https://github.com/Dreamescaper) for [PR 3781](https://github.com/nunit/nunit/pull/3781) -* [3432](https://github.com/nunit/nunit/issues/3432) Assert.That is blocking and might lead to deadlock when used with WCF.. Thanks to [Gavin Lambert](https://github.com/uecasm) for [PR 4322](https://github.com/nunit/nunit/pull/4322) -* [2843](https://github.com/nunit/nunit/issues/2843) Replacing ThrowsAsync with a composable async alternative. Thanks to [Gavin Lambert](https://github.com/uecasm) for [PR 4322](https://github.com/nunit/nunit/pull/4322) -* [1459](https://github.com/nunit/nunit/issues/1459) Support for params keyword in parameterized test fixtures. Thanks to [](https://github.com/Shiney) for [PR 4478](https://github.com/nunit/nunit/pull/4478) +* [4521](https://github.com/nunit/nunit/issues/4521) Proposal: Async test case sources . Fixed by team [PR + 4389](https://github.com/nunit/nunit/pull/4389) +* [4489](https://github.com/nunit/nunit/issues/4489) Use buffer pooling when calculating partition filters. Fixed by + team [PR 4500](https://github.com/nunit/nunit/pull/4500) +* [4476](https://github.com/nunit/nunit/issues/4476) Add support to `StreamsComparer` for non-seekable streams. Thanks + to [Michael Render](https://github.com/RenderMichael) for [PR 4483](https://github.com/nunit/nunit/pull/4483) +* [4433](https://github.com/nunit/nunit/issues/4433) Add string syntax attributes (.NET 7+). Thanks to [Michael + Render](https://github.com/RenderMichael) for [PR 4425](https://github.com/nunit/nunit/pull/4425) +* [4431](https://github.com/nunit/nunit/issues/4431) Improving error message handling and performing assert + consolidation. Fixed by team [PR 4430](https://github.com/nunit/nunit/pull/4430) +* [4421](https://github.com/nunit/nunit/issues/4421) Add support for native .NET-6.0 target . Fixed by team [PR + 4431](https://github.com/nunit/nunit/pull/4431) +* [4413](https://github.com/nunit/nunit/issues/4413) Assert.That methods should autogenerate message, if null. Fixed by + team [PR 4419](https://github.com/nunit/nunit/pull/4419) +* [4394](https://github.com/nunit/nunit/issues/4394) Expand NUnitEquality to use Equality of all Properties. Fixed by + team [PR 4436](https://github.com/nunit/nunit/pull/4436) +* [4391](https://github.com/nunit/nunit/issues/4391) Hash/Partition based Test Filter. Thanks to [Andrew + Armstrong](https://github.com/Plasma) for [PR 4392](https://github.com/nunit/nunit/pull/4392) +* [4385](https://github.com/nunit/nunit/issues/4385) Add support for Test Cancellation. Fixed by team [PR + 4386](https://github.com/nunit/nunit/pull/4386) +* [4355](https://github.com/nunit/nunit/issues/4355) Allow Is.AnyOf to be called with arrays or other collections. Fixed + by team [PR 4356](https://github.com/nunit/nunit/pull/4356) +* [4149](https://github.com/nunit/nunit/issues/4149) Distribute optimized framework builds with easy debugging. Thanks + to [Marko Lahma](https://github.com/lahma) for [PR 4350](https://github.com/nunit/nunit/pull/4350) +* [4144](https://github.com/nunit/nunit/issues/4144) Stderr/Console.Error will hold back unicode escaped log messages. + Thanks to [Max Schmitt](https://github.com/mxschmitt) for [PR 4145](https://github.com/nunit/nunit/pull/4145) +* [4101](https://github.com/nunit/nunit/issues/4101) Expose ExpectedResult to the TestContext. Fixed by team [PR + 4239](https://github.com/nunit/nunit/pull/4239) +* [4086](https://github.com/nunit/nunit/issues/4086) Perform case-insensitive string comparisons in-place. Fixed by team + [PR 4088](https://github.com/nunit/nunit/pull/4088) +* [4053](https://github.com/nunit/nunit/issues/4053) Cache method discovery by migrating PR 4034 to main. Fixed by team + [PR 4208](https://github.com/nunit/nunit/pull/4208) +* [3984](https://github.com/nunit/nunit/issues/3984) Add net6.0 targets. Fixed by team [PR + 3988](https://github.com/nunit/nunit/pull/3988) +* [3936](https://github.com/nunit/nunit/issues/3936) Is there any way we could make use of + CallerArgumentExpressionAttribute?. Fixed by team [PR 4419](https://github.com/nunit/nunit/pull/4419) +* [3899](https://github.com/nunit/nunit/issues/3899) Allow randomizing 'Guid' test arguments with [Random]. Thanks to + [Arnaud TAMAILLON](https://github.com/Greybird) for [PR 3951](https://github.com/nunit/nunit/pull/3951) +* [3866](https://github.com/nunit/nunit/issues/3866) SupportedOSPlatform. Fixed by team [PR + 3926](https://github.com/nunit/nunit/pull/3926) +* [3856](https://github.com/nunit/nunit/issues/3856) Theories in nested Testfixtures. Thanks to [Felix + Kr”ner](https://github.com/Crown0815) for [PR 3857](https://github.com/nunit/nunit/pull/3857) +* [3718](https://github.com/nunit/nunit/issues/3718) Improve readability of "assert failed" message for + DictionaryContainsKeyValuePairConstraint WithValue(). Fixed by team [PR + 3778](https://github.com/nunit/nunit/pull/3778) +* [3457](https://github.com/nunit/nunit/issues/3457) Add DefaultConstraint. Thanks to [Oleksandr + Liakhevych](https://github.com/Dreamescaper) for [PR 3781](https://github.com/nunit/nunit/pull/3781) +* [3432](https://github.com/nunit/nunit/issues/3432) Assert.That is blocking and might lead to deadlock when used with + WCF.. Thanks to [Gavin Lambert](https://github.com/uecasm) for [PR 4322](https://github.com/nunit/nunit/pull/4322) +* [2843](https://github.com/nunit/nunit/issues/2843) Replacing ThrowsAsync with a composable async alternative. Thanks + to [Gavin Lambert](https://github.com/uecasm) for [PR 4322](https://github.com/nunit/nunit/pull/4322) +* [1459](https://github.com/nunit/nunit/issues/1459) Support for params keyword in parameterized test fixtures. Thanks + to [](https://github.com/Shiney) for [PR 4478](https://github.com/nunit/nunit/pull/4478) ### Bug fixes -* [4532](https://github.com/nunit/nunit/issues/4532) Assert.That no longer allows 'null' message. Fixed by team [PR 4533](https://github.com/nunit/nunit/pull/4533) -* [4529](https://github.com/nunit/nunit/issues/4529) Forwardport: Missing stack trace when exception occurs during OneTimeSetUp #2466. Fixed by team [PR 4469](https://github.com/nunit/nunit/pull/4469) -* [4528](https://github.com/nunit/nunit/issues/4528) Forwardport: Is.SupersetOf and Is.SubsetOf no longer work with IImmmutableDictionary<TKey,TValue> in NUnit 3.13.3 #4095. Fixed by team [PR 4098](https://github.com/nunit/nunit/pull/4098) -* [4522](https://github.com/nunit/nunit/issues/4522) Missing stack trace when exception occurs during OneTimeSetUp #2466. Fixed by team [PR 4469](https://github.com/nunit/nunit/pull/4469) -* [4491](https://github.com/nunit/nunit/issues/4491) NUnit 4.0 fails when [Repeat] is present and test passes. Fixed by team [PR 4517](https://github.com/nunit/nunit/pull/4517) -* [4484](https://github.com/nunit/nunit/issues/4484) String not-regex constraint succeeds non-`string` actual value. Thanks to [Michael Render](https://github.com/RenderMichael) for [PR 4492](https://github.com/nunit/nunit/pull/4492) -* [4450](https://github.com/nunit/nunit/issues/4450) Missing comparison failure details for EqualTo when comparing two collection. Thanks to [Ashish Dawale](https://github.com/ashishdawale20) for [PR 4502](https://github.com/nunit/nunit/pull/4502) -* [4423](https://github.com/nunit/nunit/issues/4423) Chaining multiple collection asserts with index. Thanks to [Daniel Waechtler](https://github.com/crabstars) for [PR 4480](https://github.com/nunit/nunit/pull/4480) -* [4400](https://github.com/nunit/nunit/issues/4400) Within throws ArgumentException if null value is involved. Thanks to [Ashish Dawale](https://github.com/ashishdawale20) for [PR 4482](https://github.com/nunit/nunit/pull/4482) -* [4319](https://github.com/nunit/nunit/issues/4319) TextRunner accidentally disposes System.Out. Thanks to [Norm Johanson](https://github.com/normj) for [PR 4317](https://github.com/nunit/nunit/pull/4317) -* [4308](https://github.com/nunit/nunit/issues/4308) Random attribute with Distinct and wide range causes test to disappear. Thanks to [Russell Smith](https://github.com/mr-russ) for [PR 4316](https://github.com/nunit/nunit/pull/4316) -* [4264](https://github.com/nunit/nunit/issues/4264) Assert.Multiple method should fail only if a contained assertion failed. Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR 4313](https://github.com/nunit/nunit/pull/4313) -* [4259](https://github.com/nunit/nunit/issues/4259) Bug: Assert.That(IEnumerable<Type>, Has.All.Property(nameof(Type.Namespace)) fails.. Fixed by team [PR 4260](https://github.com/nunit/nunit/pull/4260) -* [4255](https://github.com/nunit/nunit/issues/4255) InternalTrace.Initialize fails with Nullref exception. Fixed by team [PR 4256](https://github.com/nunit/nunit/pull/4256) -* [4246](https://github.com/nunit/nunit/issues/4246) Stack overflow when running tests on machine with Thai regional format. Fixed by team [PR 4345](https://github.com/nunit/nunit/pull/4345) -* [4243](https://github.com/nunit/nunit/issues/4243) Type args are not deduced correctly for parameterized fixtures. Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR 4307](https://github.com/nunit/nunit/pull/4307) -* [4237](https://github.com/nunit/nunit/issues/4237) Bogus check for Windows 11. Fixed by team [PR 4374](https://github.com/nunit/nunit/pull/4374) -* [4158](https://github.com/nunit/nunit/issues/4158) SetupFixture should have an `AttributeUsage` of `Inherited = false`. Thanks to [TillW](https://github.com/x789) for [PR 4222](https://github.com/nunit/nunit/pull/4222) -* [4107](https://github.com/nunit/nunit/issues/4107) Incorrect type specified for Values attribute fails unrelated tests. Fixed by team [PR 4133](https://github.com/nunit/nunit/pull/4133) -* [4096](https://github.com/nunit/nunit/issues/4096) NUnit.Framework 3.13.2 introduced a breaking change that conceals problems with tests. Fixed by team [PR 4133](https://github.com/nunit/nunit/pull/4133) -* [3964](https://github.com/nunit/nunit/issues/3964) DictionaryContainsKeyValuePairConstraint doesn't work with `IDictionary<TKey, TValue>`. Thanks to [Louis Zanella](https://github.com/louis-z) for [PR 4014](https://github.com/nunit/nunit/pull/4014) -* [3961](https://github.com/nunit/nunit/issues/3961) OneTimeTearDown runs on a new thread with mismatched Thread Name and Worker Id. Thanks to [](https://github.com/EraserKing) for [PR 4004](https://github.com/nunit/nunit/pull/4004) -* [3953](https://github.com/nunit/nunit/issues/3953) Dispose is not called on test fixtures with LifeCycle.InstancePerTestCase without TearDown method. Fixed by team [PR 3963](https://github.com/nunit/nunit/pull/3963) -* [3872](https://github.com/nunit/nunit/issues/3872) Add support for `ref bool`, `ref bool?`, `in bool`, and `in bool?` when using `NUnit.Framework.ValuesAttribute`. Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR 4304](https://github.com/nunit/nunit/pull/4304) -* [3868](https://github.com/nunit/nunit/issues/3868) Order attribute skips classes with multiple test fixtures. Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR 4304](https://github.com/nunit/nunit/pull/4304) -* [3867](https://github.com/nunit/nunit/issues/3867) nunit Framework tests do not run with "dotnet test" nor inside VS2019 (Windows). Fixed by team [PR 4315](https://github.com/nunit/nunit/pull/4315) -* [3858](https://github.com/nunit/nunit/issues/3858) Running tests with ITestAction attributes leaks memory. Thanks to [Marko Lahma](https://github.com/lahma) for [PR 4300](https://github.com/nunit/nunit/pull/4300) -* [3811](https://github.com/nunit/nunit/issues/3811) Incorrect summary comments on Warn.If overloads. Fixed by team [PR 3845](https://github.com/nunit/nunit/pull/3845) -* [3735](https://github.com/nunit/nunit/issues/3735) Parallelizable TestFixtureSource with TestFixtureData not running in parallel. Thanks to [Julien Richard](https://github.com/jairbubbles) for [PR 4099](https://github.com/nunit/nunit/pull/4099) -* [3449](https://github.com/nunit/nunit/issues/3449) Assert.AreEqual overloads for nullable double are not useful. Thanks to [Anton Ashmarin](https://github.com/Antash) for [PR 3780](https://github.com/nunit/nunit/pull/3780) -* [3274](https://github.com/nunit/nunit/issues/3274) Overriden tests are not discovered in NUnit 3.12.0. Fixed by team [PR 4490](https://github.com/nunit/nunit/pull/4490) -* [3215](https://github.com/nunit/nunit/issues/3215) Better error message for generic test where type parameter cannot be determined. Thanks to [Ove Bastiansen](https://github.com/ovebastiansen) for [PR 4382](https://github.com/nunit/nunit/pull/4382) -* [2870](https://github.com/nunit/nunit/issues/2870) CollectionTally (EquivalentTo) should throw for non-transitive comparisons. Thanks to [Russell Smith](https://github.com/mr-russ) for [PR 4312](https://github.com/nunit/nunit/pull/4312) -* [2841](https://github.com/nunit/nunit/issues/2841) DelayedConstraint calls delegate twice. Fixed by team [PR 4488](https://github.com/nunit/nunit/pull/4488) -* [2436](https://github.com/nunit/nunit/issues/2436) Properties on System.Type cannot be used with either property constraint. Fixed by team [PR 4259](https://github.com/nunit/nunit/pull/4259) -* [1428](https://github.com/nunit/nunit/issues/1428) NUnitLite package always installs both Program.cs and Program.vb. Fixed by team [PR 3952](https://github.com/nunit/nunit/pull/3952) +* [4532](https://github.com/nunit/nunit/issues/4532) Assert.That no longer allows 'null' message. Fixed by team [PR + 4533](https://github.com/nunit/nunit/pull/4533) +* [4529](https://github.com/nunit/nunit/issues/4529) Forwardport: Missing stack trace when exception occurs during + OneTimeSetUp #2466. Fixed by team [PR 4469](https://github.com/nunit/nunit/pull/4469) +* [4528](https://github.com/nunit/nunit/issues/4528) Forwardport: Is.SupersetOf and Is.SubsetOf no longer work with + IImmmutableDictionary<TKey,TValue> in NUnit 3.13.3 #4095. Fixed by team [PR + 4098](https://github.com/nunit/nunit/pull/4098) +* [4522](https://github.com/nunit/nunit/issues/4522) Missing stack trace when exception occurs during OneTimeSetUp + #2466. Fixed by team [PR 4469](https://github.com/nunit/nunit/pull/4469) +* [4491](https://github.com/nunit/nunit/issues/4491) NUnit 4.0 fails when [Repeat] is present and test passes. Fixed by + team [PR 4517](https://github.com/nunit/nunit/pull/4517) +* [4484](https://github.com/nunit/nunit/issues/4484) String not-regex constraint succeeds non-`string` actual value. + Thanks to [Michael Render](https://github.com/RenderMichael) for [PR 4492](https://github.com/nunit/nunit/pull/4492) +* [4450](https://github.com/nunit/nunit/issues/4450) Missing comparison failure details for EqualTo when comparing two + collection. Thanks to [Ashish Dawale](https://github.com/ashishdawale20) for [PR + 4502](https://github.com/nunit/nunit/pull/4502) +* [4423](https://github.com/nunit/nunit/issues/4423) Chaining multiple collection asserts with index. Thanks to [Daniel + Waechtler](https://github.com/crabstars) for [PR 4480](https://github.com/nunit/nunit/pull/4480) +* [4400](https://github.com/nunit/nunit/issues/4400) Within throws ArgumentException if null value is involved. Thanks + to [Ashish Dawale](https://github.com/ashishdawale20) for [PR 4482](https://github.com/nunit/nunit/pull/4482) +* [4319](https://github.com/nunit/nunit/issues/4319) TextRunner accidentally disposes System.Out. Thanks to [Norm + Johanson](https://github.com/normj) for [PR 4317](https://github.com/nunit/nunit/pull/4317) +* [4308](https://github.com/nunit/nunit/issues/4308) Random attribute with Distinct and wide range causes test to + disappear. Thanks to [Russell Smith](https://github.com/mr-russ) for [PR + 4316](https://github.com/nunit/nunit/pull/4316) +* [4264](https://github.com/nunit/nunit/issues/4264) Assert.Multiple method should fail only if a contained assertion + failed. Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR + 4313](https://github.com/nunit/nunit/pull/4313) +* [4259](https://github.com/nunit/nunit/issues/4259) Bug: Assert.That(IEnumerable<Type>, + Has.All.Property(nameof(Type.Namespace)) fails.. Fixed by team [PR 4260](https://github.com/nunit/nunit/pull/4260) +* [4255](https://github.com/nunit/nunit/issues/4255) InternalTrace.Initialize fails with Nullref exception. Fixed by + team [PR 4256](https://github.com/nunit/nunit/pull/4256) +* [4246](https://github.com/nunit/nunit/issues/4246) Stack overflow when running tests on machine with Thai regional + format. Fixed by team [PR 4345](https://github.com/nunit/nunit/pull/4345) +* [4243](https://github.com/nunit/nunit/issues/4243) Type args are not deduced correctly for parameterized fixtures. + Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR 4307](https://github.com/nunit/nunit/pull/4307) +* [4237](https://github.com/nunit/nunit/issues/4237) Bogus check for Windows 11. Fixed by team [PR + 4374](https://github.com/nunit/nunit/pull/4374) +* [4158](https://github.com/nunit/nunit/issues/4158) SetupFixture should have an `AttributeUsage` of `Inherited = + false`. Thanks to [TillW](https://github.com/x789) for [PR 4222](https://github.com/nunit/nunit/pull/4222) +* [4107](https://github.com/nunit/nunit/issues/4107) Incorrect type specified for Values attribute fails unrelated + tests. Fixed by team [PR 4133](https://github.com/nunit/nunit/pull/4133) +* [4096](https://github.com/nunit/nunit/issues/4096) NUnit.Framework 3.13.2 introduced a breaking change that conceals + problems with tests. Fixed by team [PR 4133](https://github.com/nunit/nunit/pull/4133) +* [3964](https://github.com/nunit/nunit/issues/3964) DictionaryContainsKeyValuePairConstraint doesn't work with + `IDictionary<TKey, TValue>`. Thanks to [Louis Zanella](https://github.com/louis-z) for [PR + 4014](https://github.com/nunit/nunit/pull/4014) +* [3961](https://github.com/nunit/nunit/issues/3961) OneTimeTearDown runs on a new thread with mismatched Thread Name + and Worker Id. Thanks to [](https://github.com/EraserKing) for [PR 4004](https://github.com/nunit/nunit/pull/4004) +* [3953](https://github.com/nunit/nunit/issues/3953) Dispose is not called on test fixtures with + LifeCycle.InstancePerTestCase without TearDown method. Fixed by team [PR + 3963](https://github.com/nunit/nunit/pull/3963) +* [3872](https://github.com/nunit/nunit/issues/3872) Add support for `ref bool`, `ref bool?`, `in bool`, and `in bool?` + when using `NUnit.Framework.ValuesAttribute`. Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR + 4304](https://github.com/nunit/nunit/pull/4304) +* [3868](https://github.com/nunit/nunit/issues/3868) Order attribute skips classes with multiple test fixtures. Thanks + to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR 4304](https://github.com/nunit/nunit/pull/4304) +* [3867](https://github.com/nunit/nunit/issues/3867) nunit Framework tests do not run with "dotnet test" nor inside + VS2019 (Windows). Fixed by team [PR 4315](https://github.com/nunit/nunit/pull/4315) +* [3858](https://github.com/nunit/nunit/issues/3858) Running tests with ITestAction attributes leaks memory. Thanks to + [Marko Lahma](https://github.com/lahma) for [PR 4300](https://github.com/nunit/nunit/pull/4300) +* [3811](https://github.com/nunit/nunit/issues/3811) Incorrect summary comments on Warn.If overloads. Fixed by team [PR + 3845](https://github.com/nunit/nunit/pull/3845) +* [3735](https://github.com/nunit/nunit/issues/3735) Parallelizable TestFixtureSource with TestFixtureData not running + in parallel. Thanks to [Julien Richard](https://github.com/jairbubbles) for [PR + 4099](https://github.com/nunit/nunit/pull/4099) +* [3449](https://github.com/nunit/nunit/issues/3449) Assert.AreEqual overloads for nullable double are not useful. + Thanks to [Anton Ashmarin](https://github.com/Antash) for [PR 3780](https://github.com/nunit/nunit/pull/3780) +* [3274](https://github.com/nunit/nunit/issues/3274) Overriden tests are not discovered in NUnit 3.12.0. Fixed by team + [PR 4490](https://github.com/nunit/nunit/pull/4490) +* [3215](https://github.com/nunit/nunit/issues/3215) Better error message for generic test where type parameter cannot + be determined. Thanks to [Ove Bastiansen](https://github.com/ovebastiansen) for [PR + 4382](https://github.com/nunit/nunit/pull/4382) +* [2870](https://github.com/nunit/nunit/issues/2870) CollectionTally (EquivalentTo) should throw for non-transitive + comparisons. Thanks to [Russell Smith](https://github.com/mr-russ) for [PR + 4312](https://github.com/nunit/nunit/pull/4312) +* [2841](https://github.com/nunit/nunit/issues/2841) DelayedConstraint calls delegate twice. Fixed by team [PR + 4488](https://github.com/nunit/nunit/pull/4488) +* [2436](https://github.com/nunit/nunit/issues/2436) Properties on System.Type cannot be used with either property + constraint. Fixed by team [PR 4259](https://github.com/nunit/nunit/pull/4259) +* [1428](https://github.com/nunit/nunit/issues/1428) NUnitLite package always installs both Program.cs and Program.vb. + Fixed by team [PR 3952](https://github.com/nunit/nunit/pull/3952) ### Refactorings -* [4434](https://github.com/nunit/nunit/issues/4434) Fixing the classic asserts. Fixed by team [PR 4438](https://github.com/nunit/nunit/pull/4438) -* [4416](https://github.com/nunit/nunit/issues/4416) Move classic asserts into its own project . Fixed by team [PR 4417](https://github.com/nunit/nunit/pull/4417) -* [4380](https://github.com/nunit/nunit/issues/4380) Consistently use _ prefix for field names. Fixed by team [PR 4387](https://github.com/nunit/nunit/pull/4387) -* [4378](https://github.com/nunit/nunit/issues/4378) Update code base to use 'is (not) null' consistently. Fixed by team [PR 4379](https://github.com/nunit/nunit/pull/4379) -* [4376](https://github.com/nunit/nunit/issues/4376) Update code base to explicitly specify accessibility. Fixed by team [PR 4377](https://github.com/nunit/nunit/pull/4377) -* [4364](https://github.com/nunit/nunit/issues/4364) Add NUnit.Analyzer to our test projects. Fixed by team [PR 4366](https://github.com/nunit/nunit/pull/4366) -* [4111](https://github.com/nunit/nunit/issues/4111) `Is.Empty` constraint on complex collections might hide bugs. Thanks to [Felix Kr”ner](https://github.com/Crown0815) for [PR 4120](https://github.com/nunit/nunit/pull/4120) -* [4051](https://github.com/nunit/nunit/issues/4051) Update codebase to use Array.Empty<T>. Thanks to [Marcin Jedrzejek](https://github.com/mjedrzejek) for [PR 4127](https://github.com/nunit/nunit/pull/4127) -* [3932](https://github.com/nunit/nunit/issues/3932) Make `Numerics` class internal. Thanks to [TillW](https://github.com/x789) for [PR 4205](https://github.com/nunit/nunit/pull/4205) +* [4434](https://github.com/nunit/nunit/issues/4434) Fixing the classic asserts. Fixed by team [PR + 4438](https://github.com/nunit/nunit/pull/4438) +* [4416](https://github.com/nunit/nunit/issues/4416) Move classic asserts into its own project . Fixed by team [PR + 4417](https://github.com/nunit/nunit/pull/4417) +* [4380](https://github.com/nunit/nunit/issues/4380) Consistently use _ prefix for field names. Fixed by team [PR + 4387](https://github.com/nunit/nunit/pull/4387) +* [4378](https://github.com/nunit/nunit/issues/4378) Update code base to use 'is (not) null' consistently. Fixed by team + [PR 4379](https://github.com/nunit/nunit/pull/4379) +* [4376](https://github.com/nunit/nunit/issues/4376) Update code base to explicitly specify accessibility. Fixed by team + [PR 4377](https://github.com/nunit/nunit/pull/4377) +* [4364](https://github.com/nunit/nunit/issues/4364) Add NUnit.Analyzer to our test projects. Fixed by team [PR + 4366](https://github.com/nunit/nunit/pull/4366) +* [4111](https://github.com/nunit/nunit/issues/4111) `Is.Empty` constraint on complex collections might hide bugs. + Thanks to [Felix Kr”ner](https://github.com/Crown0815) for [PR 4120](https://github.com/nunit/nunit/pull/4120) +* [4051](https://github.com/nunit/nunit/issues/4051) Update codebase to use Array.Empty<T>. Thanks to [Marcin + Jedrzejek](https://github.com/mjedrzejek) for [PR 4127](https://github.com/nunit/nunit/pull/4127) +* [3932](https://github.com/nunit/nunit/issues/3932) Make `Numerics` class internal. Thanks to + [TillW](https://github.com/x789) for [PR 4205](https://github.com/nunit/nunit/pull/4205) ### Internal fixes -* [4432](https://github.com/nunit/nunit/issues/4432) Fix null message in internal static string? ExtendedMessage(string methodName, string? message, string actualExpression, string constraintExpression). Fixed by team [PR 4430](https://github.com/nunit/nunit/pull/4430) -* [4331](https://github.com/nunit/nunit/issues/4331) Add testing to "Accumulate further failures if any on AssertMultiple instead of throwing". Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR 4313](https://github.com/nunit/nunit/pull/4313) -* [4212](https://github.com/nunit/nunit/issues/4212) Add Windows11 support to the Platform attribute. Fixed by team [PR 4213](https://github.com/nunit/nunit/pull/4213) -* [4170](https://github.com/nunit/nunit/issues/4170) Add .NET7 as a build target for the test suite . Fixed by team [PR 4224](https://github.com/nunit/nunit/pull/4224) -* [4078](https://github.com/nunit/nunit/issues/4078) THREAD_ABORT not properly set. Fixed by team [PR 4079](https://github.com/nunit/nunit/pull/4079) -* [4075](https://github.com/nunit/nunit/issues/4075) Remove unnecessary allocations in NUnitEqualityComparer. Fixed by team [PR 4076](https://github.com/nunit/nunit/pull/4076) -* [4072](https://github.com/nunit/nunit/issues/4072) Use pattern matching in Constraints to avoid unecessary casts. Fixed by team [PR 4073](https://github.com/nunit/nunit/pull/4073) -* [4065](https://github.com/nunit/nunit/issues/4065) Use pattern matching in the comparers. Fixed by team [PR 4066](https://github.com/nunit/nunit/pull/4066) -* [4055](https://github.com/nunit/nunit/issues/4055) Use static Regex.IsMatch in ValueMatchFilter to take advantage of caching. Fixed by team [PR 4056](https://github.com/nunit/nunit/pull/4056) -* [4049](https://github.com/nunit/nunit/issues/4049) Simplify property retrieval in DefaultTestAssemblyBuilder.Build(). Thanks to [Scott Buchanan](https://github.com/Phyrik) for [PR 4054](https://github.com/nunit/nunit/pull/4054) -* [3935](https://github.com/nunit/nunit/issues/3935) `Numerics.IsFixedPointNumeric` should return false for decimals. Thanks to [Wellington Balbo](https://github.com/wbalbo) for [PR 3942](https://github.com/nunit/nunit/pull/3942) -* [3789](https://github.com/nunit/nunit/issues/3789) Change copyright header on files. Fixed by team [PR 3795](https://github.com/nunit/nunit/pull/3795) -* [3764](https://github.com/nunit/nunit/issues/3764) Switch to the dotnet tool version of Cake. Fixed by team [PR 3835](https://github.com/nunit/nunit/pull/3835) -* [2485](https://github.com/nunit/nunit/issues/2485) Remove\Trim copyright on individual files. Fixed by team [PR 3795](https://github.com/nunit/nunit/pull/3795) +* [4432](https://github.com/nunit/nunit/issues/4432) Fix null message in internal static string? ExtendedMessage(string + methodName, string? message, string actualExpression, string constraintExpression). Fixed by team [PR + 4430](https://github.com/nunit/nunit/pull/4430) +* [4331](https://github.com/nunit/nunit/issues/4331) Add testing to "Accumulate further failures if any on + AssertMultiple instead of throwing". Thanks to [Samuel Delarosbil](https://github.com/sdelarosbil) for [PR + 4313](https://github.com/nunit/nunit/pull/4313) +* [4212](https://github.com/nunit/nunit/issues/4212) Add Windows11 support to the Platform attribute. Fixed by team [PR + 4213](https://github.com/nunit/nunit/pull/4213) +* [4170](https://github.com/nunit/nunit/issues/4170) Add .NET7 as a build target for the test suite . Fixed by team [PR + 4224](https://github.com/nunit/nunit/pull/4224) +* [4078](https://github.com/nunit/nunit/issues/4078) THREAD_ABORT not properly set. Fixed by team [PR + 4079](https://github.com/nunit/nunit/pull/4079) +* [4075](https://github.com/nunit/nunit/issues/4075) Remove unnecessary allocations in NUnitEqualityComparer. Fixed by + team [PR 4076](https://github.com/nunit/nunit/pull/4076) +* [4072](https://github.com/nunit/nunit/issues/4072) Use pattern matching in Constraints to avoid unecessary casts. + Fixed by team [PR 4073](https://github.com/nunit/nunit/pull/4073) +* [4065](https://github.com/nunit/nunit/issues/4065) Use pattern matching in the comparers. Fixed by team [PR + 4066](https://github.com/nunit/nunit/pull/4066) +* [4055](https://github.com/nunit/nunit/issues/4055) Use static Regex.IsMatch in ValueMatchFilter to take advantage of + caching. Fixed by team [PR 4056](https://github.com/nunit/nunit/pull/4056) +* [4049](https://github.com/nunit/nunit/issues/4049) Simplify property retrieval in DefaultTestAssemblyBuilder.Build(). + Thanks to [Scott Buchanan](https://github.com/Phyrik) for [PR 4054](https://github.com/nunit/nunit/pull/4054) +* [3935](https://github.com/nunit/nunit/issues/3935) `Numerics.IsFixedPointNumeric` should return false for decimals. + Thanks to [Wellington Balbo](https://github.com/wbalbo) for [PR 3942](https://github.com/nunit/nunit/pull/3942) +* [3789](https://github.com/nunit/nunit/issues/3789) Change copyright header on files. Fixed by team [PR + 3795](https://github.com/nunit/nunit/pull/3795) +* [3764](https://github.com/nunit/nunit/issues/3764) Switch to the dotnet tool version of Cake. Fixed by team [PR + 3835](https://github.com/nunit/nunit/pull/3835) +* [2485](https://github.com/nunit/nunit/issues/2485) Remove\Trim copyright on individual files. Fixed by team [PR + 3795](https://github.com/nunit/nunit/pull/3795) ### Deprecated features -* [4415](https://github.com/nunit/nunit/issues/4415) Remove use of params for messages. Fixed by team [PR 4419](https://github.com/nunit/nunit/pull/4419) -* [4036](https://github.com/nunit/nunit/issues/4036) Drop net45 build target in nunit4. Fixed by team [PR 4050](https://github.com/nunit/nunit/pull/4050) -* [3980](https://github.com/nunit/nunit/issues/3980) Drop netcoreapp2.1 targets. Fixed by team [PR 3988](https://github.com/nunit/nunit/pull/3988) -* [3769](https://github.com/nunit/nunit/issues/3769) Remove code marked "Obsolete". Fixed by team [PR 3836](https://github.com/nunit/nunit/pull/3836) -* [3758](https://github.com/nunit/nunit/issues/3758) Drop .NET 3.5 Build Targets. Fixed by team [PR 3760](https://github.com/nunit/nunit/pull/3760) -* [3708](https://github.com/nunit/nunit/issues/3708) Drop .NET 4.0 Build Target. Fixed by team [PR 3760](https://github.com/nunit/nunit/pull/3760) -* [3410](https://github.com/nunit/nunit/issues/3410) Consider deprecating NUnitEqualityComparer.AreEqual optional bool parameter. Thanks to [TillW](https://github.com/x789) for [PR 3960](https://github.com/nunit/nunit/pull/3960) -* [3132](https://github.com/nunit/nunit/issues/3132) Remove AssertionHelper and AssertionHelperTests. Fixed by team [PR 3836](https://github.com/nunit/nunit/pull/3836) +* [4415](https://github.com/nunit/nunit/issues/4415) Remove use of params for messages. Fixed by team [PR + 4419](https://github.com/nunit/nunit/pull/4419) +* [4036](https://github.com/nunit/nunit/issues/4036) Drop net45 build target in nunit4. Fixed by team [PR + 4050](https://github.com/nunit/nunit/pull/4050) +* [3980](https://github.com/nunit/nunit/issues/3980) Drop netcoreapp2.1 targets. Fixed by team [PR + 3988](https://github.com/nunit/nunit/pull/3988) +* [3769](https://github.com/nunit/nunit/issues/3769) Remove code marked "Obsolete". Fixed by team [PR + 3836](https://github.com/nunit/nunit/pull/3836) +* [3758](https://github.com/nunit/nunit/issues/3758) Drop .NET 3.5 Build Targets. Fixed by team [PR + 3760](https://github.com/nunit/nunit/pull/3760) +* [3708](https://github.com/nunit/nunit/issues/3708) Drop .NET 4.0 Build Target. Fixed by team [PR + 3760](https://github.com/nunit/nunit/pull/3760) +* [3410](https://github.com/nunit/nunit/issues/3410) Consider deprecating NUnitEqualityComparer.AreEqual optional bool + parameter. Thanks to [TillW](https://github.com/x789) for [PR 3960](https://github.com/nunit/nunit/pull/3960) +* [3132](https://github.com/nunit/nunit/issues/3132) Remove AssertionHelper and AssertionHelperTests. Fixed by team [PR + 3836](https://github.com/nunit/nunit/pull/3836) ### Others -* [4504](https://github.com/nunit/nunit/issues/4504) Remove appveyor build. Fixed by team [PR 4509](https://github.com/nunit/nunit/pull/4509) -* [4112](https://github.com/nunit/nunit/issues/4112) Update documentation to clarify passing parameters to test cases. Thanks to [Aaron Franke](https://github.com/aaronfranke) for [PR 4114](https://github.com/nunit/nunit/pull/4114) -* [3989](https://github.com/nunit/nunit/issues/3989) Revisit build documentation relating to IDEs. Fixed by team [PR 4050](https://github.com/nunit/nunit/pull/4050) -* [3869](https://github.com/nunit/nunit/issues/3869) Copyright notices for third-party code. Thanks to [Lennart Brggemann](https://github.com/lennartb-) for [PR 4444](https://github.com/nunit/nunit/pull/4444) -* [3812](https://github.com/nunit/nunit/issues/3812) Add GitHub Actions. Fixed by team [PR 3819](https://github.com/nunit/nunit/pull/3819) -* [3798](https://github.com/nunit/nunit/issues/3798) Support abstract methods marked as tests. Fixed by team [PR 4490](https://github.com/nunit/nunit/pull/4490) -* [3376](https://github.com/nunit/nunit/issues/3376) Nullable Reference Types annotations. Fixed by team through multiple PRs. . Fixed by team [PR 3488](https://github.com/nunit/nunit/pull/3488) -* [3301](https://github.com/nunit/nunit/issues/3301) [HandleProcessCorruptedStateExceptions] has no effect unless we disable partial trust. Fixed by team [PR 4398](https://github.com/nunit/nunit/pull/4398) +* [4504](https://github.com/nunit/nunit/issues/4504) Remove appveyor build. Fixed by team [PR + 4509](https://github.com/nunit/nunit/pull/4509) +* [4112](https://github.com/nunit/nunit/issues/4112) Update documentation to clarify passing parameters to test cases. + Thanks to [Aaron Franke](https://github.com/aaronfranke) for [PR 4114](https://github.com/nunit/nunit/pull/4114) +* [3989](https://github.com/nunit/nunit/issues/3989) Revisit build documentation relating to IDEs. Fixed by team [PR + 4050](https://github.com/nunit/nunit/pull/4050) +* [3869](https://github.com/nunit/nunit/issues/3869) Copyright notices for third-party code. Thanks to [Lennart + Brggemann](https://github.com/lennartb-) for [PR 4444](https://github.com/nunit/nunit/pull/4444) +* [3812](https://github.com/nunit/nunit/issues/3812) Add GitHub Actions. Fixed by team [PR + 3819](https://github.com/nunit/nunit/pull/3819) +* [3798](https://github.com/nunit/nunit/issues/3798) Support abstract methods marked as tests. Fixed by team [PR + 4490](https://github.com/nunit/nunit/pull/4490) +* [3376](https://github.com/nunit/nunit/issues/3376) Nullable Reference Types annotations. Fixed by team through + multiple PRs. . Fixed by team [PR 3488](https://github.com/nunit/nunit/pull/3488) +* [3301](https://github.com/nunit/nunit/issues/3301) [HandleProcessCorruptedStateExceptions] has no effect unless we + disable partial trust. Fixed by team [PR 4398](https://github.com/nunit/nunit/pull/4398) ### The following issues are marked as breaking changes -* [4416](https://github.com/nunit/nunit/issues/4416) Move classic asserts into its own project . Fixed by team [PR 4417](https://github.com/nunit/nunit/pull/4417) -* [4415](https://github.com/nunit/nunit/issues/4415) Remove use of params for messages. Fixed by team [PR 4419](https://github.com/nunit/nunit/pull/4419) +* [4416](https://github.com/nunit/nunit/issues/4416) Move classic asserts into its own project . Fixed by team [PR + 4417](https://github.com/nunit/nunit/pull/4417) +* [4415](https://github.com/nunit/nunit/issues/4415) Remove use of params for messages. Fixed by team [PR + 4419](https://github.com/nunit/nunit/pull/4419) ## NUnit 3.14.0 - November 4, 2023 @@ -152,22 +273,39 @@ Total number of issues fixed in this release is : 16 ### Enhancements -* [4046](https://github.com/nunit/nunit/issues/4046) Backport .NET6 test infra + build improvements from #3984 onto v3.13 branch. Fixed by team [PR 4077](https://github.com/nunit/nunit/pull/4077) ( backport of issue 3984) -* [4009](https://github.com/nunit/nunit/issues/4009) Performance degradation on many tests. Thanks to [Marko Lahma](https://github.com/lahma) for [PR 4034](https://github.com/nunit/nunit/pull/4034) -* [3859](https://github.com/nunit/nunit/issues/3859) Proper test result exception message when hitting `TimeoutAttribute`. Fixed by team [PR 4118](https://github.com/nunit/nunit/pull/4118) -* [3601](https://github.com/nunit/nunit/issues/3601) Nunit 3.10.1.0 + ReSharper 2020.1.4: Test execution delayed by ~60seconds . Thanks to [Marko Lahma](https://github.com/lahma) for [PR 4034](https://github.com/nunit/nunit/pull/4034) -* [2729](https://github.com/nunit/nunit/issues/2729) Proposal: Async test case sources. Fixed by team [PR 4390](https://github.com/nunit/nunit/pull/4390) +* [4046](https://github.com/nunit/nunit/issues/4046) Backport .NET6 test infra + build improvements from #3984 onto + v3.13 branch. Fixed by team [PR 4077](https://github.com/nunit/nunit/pull/4077) ( backport of issue 3984) +* [4009](https://github.com/nunit/nunit/issues/4009) Performance degradation on many tests. Thanks to [Marko + Lahma](https://github.com/lahma) for [PR 4034](https://github.com/nunit/nunit/pull/4034) +* [3859](https://github.com/nunit/nunit/issues/3859) Proper test result exception message when hitting + `TimeoutAttribute`. Fixed by team [PR 4118](https://github.com/nunit/nunit/pull/4118) +* [3601](https://github.com/nunit/nunit/issues/3601) Nunit 3.10.1.0 + ReSharper 2020.1.4: Test execution delayed by + ~60seconds . Thanks to [Marko Lahma](https://github.com/lahma) for [PR 4034](https://github.com/nunit/nunit/pull/4034) +* [2729](https://github.com/nunit/nunit/issues/2729) Proposal: Async test case sources. Fixed by team [PR + 4390](https://github.com/nunit/nunit/pull/4390) ### Bug fixes -* [4527](https://github.com/nunit/nunit/issues/4527) Backport: NUnit.Framework 3.13.2 introduced a breaking change that conceals problems with tests. Fixed by team [PR 4104](https://github.com/nunit/nunit/pull/4104) ( backport of issue 4096 by pr 4133) -* [4525](https://github.com/nunit/nunit/issues/4525) Backport: SetupFixture should have an AttributeUsage of Inherited = false . Thanks to [TillW](https://github.com/x789) for [PR 4223](https://github.com/nunit/nunit/pull/4223) ( backport of issue 4158 by pr 4222) -* [4523](https://github.com/nunit/nunit/issues/4523) Backport: Stack overflow when running tests on machine with Thai regional format. Fixed by team [PR 4346](https://github.com/nunit/nunit/pull/4346) ( backport of issue 4246 by pr 4345) -* [4324](https://github.com/nunit/nunit/issues/4324) Backport to v3: TextRunner accidentally disposes System.Out. Thanks to [Norm Johanson](https://github.com/normj) for [PR 4325](https://github.com/nunit/nunit/pull/4325) ( backport of issue 4319 by pr 4317) -* [4095](https://github.com/nunit/nunit/issues/4095) Is.SupersetOf and Is.SubsetOf no longer work with IImmmutableDictionary in NUnit 3.13.3. Fixed by team [PR 4097](https://github.com/nunit/nunit/pull/4097) -* [3859](https://github.com/nunit/nunit/issues/3859) Proper test result exception message when hitting `TimeoutAttribute`. Fixed by team [PR 4118](https://github.com/nunit/nunit/pull/4118) -* [3710](https://github.com/nunit/nunit/issues/3710) Calling NUnitLite from LINQpad, can't parse assembly path. Thanks to [Norm Johanson](https://github.com/normj) for [PR 4325](https://github.com/nunit/nunit/pull/4325) -* [2466](https://github.com/nunit/nunit/issues/2466) Missing stack trace when exception occurs during OneTimeSetUp. Fixed by team [PR 4467](https://github.com/nunit/nunit/pull/4467) +* [4527](https://github.com/nunit/nunit/issues/4527) Backport: NUnit.Framework 3.13.2 introduced a breaking change that + conceals problems with tests. Fixed by team [PR 4104](https://github.com/nunit/nunit/pull/4104) ( backport of issue + 4096 by pr 4133) +* [4525](https://github.com/nunit/nunit/issues/4525) Backport: SetupFixture should have an AttributeUsage of Inherited = + false . Thanks to [TillW](https://github.com/x789) for [PR 4223](https://github.com/nunit/nunit/pull/4223) ( backport + of issue 4158 by pr 4222) +* [4523](https://github.com/nunit/nunit/issues/4523) Backport: Stack overflow when running tests on machine with Thai + regional format. Fixed by team [PR 4346](https://github.com/nunit/nunit/pull/4346) ( backport of issue 4246 by pr + 4345) +* [4324](https://github.com/nunit/nunit/issues/4324) Backport to v3: TextRunner accidentally disposes System.Out. + Thanks to [Norm Johanson](https://github.com/normj) for [PR 4325](https://github.com/nunit/nunit/pull/4325) ( backport + of issue 4319 by pr 4317) +* [4095](https://github.com/nunit/nunit/issues/4095) Is.SupersetOf and Is.SubsetOf no longer work with + IImmmutableDictionary in NUnit 3.13.3. Fixed by team [PR 4097](https://github.com/nunit/nunit/pull/4097) +* [3859](https://github.com/nunit/nunit/issues/3859) Proper test result exception message when hitting + `TimeoutAttribute`. Fixed by team [PR 4118](https://github.com/nunit/nunit/pull/4118) +* [3710](https://github.com/nunit/nunit/issues/3710) Calling NUnitLite from LINQpad, can't parse assembly path. Thanks + to [Norm Johanson](https://github.com/normj) for [PR 4325](https://github.com/nunit/nunit/pull/4325) +* [2466](https://github.com/nunit/nunit/issues/2466) Missing stack trace when exception occurs during OneTimeSetUp. + Fixed by team [PR 4467](https://github.com/nunit/nunit/pull/4467) ### Refactorings @@ -175,9 +313,12 @@ None ### Internal fixes -* [4524](https://github.com/nunit/nunit/issues/4524) Backport: Add .NET7 as a build target for the test suite #4170. Fixed by team [PR 4302](https://github.com/nunit/nunit/pull/4302) ( backport of issue 4170 by pr 4224) -* [4293](https://github.com/nunit/nunit/issues/4293) .NET5 Test Suite is failing on Azure DevOps for Windows. Fixed by team [PR 4296](https://github.com/nunit/nunit/pull/4296) -* [2973](https://github.com/nunit/nunit/issues/2973) Write up recommended way to test and link it from the readme. Thanks to [Bruno Juchli](https://github.com/BrunoJuchli) for [PR 2971](https://github.com/nunit/nunit/pull/2971) +* [4524](https://github.com/nunit/nunit/issues/4524) Backport: Add .NET7 as a build target for the test suite #4170. + Fixed by team [PR 4302](https://github.com/nunit/nunit/pull/4302) ( backport of issue 4170 by pr 4224) +* [4293](https://github.com/nunit/nunit/issues/4293) .NET5 Test Suite is failing on Azure DevOps for Windows. Fixed by + team [PR 4296](https://github.com/nunit/nunit/pull/4296) +* [2973](https://github.com/nunit/nunit/issues/2973) Write up recommended way to test and link it from the readme. + Thanks to [Bruno Juchli](https://github.com/BrunoJuchli) for [PR 2971](https://github.com/nunit/nunit/pull/2971) ### Deprecated features @@ -189,46 +330,64 @@ None ## NUnit 3.13.3 - March 20, 2022 -This release includes several performance enhancements. [@lahma](https://github.com/lahma) provided a massive speed improvement for large, parametrized test suites. In addition, equivalency tests with large unsortable collections run faster by determining if the collections are sortable before attempting to sort them. +This release includes several performance enhancements. [@lahma](https://github.com/lahma) provided a massive speed +improvement for large, parametrized test suites. In addition, equivalency tests with large unsortable collections run +faster by determining if the collections are sortable before attempting to sort them. -We've added several fixes for .NET 6.0 and we've stopped testing NUnit against .NET Core 2.1 which is now out of support. +We've added several fixes for .NET 6.0 and we've stopped testing NUnit against .NET Core 2.1 which is now out of +support. -There are also several fixes for the new `FixtureLifeCycle` feature and other smaller bug fixes and performance improvements. +There are also several fixes for the new `FixtureLifeCycle` feature and other smaller bug fixes and performance +improvements. ### Issues Resolved * [2963](https://github.com/nunit/nunit/issues/2963) Flakey tests in FrameworkControllerTests * [3643](https://github.com/nunit/nunit/issues/3643) Assert.Pass(message) produces "reason" in XML-Result -* [3841](https://github.com/nunit/nunit/issues/3841) Breaking change: Is.SupersetOf with ValueTuple requires IComparable in NUnit 3.13.2 -* [3843](https://github.com/nunit/nunit/issues/3843) IDisposable & InstancePerTestCase: Object created for OneTimeSetUp is not disposed -* [3898](https://github.com/nunit/nunit/issues/3898) NUnit 3.13.2 : LessThanOrEqualTo fails on a case which should succeed +* [3841](https://github.com/nunit/nunit/issues/3841) Breaking change: Is.SupersetOf with ValueTuple requires IComparable + in NUnit 3.13.2 +* [3843](https://github.com/nunit/nunit/issues/3843) IDisposable & InstancePerTestCase: Object created for OneTimeSetUp + is not disposed +* [3898](https://github.com/nunit/nunit/issues/3898) NUnit 3.13.2 : LessThanOrEqualTo fails on a case which should + succeed * [3903](https://github.com/nunit/nunit/issues/3903) Backport race condition fix (PR 3883) * [3904](https://github.com/nunit/nunit/issues/3904) Backport fix for "IDisposable & InstancePerTestCase" (PR 3843) * [3929](https://github.com/nunit/nunit/issues/3929) Fix high precision decimal calculations in v3.13 (#3898) -* [3959](https://github.com/nunit/nunit/issues/3959) Marked 'NUnitEqualityComparer.AreEqual(object, object, Tolerance, bool)' as obsolete +* [3959](https://github.com/nunit/nunit/issues/3959) Marked 'NUnitEqualityComparer.AreEqual(object, object, Tolerance, + bool)' as obsolete * [3962](https://github.com/nunit/nunit/issues/3962) Ensure that AfterTest always runs in AfterTestCommand * [3971](https://github.com/nunit/nunit/issues/3971) Backport "Add missing `[DoesNotReturn]` annotations" from #3958 -* [3976](https://github.com/nunit/nunit/issues/3976) Equivalency fallback for non-IComparable types can leave CollectionTally in corrupt state +* [3976](https://github.com/nunit/nunit/issues/3976) Equivalency fallback for non-IComparable types can leave + CollectionTally in corrupt state * [3998](https://github.com/nunit/nunit/issues/3998) Eagerly determine when a set is unsortable * [3999](https://github.com/nunit/nunit/issues/3999) Numeric comparison fails when it should succeed. * [4000](https://github.com/nunit/nunit/issues/4000) OverflowException comparing large double values * [4007](https://github.com/nunit/nunit/issues/4007) Eagerly detect sortable types for equivalency tests in 3.13.x * [4030](https://github.com/nunit/nunit/issues/4030) IsEmpty doesn't work with new .NET6 PriorityQueue -* [4032](https://github.com/nunit/nunit/issues/4032) Tests won't run with an abstract base class that has a TestCaseFixtureSource +* [4032](https://github.com/nunit/nunit/issues/4032) Tests won't run with an abstract base class that has a + TestCaseFixtureSource * [4033](https://github.com/nunit/nunit/issues/4033) Recognized private members in base class for Source attributes * [4034](https://github.com/nunit/nunit/issues/4034) Improve method discovery and filtering performance -* [4041](https://github.com/nunit/nunit/issues/4041) Minimize empty array allocations via centralized helper for pre-net46 +* [4041](https://github.com/nunit/nunit/issues/4041) Minimize empty array allocations via centralized helper for + pre-net46 * [4043](https://github.com/nunit/nunit/issues/4043) Stop testing the framework against netcoreapp21 in v3.13 branch * [4045](https://github.com/nunit/nunit/issues/4045) Drop netcore2.1 as a target (backport #3986) * [4058](https://github.com/nunit/nunit/issues/4058) Remove TopLevel property from ValueMatchFilter ## NUnit 3.13.2 - April 27, 2021 -This release fixes a new issue with the `FixtureLifeCycle` attribute where `IDisposable` test fixtures were not being disposed properly. As always, [@gleb-osokin](https://github.com/gleb-osokin) has been a great help with this new feature. +This release fixes a new issue with the `FixtureLifeCycle` attribute where `IDisposable` test fixtures were not being +disposed properly. As always, [@gleb-osokin](https://github.com/gleb-osokin) has been a great help with this new +feature. -It also fixes a long-standing performance issue with `CollectionAssert.AreEquivalent` and the `CollectionEquivalentConstraint` when comparing large collections. The deep comparison that NUnit performs on the two collections will always have a worst case bound of O(n^2) but we have optimized it so that the majority of use cases will be closer to O(n). +It also fixes a long-standing performance issue with `CollectionAssert.AreEquivalent` and the +`CollectionEquivalentConstraint` when comparing large collections. The deep comparison that NUnit performs on the two +collections will always have a worst case bound of O(n^2) but we have optimized it so that the majority of use cases +will be closer to O(n). -We've also made significant optimizations to the OR filters for selecting tests using their full name. This dramatically improves test performance for large code bases that use `dotnet test`. Thanks to [@pakrym](https://github.com/pakrym) for his help with this. +We've also made significant optimizations to the OR filters for selecting tests using their full name. This dramatically +improves test performance for large code bases that use `dotnet test`. Thanks to [@pakrym](https://github.com/pakrym) +for his help with this. ### Issues Resolved @@ -244,85 +403,118 @@ We've also made significant optimizations to the OR filters for selecting tests ## NUnit 3.13.1 - January 31, 2021 -This release addresses several misses with the new `FixtureLifeCycle` attribute, switches to using [SourceLink](https://github.com/dotnet/sourcelink) and NuGet [snupkg](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) packages for debugging into NUnit from your unit tests. It also addresses issues with the time format of ignored and explicit tests in the test results file. +This release addresses several misses with the new `FixtureLifeCycle` attribute, switches to using +[SourceLink](https://github.com/dotnet/sourcelink) and NuGet +[snupkg](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) packages for debugging into +NUnit from your unit tests. It also addresses issues with the time format of ignored and explicit tests in the test +results file. ### Issues Resolved * [2339](https://github.com/nunit/nunit/issues/2339) Wrong date format in Ignored TestFixtures -* [3715](https://github.com/nunit/nunit/issues/3715) `FixtureLifeCycle(LifeCycle.InstancePerTestCase)` Not working with `TestFixtureSource` -* [3716](https://github.com/nunit/nunit/issues/3716) Assembly level `FixtureLifeCycle(LifeCycle.InstancePerTestCase)` doesn't work +* [3715](https://github.com/nunit/nunit/issues/3715) `FixtureLifeCycle(LifeCycle.InstancePerTestCase)` Not working with + `TestFixtureSource` +* [3716](https://github.com/nunit/nunit/issues/3716) Assembly level `FixtureLifeCycle(LifeCycle.InstancePerTestCase)` + doesn't work * [3724](https://github.com/nunit/nunit/issues/3724) Test start and end time should end with Z -* [3726](https://github.com/nunit/nunit/issues/3726) Assert `EqualTo().Within().Seconds` does not work with DateTimes in NUnit 3.13 +* [3726](https://github.com/nunit/nunit/issues/3726) Assert `EqualTo().Within().Seconds` does not work with DateTimes in + NUnit 3.13 * [3729](https://github.com/nunit/nunit/issues/3729) AppVeyor builds failing * [3736](https://github.com/nunit/nunit/issues/3736) `AreEqual.Within` throws on failure with non-numeric types -* [3743](https://github.com/nunit/nunit/issues/3743) Parametrized tests do not respect `FixtureLifeCycle.InstancePerTestCase` -* [3745](https://github.com/nunit/nunit/issues/3745) After upgrading to NUnit 3.13.0 the debugger enters NUnit code despite having checked "Enable Just My Code" +* [3743](https://github.com/nunit/nunit/issues/3743) Parametrized tests do not respect + `FixtureLifeCycle.InstancePerTestCase` +* [3745](https://github.com/nunit/nunit/issues/3745) After upgrading to NUnit 3.13.0 the debugger enters NUnit code + despite having checked "Enable Just My Code" ## NUnit 3.13 - January 7, 2021 -The [`FixtureLifeCycle`](xref:fixturelifecycleattribute) attribute has been added to indicate that an instance for a test fixture or all test fixtures in an assembly should be constructed for each test within the fixture or assembly. +The [`FixtureLifeCycle`](xref:fixturelifecycleattribute) attribute has been added to indicate that an instance for a +test fixture or all test fixtures in an assembly should be constructed for each test within the fixture or assembly. -This attribute may be applied to a test fixture (class) or to a test assembly. It is useful in combination with the [Parallelizable Attribute](xref:parallelizableattribute) so that a new instance of a test fixture is constructed for every test within the test fixture. This allows tests to run in isolation without sharing instance fields and properties during parallel test runs. This make running parallel tests easier because it is easier to make your tests thread safe. +This attribute may be applied to a test fixture (class) or to a test assembly. It is useful in combination with the +[Parallelizable Attribute](xref:parallelizableattribute) so that a new instance of a test fixture is constructed for +every test within the test fixture. This allows tests to run in isolation without sharing instance fields and properties +during parallel test runs. This make running parallel tests easier because it is easier to make your tests thread safe. -This release also fixes several issues running tests in .NET 5.0. If your tests target .NET 5.0, we recommend updating to this release. +This release also fixes several issues running tests in .NET 5.0. If your tests target .NET 5.0, we recommend updating +to this release. ### Issues Resolved * [34](https://github.com/nunit/nunit/issues/34) Async testing with F# * [52](https://github.com/nunit/nunit/issues/52) Self-contained item in array causes stack overflow -* [1394](https://github.com/nunit/nunit/issues/1394) `Has.Property` cannot see explicit interface implementation properties +* [1394](https://github.com/nunit/nunit/issues/1394) `Has.Property` cannot see explicit interface implementation + properties * [1491](https://github.com/nunit/nunit/issues/1491) Add a CLA to the project -* [1546](https://github.com/nunit/nunit/issues/1546) `NUnitEqualityComparer.GetEquatableGenericArguments` should explicitly order arguments +* [1546](https://github.com/nunit/nunit/issues/1546) `NUnitEqualityComparer.GetEquatableGenericArguments` should + explicitly order arguments * [1809](https://github.com/nunit/nunit/issues/1809) `Assert.AreEqual` fails for Complex on Linux -* [1897](https://github.com/nunit/nunit/issues/1897) `EqualTo().Using()` prevents caller from comparing strings to anything else +* [1897](https://github.com/nunit/nunit/issues/1897) `EqualTo().Using()` prevents caller from comparing strings to + anything else * [2211](https://github.com/nunit/nunit/issues/2211) Add support of indexers to the PropertyConstraint * [2222](https://github.com/nunit/nunit/issues/2222) Switch to one Release branch -* [2477](https://github.com/nunit/nunit/issues/2477) Parameterized fixture with `Explicit` attribute can not be run when selected by name +* [2477](https://github.com/nunit/nunit/issues/2477) Parameterized fixture with `Explicit` attribute can not be run when + selected by name * [2574](https://github.com/nunit/nunit/issues/2574) Instance-per-test-case feature * [2680](https://github.com/nunit/nunit/issues/2680) Deprecate the `DebugWriter` class -* [3611](https://github.com/nunit/nunit/issues/3611) Properties are shown when `--explore:nunit3` is run on entire project, but omitted when using the `--where` clause +* [3611](https://github.com/nunit/nunit/issues/3611) Properties are shown when `--explore:nunit3` is run on entire + project, but omitted when using the `--where` clause * [3054](https://github.com/nunit/nunit/issues/3054) Don't enforce `[Timeout]` when debugger is attached * [3075](https://github.com/nunit/nunit/issues/3075) Complete `RunAsyncAction` tests in `FrameworkControllerTests` * [3228](https://github.com/nunit/nunit/issues/3228) Modulo bias is present in `Randomizer.NextDecimal(decimal)` * [3240](https://github.com/nunit/nunit/issues/3240) Automate uploading of test results to Azure Pipelines * [3243](https://github.com/nunit/nunit/issues/3243) Azure DevOps does not build release branch * [3249](https://github.com/nunit/nunit/issues/3249) Pin GitLink version to speed up Cake script -* [3251](https://github.com/nunit/nunit/issues/3251) `RawInt32()` can't use Next since the maximum is always exclusive and it would never return int.MaxValue -* [3252](https://github.com/nunit/nunit/issues/3252) Timeout of 100 ms in `TestTimeoutDoesNotStopCompletion` occasionally fails the macOS build -* [3253](https://github.com/nunit/nunit/issues/3253) Chance of failure in random bias tests is not sufficiently low for CI +* [3251](https://github.com/nunit/nunit/issues/3251) `RawInt32()` can't use Next since the maximum is always exclusive + and it would never return int.MaxValue +* [3252](https://github.com/nunit/nunit/issues/3252) Timeout of 100 ms in `TestTimeoutDoesNotStopCompletion` + occasionally fails the macOS build +* [3253](https://github.com/nunit/nunit/issues/3253) Chance of failure in random bias tests is not sufficiently low for + CI * [3256](https://github.com/nunit/nunit/issues/3256) Building under VS2019 * [3257](https://github.com/nunit/nunit/issues/3257) Running under mono * [3259](https://github.com/nunit/nunit/issues/3259) The type of an Array isn't inferred from properly -* [3264](https://github.com/nunit/nunit/issues/3264) Test that `IRepeatTest` only gets attributes via the `IMethodInfo` interface +* [3264](https://github.com/nunit/nunit/issues/3264) Test that `IRepeatTest` only gets attributes via the `IMethodInfo` + interface * [3275](https://github.com/nunit/nunit/issues/3275) Enable setting `IgnoreUntilDate` in `TestCaseData.Ignore` * [3279](https://github.com/nunit/nunit/issues/3279) Improve failure message from `UniqueItemsConstraint` * [3282](https://github.com/nunit/nunit/issues/3282) `TimeoutAttribute` makes all Assertions count as failure * [3283](https://github.com/nunit/nunit/issues/3283) `ExecutionContext` is flowed between unrelated tests -* [3286](https://github.com/nunit/nunit/issues/3286) Testing for equality using a predicate throws exception for collections +* [3286](https://github.com/nunit/nunit/issues/3286) Testing for equality using a predicate throws exception for + collections * [3290](https://github.com/nunit/nunit/issues/3290) 'Good first issue' or 'help wanted' issue count badge -* [3296](https://github.com/nunit/nunit/issues/3296) `ExceptionHelper.GetExceptionMessage(Exception ex)` should tolerate exceptions from exceptions -* [3302](https://github.com/nunit/nunit/issues/3302) Incorrect formatting of failure message if test fails with `Assert.Multiple` +* [3296](https://github.com/nunit/nunit/issues/3296) `ExceptionHelper.GetExceptionMessage(Exception ex)` should tolerate + exceptions from exceptions +* [3302](https://github.com/nunit/nunit/issues/3302) Incorrect formatting of failure message if test fails with + `Assert.Multiple` * [3303](https://github.com/nunit/nunit/issues/3303) Check type of actual argument using consistent helper method * [3304](https://github.com/nunit/nunit/issues/3304) `CheckString` should not be a generic method * [3305](https://github.com/nunit/nunit/issues/3305) Remove unused methods * [3307](https://github.com/nunit/nunit/issues/3307) Sporadic `GetResultIsNotCalledUntilContinued` failure * [3308](https://github.com/nunit/nunit/issues/3308) Fix disposal in `EnumerablesComparer` * [3309](https://github.com/nunit/nunit/issues/3309) Simplify code in `EventListenerTextWriter` -* [3311](https://github.com/nunit/nunit/issues/3311) Minimal unit of `DateTime` in the report when Test was started/ended -* [3312](https://github.com/nunit/nunit/issues/3312) Simplify `ProviderCache` and make it instantiable since it is intentionally not thread safe +* [3311](https://github.com/nunit/nunit/issues/3311) Minimal unit of `DateTime` in the report when Test was + started/ended +* [3312](https://github.com/nunit/nunit/issues/3312) Simplify `ProviderCache` and make it instantiable since it is + intentionally not thread safe * [3315](https://github.com/nunit/nunit/issues/3315) `Assert.DoesNotThrow()` stopped working as it was previously * [3318](https://github.com/nunit/nunit/issues/3318) Fix `AwaitAdapter` terminology * [3321](https://github.com/nunit/nunit/issues/3321) Keep dependencies up to date * [3322](https://github.com/nunit/nunit/issues/3322) Speed up build script by removing unnecessary builds * [3324](https://github.com/nunit/nunit/issues/3324) Broken link in `CHANGES.md` -* [3328](https://github.com/nunit/nunit/issues/3328) Problems when using a mixture of Not and Or filters in NUnit framework 3.12.0 +* [3328](https://github.com/nunit/nunit/issues/3328) Problems when using a mixture of Not and Or filters in NUnit + framework 3.12.0 * [3331](https://github.com/nunit/nunit/issues/3331) `Contains.Key` no longer working for `IDictionary` -* [3338](https://github.com/nunit/nunit/issues/3338) Azure Pipelines is failing on Linux for both netstandard 1.4 and 2.0 +* [3338](https://github.com/nunit/nunit/issues/3338) Azure Pipelines is failing on Linux for both netstandard 1.4 and + 2.0 * [3356](https://github.com/nunit/nunit/issues/3356) `SetUpFixture` not run -* [3368](https://github.com/nunit/nunit/issues/3368) Tests with warnings are not added to console `TestResult.xml` total count -* [3383](https://github.com/nunit/nunit/issues/3383) Drop netstandard1.4 and stop testing on end-of-life versions of .NET Core +* [3368](https://github.com/nunit/nunit/issues/3368) Tests with warnings are not added to console `TestResult.xml` total + count +* [3383](https://github.com/nunit/nunit/issues/3383) Drop netstandard1.4 and stop testing on end-of-life versions of + .NET Core * [3389](https://github.com/nunit/nunit/issues/3389) Show names of parameters -* [3390](https://github.com/nunit/nunit/issues/3390) `SetUpFixture` not being triggered when running tests using `--testlist` +* [3390](https://github.com/nunit/nunit/issues/3390) `SetUpFixture` not being triggered when running tests using + `--testlist` * [3392](https://github.com/nunit/nunit/issues/3392) Use of `Thread.CurrentPrincipal` in Blazor/WASM * [3393](https://github.com/nunit/nunit/issues/3393) Nuget Package Not Signed * [3395](https://github.com/nunit/nunit/issues/3395) `Randomizer.NextString()` can probably be sped up @@ -331,14 +523,17 @@ This release also fixes several issues running tests in .NET 5.0. If your tests * [3414](https://github.com/nunit/nunit/issues/3414) Azure pipelines are failing on Linux * [3415](https://github.com/nunit/nunit/issues/3415) Azure CI: Still publish test results on failure * [3423](https://github.com/nunit/nunit/issues/3423) `TestResult.cs` casts `ITestResult` to `TestResult` -* [3447](https://github.com/nunit/nunit/issues/3447) `Is.EqualTo(...).Using(StructuralComparisons.StructuralEqualityComparer or StructuralComparer)` not working +* [3447](https://github.com/nunit/nunit/issues/3447) + `Is.EqualTo(...).Using(StructuralComparisons.StructuralEqualityComparer or StructuralComparer)` not working * [3452](https://github.com/nunit/nunit/issues/3452) Assertions that use an existing Regex * [3453](https://github.com/nunit/nunit/issues/3453) Visibility of SetUp/TearDown Methods * [3454](https://github.com/nunit/nunit/issues/3454) Pre-Filtering in NUnitLite has problems * [3464](https://github.com/nunit/nunit/issues/3464) Improve debugging experience * [3470](https://github.com/nunit/nunit/issues/3470) Assertion for key-value-pair -* [3475](https://github.com/nunit/nunit/issues/3475) Our XML comments are using `` (block element) instead of `` (inline element) -* [3485](https://github.com/nunit/nunit/issues/3485) Should we make `MultipleAssertException.TestResult` maybe-null or obsolete two constructors? +* [3475](https://github.com/nunit/nunit/issues/3475) Our XML comments are using `` (block element) instead of + `` (inline element) +* [3485](https://github.com/nunit/nunit/issues/3485) Should we make `MultipleAssertException.TestResult` maybe-null or + obsolete two constructors? * [3496](https://github.com/nunit/nunit/issues/3496) Adding data dictionary should not add a trailing newline * [3497](https://github.com/nunit/nunit/issues/3497) Fix mixed line endings in Git * [3503](https://github.com/nunit/nunit/issues/3503) Remove implicit cast from `ITestResult` to `TestResult` @@ -346,10 +541,13 @@ This release also fixes several issues running tests in .NET 5.0. If your tests * [3506](https://github.com/nunit/nunit/issues/3506) `ValueTuple` tests now running if not targeting NET35 * [3536](https://github.com/nunit/nunit/issues/3536) Reduce newly added API surface * [3542](https://github.com/nunit/nunit/issues/3542) Update NuGet Package Icons -* [3547](https://github.com/nunit/nunit/issues/3547) `DelayedConstraint` constrains does not preserve original result additional information +* [3547](https://github.com/nunit/nunit/issues/3547) `DelayedConstraint` constrains does not preserve original result + additional information * [3551](https://github.com/nunit/nunit/issues/3551) Add `PrivateAssets="all"` to analyzer dependency -* [3552](https://github.com/nunit/nunit/issues/3552) `MessagePumpStrategy` does not work for WPF on netcoreapp3.0 and upwards -* [3559](https://github.com/nunit/nunit/issues/3559) Disables the DOC100 suggestion and reverts the added paragraph elements +* [3552](https://github.com/nunit/nunit/issues/3552) `MessagePumpStrategy` does not work for WPF on netcoreapp3.0 and + upwards +* [3559](https://github.com/nunit/nunit/issues/3559) Disables the DOC100 suggestion and reverts the added paragraph + elements * [3563](https://github.com/nunit/nunit/issues/3563) Improve `TextMessageWriter` output for numeric values * [3565](https://github.com/nunit/nunit/issues/3565) .NET 5 issue with `PlatformAttribute` * [3583](https://github.com/nunit/nunit/issues/3583) Avoid using a culture-sensitive `EndsWith` in common code @@ -359,61 +557,69 @@ This release also fixes several issues running tests in .NET 5.0. If your tests * [3598](https://github.com/nunit/nunit/issues/3598) Fix typo * [3608](https://github.com/nunit/nunit/issues/3608) `[Platform]` attribute fails with `DllNotFoundException` in WASM * [3616](https://github.com/nunit/nunit/issues/3616) Extend `Is.Empty` to work for `Guid.Empty` -* [3618](https://github.com/nunit/nunit/issues/3618) NUnit has a P/Invoke whose native function doesn't exist on all platforms -* [3622](https://github.com/nunit/nunit/issues/3622) `EmptyDirectoryConstraint` doesn't need to enumerate entire directory contents +* [3618](https://github.com/nunit/nunit/issues/3618) NUnit has a P/Invoke whose native function doesn't exist on all + platforms +* [3622](https://github.com/nunit/nunit/issues/3622) `EmptyDirectoryConstraint` doesn't need to enumerate entire + directory contents * [3632](https://github.com/nunit/nunit/issues/3632) `Assert.Inconclusive()` reports failed when timeout used * [3636](https://github.com/nunit/nunit/issues/3636) NUnitLite filtering fails if space in test name before ( -* [3641](https://github.com/nunit/nunit/issues/3641) Type implementing `IComparable` (or any `IComparable`) fails comparison. +* [3641](https://github.com/nunit/nunit/issues/3641) Type implementing `IComparable` (or any `IComparable`) fails + comparison. * [3647](https://github.com/nunit/nunit/issues/3647) Fix exception under Blazor 5 * [3650](https://github.com/nunit/nunit/issues/3650) Build issue with the latest .NET SDK 5.0.100-rc.2 * [3657](https://github.com/nunit/nunit/issues/3657) Add Framework Version to the XML -* [3662](https://github.com/nunit/nunit/issues/3662) `TestContext.CurrentContext.CurrentRepeatCount` only contains retry count not the repeat count -* [3667](https://github.com/nunit/nunit/issues/3667) Create FrameworkPackageSetting to set `CurrentCulture` and `CurrentUICulture` +* [3662](https://github.com/nunit/nunit/issues/3662) `TestContext.CurrentContext.CurrentRepeatCount` only contains retry + count not the repeat count +* [3667](https://github.com/nunit/nunit/issues/3667) Create FrameworkPackageSetting to set `CurrentCulture` and + `CurrentUICulture` * [3676](https://github.com/nunit/nunit/issues/3676) `Parallelizeable` tests sometimes shares memory * [3679](https://github.com/nunit/nunit/issues/3679) Issue 3390: Do not prefilter relevant `SetUpFixtures` * [3694](https://github.com/nunit/nunit/issues/3694) Async tests causes double failure messages -* [3699](https://github.com/nunit/nunit/issues/3699) Compilation of netcoreapp3.1 targets fails on CI (both AppVeyor and Azure Pipelines) +* [3699](https://github.com/nunit/nunit/issues/3699) Compilation of netcoreapp3.1 targets fails on CI (both AppVeyor and + Azure Pipelines) ## NUnit 3.12 - May 14, 2019 -This release of NUnit finally drops support for .NET 2.0. If your application still -targets .NET 2.0, your tests will need to target at least .NET 3.5. Microsoft ended -support for .NET 2.0 on July 12, 2011. Microsoft recommends that everyone migrate -to at least .NET Framework 3.5 SP1 for security and performance fixes. +This release of NUnit finally drops support for .NET 2.0. If your application still targets .NET 2.0, your tests will +need to target at least .NET 3.5. Microsoft ended support for .NET 2.0 on July 12, 2011. Microsoft recommends that +everyone migrate to at least .NET Framework 3.5 SP1 for security and performance fixes. -This release dramatically improves NUnit support for async tests including returning -ValueTask and custom tasks from tests, improved handling of SynchronizationContexts -and better exception handling. +This release dramatically improves NUnit support for async tests including returning ValueTask and custom tasks from +tests, improved handling of SynchronizationContexts and better exception handling. -The .NET Standard 2.0 version of NUnit continues to gain more functionality that -is found in the .NET 4.5 version of the framework like setting the ApartmentState -and enabling Timeout on tests. +The .NET Standard 2.0 version of NUnit continues to gain more functionality that is found in the .NET 4.5 version of the +framework like setting the ApartmentState and enabling Timeout on tests. ### Issues Resolved * [474](https://github.com/nunit/nunit/issues/474) TypeHelperTests.cs is orphaned * [999](https://github.com/nunit/nunit/issues/999) Support multiple TestOf attributes per test * [1638](https://github.com/nunit/nunit/issues/1638) TimeoutAttribute not available when targeting netcoreapp framework -* [2168](https://github.com/nunit/nunit/issues/2168) ThrowsAsync reports OperationCanceledException as TaskCanceledException +* [2168](https://github.com/nunit/nunit/issues/2168) ThrowsAsync reports OperationCanceledException as + TaskCanceledException * [2194](https://github.com/nunit/nunit/issues/2194) How to use `Contains.Substring` with `And` * [2286](https://github.com/nunit/nunit/issues/2286) Add support for custom Task (i.e. ValueTask) * [2579](https://github.com/nunit/nunit/issues/2579) AppVeyor Test Failures under .NET 3.5 -* [2614](https://github.com/nunit/nunit/issues/2614) TestExecutionContext.CurrentContext is saved in Remoting CallContext between test runs +* [2614](https://github.com/nunit/nunit/issues/2614) TestExecutionContext.CurrentContext is saved in Remoting + CallContext between test runs * [2696](https://github.com/nunit/nunit/issues/2696) Getting WorkerId fails in debug -* [2772](https://github.com/nunit/nunit/issues/2772) Random failing of parallel test run: Unhandled Exception: System.InvalidOperationException: Stack empty. +* [2772](https://github.com/nunit/nunit/issues/2772) Random failing of parallel test run: Unhandled Exception: + System.InvalidOperationException: Stack empty. * [2975](https://github.com/nunit/nunit/issues/2975) ComparisonConstraints are allocating string on construction * [3014](https://github.com/nunit/nunit/issues/3014) Timeout failures on MacOS * [3023](https://github.com/nunit/nunit/issues/3023) NUnit runner fails when test method returns ValueTask<> * [3035](https://github.com/nunit/nunit/issues/3035) Apartment state can't be used for .NET Standard 2.0 tests * [3036](https://github.com/nunit/nunit/issues/3036) Apartment state can't be used for .NET Standard 2.0 tests * [3038](https://github.com/nunit/nunit/issues/3038) TestName in TestCase attribute not validated to be not empty -* [3042](https://github.com/nunit/nunit/issues/3042) RequiresThreadAttribute allows ApartmentState.Unknown, unlike ApartmentAttribute +* [3042](https://github.com/nunit/nunit/issues/3042) RequiresThreadAttribute allows ApartmentState.Unknown, unlike + ApartmentAttribute * [3048](https://github.com/nunit/nunit/issues/3048) Add .idea folder to .gitignore * [3053](https://github.com/nunit/nunit/issues/3053) Conversion from TestCase string parameter to DateTimeOffset * [3059](https://github.com/nunit/nunit/issues/3059) Constraint Throws.Exception does not work with async return value * [3068](https://github.com/nunit/nunit/issues/3068) First Chance Exception in RuntimeFramework * [3070](https://github.com/nunit/nunit/issues/3070) End support for .NET Framework 2.0 (released in 2005) -* [3073](https://github.com/nunit/nunit/issues/3073) CollectionAssert.AreEquivalent fails for ValueTuple Wrapped Dictionary +* [3073](https://github.com/nunit/nunit/issues/3073) CollectionAssert.AreEquivalent fails for ValueTuple Wrapped + Dictionary * [3079](https://github.com/nunit/nunit/issues/3079) Regression from 3.10 to 3.11: Range in bytes * [3082](https://github.com/nunit/nunit/issues/3082) Is.Ordered.By * [3085](https://github.com/nunit/nunit/issues/3085) XML Test-Suite Assembly does not contain DLL path anymore @@ -421,8 +627,10 @@ and enabling Timeout on tests. * [3093](https://github.com/nunit/nunit/issues/3093) Tests having TaskLike objects as their return type throws Exception * [3094](https://github.com/nunit/nunit/issues/3094) Bad error message if collections have different types * [3104](https://github.com/nunit/nunit/issues/3104) Removed NET20 compile output -* [3105](https://github.com/nunit/nunit/issues/3105) Add tests for use of ApartmentState.Unknown in RequiresThreadAttribute -* [3107](https://github.com/nunit/nunit/issues/3107) Declare class in Program.cs provided with NUnitLite Nuget package static +* [3105](https://github.com/nunit/nunit/issues/3105) Add tests for use of ApartmentState.Unknown in + RequiresThreadAttribute +* [3107](https://github.com/nunit/nunit/issues/3107) Declare class in Program.cs provided with NUnitLite Nuget package + static * [3109](https://github.com/nunit/nunit/issues/3109) Azure DevOps build fails in Save package artifacts * [3124](https://github.com/nunit/nunit/issues/3124) Switch copyright notice * [3128](https://github.com/nunit/nunit/issues/3128) Correct documentation on ParallelScope @@ -431,22 +639,27 @@ and enabling Timeout on tests. * [3139](https://github.com/nunit/nunit/issues/3139) Add Azure pipelines badge to front page * [3144](https://github.com/nunit/nunit/issues/3144) Retry attribute should not derive from PropertyAttribute * [3145](https://github.com/nunit/nunit/issues/3145) Capture additional exception details in the test output -* [3156](https://github.com/nunit/nunit/issues/3156) UnexpectedExceptionTests should tolerate Mono on Azure DevOps Ubuntu +* [3156](https://github.com/nunit/nunit/issues/3156) UnexpectedExceptionTests should tolerate Mono on Azure DevOps + Ubuntu * [3159](https://github.com/nunit/nunit/issues/3159) Make tests more tolerant * [3161](https://github.com/nunit/nunit/issues/3161) https url repo * [3166](https://github.com/nunit/nunit/issues/3166) Allow static SetUpFixture classes -* [3171](https://github.com/nunit/nunit/issues/3171) Incorrect type for Test Fixtures when using running explore with a filter +* [3171](https://github.com/nunit/nunit/issues/3171) Incorrect type for Test Fixtures when using running explore with a + filter * [3175](https://github.com/nunit/nunit/issues/3175) Improve user-facing messages -* [3181](https://github.com/nunit/nunit/issues/3181) Template Based Test Naming - Incorrect truncation for individual arguments +* [3181](https://github.com/nunit/nunit/issues/3181) Template Based Test Naming - Incorrect truncation for individual + arguments * [3186](https://github.com/nunit/nunit/issues/3186) Fix licenseUrl element in nuspec, will be deprecated * [3193](https://github.com/nunit/nunit/issues/3193) Cake Build Fails with Visual Studio 2019 * [3195](https://github.com/nunit/nunit/issues/3195) Drop or at least make Travis not required? -* [3231](https://github.com/nunit/nunit/issues/3231) Breaking change in filter functionality between framework 2.7 and 3.11 +* [3231](https://github.com/nunit/nunit/issues/3231) Breaking change in filter functionality between framework 2.7 and + 3.11 * [3209](https://github.com/nunit/nunit/issues/3209) Test fail when posting to SynchronizationContext.Current * [3211](https://github.com/nunit/nunit/issues/3211) Fix logging * [3218](https://github.com/nunit/nunit/issues/3218) Remove to-dos from the code base * [3222](https://github.com/nunit/nunit/issues/3222) Our build script tests hang when run with Mono on Windows -* [3233](https://github.com/nunit/nunit/issues/3233) AndConstraint should write additional information from failed constraint +* [3233](https://github.com/nunit/nunit/issues/3233) AndConstraint should write additional information from failed + constraint ## NUnit 3.11 - October 6, 2018 @@ -461,35 +674,46 @@ and enabling Timeout on tests. * [352](https://github.com/nunit/nunit/issues/352) Test with infinite loop in TearDown cannot be aborted * [452](https://github.com/nunit/nunit/issues/452) Deprecate the existing Chocolatey framework package * [660](https://github.com/nunit/nunit/issues/660) Order dependence of And and Or constraints should be documented -* [1200](https://github.com/nunit/nunit/issues/1200) async test + Apartment(ApartmentState.STA) => await not returning on STA thread -* [2123](https://github.com/nunit/nunit/issues/2123) Task.Run inside a test will result in deadlock if a control was created previously -* [2146](https://github.com/nunit/nunit/issues/2146) Assert.That with a Throws constraint does not provide as much info as Assert.Throws -* [2427](https://github.com/nunit/nunit/issues/2427) PropertyConstraint throws away the more helpful message in the base constraint result +* [1200](https://github.com/nunit/nunit/issues/1200) async test + Apartment(ApartmentState.STA) => await not returning + on STA thread +* [2123](https://github.com/nunit/nunit/issues/2123) Task.Run inside a test will result in deadlock if a control was + created previously +* [2146](https://github.com/nunit/nunit/issues/2146) Assert.That with a Throws constraint does not provide as much info + as Assert.Throws +* [2427](https://github.com/nunit/nunit/issues/2427) PropertyConstraint throws away the more helpful message in the base + constraint result * [2432](https://github.com/nunit/nunit/issues/2432) Ability to exclude/include the platform .NET Core * [2450](https://github.com/nunit/nunit/issues/2450) NullReferenceException in ExceptionHelper.BuildMessage on Mono * [2536](https://github.com/nunit/nunit/issues/2536) SetArgDisplayNames for TestCaseData and TestFixtureData * [2611](https://github.com/nunit/nunit/issues/2611) Enable .NET Standard 1.6 tests on non-Windows -* [2693](https://github.com/nunit/nunit/issues/2693) Ensure that ReSharper settings are consistent with the editorconfig configuration +* [2693](https://github.com/nunit/nunit/issues/2693) Ensure that ReSharper settings are consistent with the editorconfig + configuration * [2757](https://github.com/nunit/nunit/issues/2757) Broken `char` comparison in v3.7 and higher -* [2759](https://github.com/nunit/nunit/issues/2759) Test fails with "No arguments were provided" error when no values returned from IParameterDataSource +* [2759](https://github.com/nunit/nunit/issues/2759) Test fails with "No arguments were provided" error when no values + returned from IParameterDataSource * [2761](https://github.com/nunit/nunit/issues/2761) Infinite loop in nunit 3.9 * [2781](https://github.com/nunit/nunit/issues/2781) Fixed pre-compiler typo * [2786](https://github.com/nunit/nunit/issues/2786) Timeout value not resetting on Retry of failed test * [2790](https://github.com/nunit/nunit/issues/2790) Removing ITypeInfo abstraction -* [2798](https://github.com/nunit/nunit/issues/2798) [Request] Show actual count value when test fail on Has.Exactly(x).Items +* [2798](https://github.com/nunit/nunit/issues/2798) [Request] Show actual count value when test fail on + Has.Exactly(x).Items * [2814](https://github.com/nunit/nunit/issues/2814) Remove public marker types * [2819](https://github.com/nunit/nunit/issues/2819) Only run AppVeyor PR build against open PRs -* [2821](https://github.com/nunit/nunit/issues/2821) Save and restore the SynchronizationContext before and after each test case -* [2823](https://github.com/nunit/nunit/issues/2823) SetUp failed for test fixture - Array was not a one-dimensional array. Issue seems related to byte[,] method parameters +* [2821](https://github.com/nunit/nunit/issues/2821) Save and restore the SynchronizationContext before and after each + test case +* [2823](https://github.com/nunit/nunit/issues/2823) SetUp failed for test fixture - Array was not a one-dimensional + array. Issue seems related to byte[,] method parameters * [2829](https://github.com/nunit/nunit/issues/2829) Obsoletion warning for DataAttribute * [2831](https://github.com/nunit/nunit/issues/2831) Regular "BusyExecIdle after 200 milliseconds delay" CI failures * [2833](https://github.com/nunit/nunit/issues/2833) Use longer BusyExecIdle to avoid CI failures * [2836](https://github.com/nunit/nunit/issues/2836) NUnit.Framework.Does cannot be extended -* [2837](https://github.com/nunit/nunit/issues/2837) DictionaryContainsKeyConstraint behavior is inconstant with Dictionary.ContainsKey when the dictionary uses a custom Comparer +* [2837](https://github.com/nunit/nunit/issues/2837) DictionaryContainsKeyConstraint behavior is inconstant with + Dictionary.ContainsKey when the dictionary uses a custom Comparer * [2842](https://github.com/nunit/nunit/issues/2842) Supporting inheritance of Assert and related classes * [2854](https://github.com/nunit/nunit/issues/2854) Has.All.../Has.None... - show non-matching items in error message * [2863](https://github.com/nunit/nunit/issues/2863) Make tests robust without depending on the order of attributes -* [2867](https://github.com/nunit/nunit/issues/2867) Skip executing TestCaseSources for tests which are not included in the filter +* [2867](https://github.com/nunit/nunit/issues/2867) Skip executing TestCaseSources for tests which are not included in + the filter * [2876](https://github.com/nunit/nunit/issues/2876) Implement Discovery-time filtering for NUnitLite * [2883](https://github.com/nunit/nunit/issues/2883) Our public ConcurrentQueue causes type conflicts * [2885](https://github.com/nunit/nunit/issues/2885) Copy/paste error in Assert.That documentation @@ -503,46 +727,47 @@ and enabling Timeout on tests. * [2940](https://github.com/nunit/nunit/issues/2940) Increase StackTracesAreFiltered amount to 5 * [2955](https://github.com/nunit/nunit/issues/2955) Potential threading issue in IsolatedContext * [2965](https://github.com/nunit/nunit/issues/2965) NuGet Package : Add `repository` metadata. -* [2970](https://github.com/nunit/nunit/issues/2970) InvalidCastException @ NUnit.Framework.TestFixtureSourceAttribute.BuildFrom +* [2970](https://github.com/nunit/nunit/issues/2970) InvalidCastException @ + NUnit.Framework.TestFixtureSourceAttribute.BuildFrom * [2979](https://github.com/nunit/nunit/issues/2979) Warn.If in Assert.Multiple -* [2994](https://github.com/nunit/nunit/issues/2994) Error in .NET Standard 1.4 DictionaryContainsKeyConstraint MetadataToken compatibility methods +* [2994](https://github.com/nunit/nunit/issues/2994) Error in .NET Standard 1.4 DictionaryContainsKeyConstraint + MetadataToken compatibility methods * [2996](https://github.com/nunit/nunit/issues/2996) Remove unused enum * [3009](https://github.com/nunit/nunit/issues/3009) Fix failing CI Builds by upgrading to NUnit Console 3.9.0 * [3020](https://github.com/nunit/nunit/issues/3020) Upgrade nunit-vs-adapter to 3.10 for nUnit 3.11 -* [3024](https://github.com/nunit/nunit/issues/3024) Unable to add `.IgnoreCase` modifier to an `AnyOf` constraint in collection constraints +* [3024](https://github.com/nunit/nunit/issues/3024) Unable to add `.IgnoreCase` modifier to an `AnyOf` constraint in + collection constraints * [3032](https://github.com/nunit/nunit/issues/3032) APIs to restore before 3.11 ## NUnit 3.10.1 - March 12, 2018 -Added a namespace to the props file included in the NuGet package to make it -compatible with versions of Visual Studio prior to VS 2017. +Added a namespace to the props file included in the NuGet package to make it compatible with versions of Visual Studio +prior to VS 2017. ## NUnit 3.10 - March 12, 2018 -This release adds a .NET Standard 2.0 version of the framework which re-enables -most of the features that have been missing in our earlier .NET Standard builds -like parallelism, timeouts, directory and path based asserts, etc. It also contains -numerous bug fixes and smaller enhancements. We've improved our XML docs, -fixed performance issues and added more detail to Multiple Asserts. +This release adds a .NET Standard 2.0 version of the framework which re-enables most of the features that have been +missing in our earlier .NET Standard builds like parallelism, timeouts, directory and path based asserts, etc. It also +contains numerous bug fixes and smaller enhancements. We've improved our XML docs, fixed performance issues and added +more detail to Multiple Asserts. -This release also contains source-indexed PDB files allowing developers to debug -into the NUnit Framework. This allows you to track down errors or see how the -framework works. +This release also contains source-indexed PDB files allowing developers to debug into the NUnit Framework. This allows +you to track down errors or see how the framework works. -In order to support the .NET Standard 2.0 version, the NUnit project switched to -the new CSPROJ format and now requires Visual Studio 2017 to compile. This only -effects people contributing to the project. NUnit still supports building and -compiling your tests in older .NET IDEs and NUnit still supports older versions -of the .NET Framework back to 2.0. For contributors, NUnit can now compile all -supported targets on Windows, Linux and Mac using the Cake command line build. +In order to support the .NET Standard 2.0 version, the NUnit project switched to the new CSPROJ format and now requires +Visual Studio 2017 to compile. This only effects people contributing to the project. NUnit still supports building and +compiling your tests in older .NET IDEs and NUnit still supports older versions of the .NET Framework back to 2.0. For +contributors, NUnit can now compile all supported targets on Windows, Linux and Mac using the Cake command line build. ### Issues Resolved * [1212](https://github.com/nunit/nunit/issues/1212) Separate AssertionHelper project or assembly * [1373](https://github.com/nunit/nunit/issues/1373) Setting with a null value -* [1382](https://github.com/nunit/nunit/issues/1382) Use array argument contents in name of parameterized tests rather than just array type. +* [1382](https://github.com/nunit/nunit/issues/1382) Use array argument contents in name of parameterized tests rather + than just array type. * [1578](https://github.com/nunit/nunit/issues/1578) TestContext.CurrentTest exposes too much internal info -* [1678](https://github.com/nunit/nunit/issues/1678) Result Message: OneTimeSetUp: Category name must not contain ',', '!', '+' or '-' +* [1678](https://github.com/nunit/nunit/issues/1678) Result Message: OneTimeSetUp: Category name must not contain ',', + '!', '+' or '-' * [1944](https://github.com/nunit/nunit/issues/1944) Removing Compact Framework workarounds * [1958](https://github.com/nunit/nunit/issues/1958) System.Reflection.TargetInvocationException after run finished * [2033](https://github.com/nunit/nunit/issues/2033) Nameof refactor @@ -556,23 +781,31 @@ supported targets on Windows, Linux and Mac using the Cake command line build. * [2518](https://github.com/nunit/nunit/issues/2518) Bug in CollectionAssert.AreEqual for ValueTuples. * [2530](https://github.com/nunit/nunit/issues/2530) Running tests on main thread. Revisiting #2483 * [2542](https://github.com/nunit/nunit/issues/2542) NUnit does not support parallelism on .NET Core 2.0 -* [2555](https://github.com/nunit/nunit/issues/2555) CI timeout: NUnit.Framework.Assertions.CollectionAssertTest.PerformanceTests +* [2555](https://github.com/nunit/nunit/issues/2555) CI timeout: + NUnit.Framework.Assertions.CollectionAssertTest.PerformanceTests * [2564](https://github.com/nunit/nunit/issues/2564) Add minClientVersion to .nuspec files * [2566](https://github.com/nunit/nunit/issues/2566) Refactor `SimpleEnumerableWithIEquatable` test object * [2577](https://github.com/nunit/nunit/issues/2577) Warning in TearDown is inconsistent with Assertion failure * [2580](https://github.com/nunit/nunit/issues/2580) Remove unused defines -* [2591](https://github.com/nunit/nunit/issues/2591) NUnitEqualityComparer.Default should be replaced with new NUnitEqualityComparer() -* [2592](https://github.com/nunit/nunit/issues/2592) Add .props with ProjectCapability to suppress test project service GUID item -* [2608](https://github.com/nunit/nunit/issues/2608) Culture differences on .NET Core on non-Windows causes test failures +* [2591](https://github.com/nunit/nunit/issues/2591) NUnitEqualityComparer.Default should be replaced with new + NUnitEqualityComparer() +* [2592](https://github.com/nunit/nunit/issues/2592) Add .props with ProjectCapability to suppress test project service + GUID item +* [2608](https://github.com/nunit/nunit/issues/2608) Culture differences on .NET Core on non-Windows causes test + failures * [2622](https://github.com/nunit/nunit/issues/2622) Fix flakey test * [2624](https://github.com/nunit/nunit/issues/2624) Prevent emails for successful builds on Travis -* [2626](https://github.com/nunit/nunit/issues/2626) SetUp/TearDown methods are invoked multiple times before/after test in .NET Standard targeted projects -* [2627](https://github.com/nunit/nunit/issues/2627) Breaking change in CollectionAssert.AllItemsAreUnique with NUnit 3.9 +* [2626](https://github.com/nunit/nunit/issues/2626) SetUp/TearDown methods are invoked multiple times before/after test + in .NET Standard targeted projects +* [2627](https://github.com/nunit/nunit/issues/2627) Breaking change in CollectionAssert.AllItemsAreUnique with NUnit + 3.9 * [2628](https://github.com/nunit/nunit/issues/2628) Error during installing tools when running build script -* [2630](https://github.com/nunit/nunit/issues/2630) Framework throws NullReferenceException if test parameter is marked with [Values(null)] +* [2630](https://github.com/nunit/nunit/issues/2630) Framework throws NullReferenceException if test parameter is marked + with [Values(null)] * [2632](https://github.com/nunit/nunit/issues/2632) Parallel tests are loading 100% CPU when nested SetUpFixture exists * [2639](https://github.com/nunit/nunit/issues/2639) ValuesAttribute causes ExpectedResult to have no effect -* [2647](https://github.com/nunit/nunit/issues/2647) Add Current Attempt indicator in TestContext for use with RetryAttribute +* [2647](https://github.com/nunit/nunit/issues/2647) Add Current Attempt indicator in TestContext for use with + RetryAttribute * [2654](https://github.com/nunit/nunit/issues/2654) Address feedback from `@oznetmaster` * [2656](https://github.com/nunit/nunit/issues/2656) NuGet package links to outdated license * [2659](https://github.com/nunit/nunit/issues/2659) Naming Errors @@ -585,93 +818,120 @@ supported targets on Windows, Linux and Mac using the Cake command line build. * [2688](https://github.com/nunit/nunit/issues/2688) Assert.Throws swallows console output * [2695](https://github.com/nunit/nunit/issues/2695) MultipleAssertException doesn't provide proper details on failures * [2698](https://github.com/nunit/nunit/issues/2698) Syntax suggestions errors as warnings -* [2704](https://github.com/nunit/nunit/issues/2704) Add Constraint to test whether actual item is contained in expected collection +* [2704](https://github.com/nunit/nunit/issues/2704) Add Constraint to test whether actual item is contained in expected + collection * [2711](https://github.com/nunit/nunit/issues/2711) NUnitLite: Add support for `--nocolor` option * [2714](https://github.com/nunit/nunit/issues/2714) AnyOfConstraint enumerates multiple times * [2725](https://github.com/nunit/nunit/issues/2725) Enable 'strict' compilation flag * [2726](https://github.com/nunit/nunit/issues/2726) Replace the ConcurrentQueue and SpinWait compatibility classes * [2727](https://github.com/nunit/nunit/issues/2727) Avoid treating warnings as errors inside the IDE -* [2734](https://github.com/nunit/nunit/issues/2734) TestCaseAttribute: ExpectedResult should support same value conversion as normal method arguments -* [2742](https://github.com/nunit/nunit/issues/2742) FailureSite not correctly set on containing suites when tests are ignored. +* [2734](https://github.com/nunit/nunit/issues/2734) TestCaseAttribute: ExpectedResult should support same value + conversion as normal method arguments +* [2742](https://github.com/nunit/nunit/issues/2742) FailureSite not correctly set on containing suites when tests are + ignored. * [2749](https://github.com/nunit/nunit/issues/2749) Update Travis SDK versions ## NUnit 3.9 - November 10, 2017 -This release addresses numerous parallelization issues that were introduced in 3.8 when method level parallelization was added. Most of the parallelization issues resolved were tests never completing when using some combinations of parallel tests and `ApartmentState` not being properly applied to tests in all cases. +This release addresses numerous parallelization issues that were introduced in 3.8 when method level parallelization was +added. Most of the parallelization issues resolved were tests never completing when using some combinations of parallel +tests and `ApartmentState` not being properly applied to tests in all cases. ### Issues Resolved * [893](https://github.com/nunit/nunit/issues/893) Inconsistent Tuple behavior. * [1239](https://github.com/nunit/nunit/issues/1239) NUnit3 sometimes hangs if SetUpFixtures are run in parallel -* [1346](https://github.com/nunit/nunit/issues/1346) NullReferenceException when [TestFixtureSource] refers to data in a generic class. +* [1346](https://github.com/nunit/nunit/issues/1346) NullReferenceException when [TestFixtureSource] refers to data in a + generic class. * [1473](https://github.com/nunit/nunit/issues/1473) Allow Is.Ordered to Compare Null Values -* [1899](https://github.com/nunit/nunit/issues/1899) Constraint Throws.Exception does not catch exception with async lambdas -* [1905](https://github.com/nunit/nunit/issues/1905) SetupFixture without namespace will make assembly-level Parallelizable attribute useless -* [2091](https://github.com/nunit/nunit/issues/2091) When a native exception of corrupted state is thrown, nunit test thread crashes and the nunit-console process hangs +* [1899](https://github.com/nunit/nunit/issues/1899) Constraint Throws.Exception does not catch exception with async + lambdas +* [1905](https://github.com/nunit/nunit/issues/1905) SetupFixture without namespace will make assembly-level + Parallelizable attribute useless +* [2091](https://github.com/nunit/nunit/issues/2091) When a native exception of corrupted state is thrown, nunit test + thread crashes and the nunit-console process hangs * [2102](https://github.com/nunit/nunit/issues/2102) NUnitLite incorrectly reports Win 10 OS name -* [2271](https://github.com/nunit/nunit/issues/2271) When CollectionAssert.AreEqual do compare each element, it will ignore the IEquatable of the element too +* [2271](https://github.com/nunit/nunit/issues/2271) When CollectionAssert.AreEqual do compare each element, it will + ignore the IEquatable of the element too * [2289](https://github.com/nunit/nunit/issues/2289) ResolveTypeNameDifference does not handle generic types well * [2311](https://github.com/nunit/nunit/issues/2311) Resolve test projects' namespace situation -* [2319](https://github.com/nunit/nunit/issues/2319) Add .editorconfig to set file encodings so that people don't have to think about it -* [2364](https://github.com/nunit/nunit/issues/2364) Parallelizable attribute not invalidating invalid parallel scope combinations +* [2319](https://github.com/nunit/nunit/issues/2319) Add .editorconfig to set file encodings so that people don't have + to think about it +* [2364](https://github.com/nunit/nunit/issues/2364) Parallelizable attribute not invalidating invalid parallel scope + combinations * [2372](https://github.com/nunit/nunit/issues/2372) Create testing for compounded ConstraintFilters -* [2388](https://github.com/nunit/nunit/issues/2388) Parallelization causes test cases to stop respecting fixture's apartment state +* [2388](https://github.com/nunit/nunit/issues/2388) Parallelization causes test cases to stop respecting fixture's + apartment state * [2395](https://github.com/nunit/nunit/issues/2395) NUnit 3.8+ does not finish running tests -* [2398](https://github.com/nunit/nunit/issues/2398) NUnit CI spurious failures, NUnit.Framework.Internal.ThreadUtilityTests.Kill -* [2402](https://github.com/nunit/nunit/issues/2402) --labels=All doesn't show anything in console output executing NUnitLite Console Runner +* [2398](https://github.com/nunit/nunit/issues/2398) NUnit CI spurious failures, + NUnit.Framework.Internal.ThreadUtilityTests.Kill +* [2402](https://github.com/nunit/nunit/issues/2402) --labels=All doesn't show anything in console output executing + NUnitLite Console Runner * [2406](https://github.com/nunit/nunit/issues/2406) Summary descriptions replaced by more detailed ones * [2411](https://github.com/nunit/nunit/issues/2411) And constraint on Has.Member throws * [2412](https://github.com/nunit/nunit/issues/2412) Using fluent syntax unintentionally removed in 3.8 * [2418](https://github.com/nunit/nunit/issues/2418) Support equality comparison delegate -* [2422](https://github.com/nunit/nunit/issues/2422) Has.Property causes AmbiguousMatchException for shadowing properties +* [2422](https://github.com/nunit/nunit/issues/2422) Has.Property causes AmbiguousMatchException for shadowing + properties * [2425](https://github.com/nunit/nunit/issues/2425) XML doc typo fix -* [2426](https://github.com/nunit/nunit/issues/2426) Regression in 3.8.1: ApartmentAttribute no longer works when applied to an assembly -* [2428](https://github.com/nunit/nunit/issues/2428) Fix NullReferenceExceptions caused by WorkItemQueue not being thread-safe +* [2426](https://github.com/nunit/nunit/issues/2426) Regression in 3.8.1: ApartmentAttribute no longer works when + applied to an assembly +* [2428](https://github.com/nunit/nunit/issues/2428) Fix NullReferenceExceptions caused by WorkItemQueue not being + thread-safe * [2429](https://github.com/nunit/nunit/issues/2429) Stack trace shown for Assert.Warn * [2438](https://github.com/nunit/nunit/issues/2438) [Parallelizable] hangs after a few tests -* [2441](https://github.com/nunit/nunit/issues/2441) Allows to override load-time/execution-time interfaces in built-in tests attributes +* [2441](https://github.com/nunit/nunit/issues/2441) Allows to override load-time/execution-time interfaces in built-in + tests attributes * [2446](https://github.com/nunit/nunit/issues/2446) CI failure in mono Warning tests -* [2448](https://github.com/nunit/nunit/issues/2448) Inherited Test SetUp, TearDown, etc. are not executed in .NET Core if they are not public +* [2448](https://github.com/nunit/nunit/issues/2448) Inherited Test SetUp, TearDown, etc. are not executed in .NET Core + if they are not public * [2451](https://github.com/nunit/nunit/issues/2451) Compile RegEx to improve performance * [2454](https://github.com/nunit/nunit/issues/2454) SetUpFixture not respecting NonParallelizable tag on TestFixtures. * [2459](https://github.com/nunit/nunit/issues/2459) [Parallelizable(ParallelScope.Children)] Unable to finish tests -* [2465](https://github.com/nunit/nunit/issues/2465) Possible wrong properties are returned by reflection in ReflectionExtensions.cs +* [2465](https://github.com/nunit/nunit/issues/2465) Possible wrong properties are returned by reflection in + ReflectionExtensions.cs * [2467](https://github.com/nunit/nunit/issues/2467) Test execution hangs when using [SetUpFixture] with NUnit 3.8.x -* [2469](https://github.com/nunit/nunit/issues/2469) Allow RangeAttribute to be specified multiple times for the same argument +* [2469](https://github.com/nunit/nunit/issues/2469) Allow RangeAttribute to be specified multiple times for the same + argument * [2471](https://github.com/nunit/nunit/issues/2471) Parametrized test cases not running in parallel * [2475](https://github.com/nunit/nunit/issues/2475) Framework incorrectly identifies Win 10 in xml results * [2478](https://github.com/nunit/nunit/issues/2478) Attributes on SetUpFixture are not applied -* [2486](https://github.com/nunit/nunit/issues/2486) Message when asserting null with Is.EquivalentTo could be more helpful +* [2486](https://github.com/nunit/nunit/issues/2486) Message when asserting null with Is.EquivalentTo could be more + helpful * [2497](https://github.com/nunit/nunit/issues/2497) Use ConstraintUtils.RequireActual through out the codebase * [2504](https://github.com/nunit/nunit/issues/2504) Support changing test display name on TestFixtureData * [2508](https://github.com/nunit/nunit/issues/2508) Correct divergence from shadowed Is / Has members. -* [2516](https://github.com/nunit/nunit/issues/2516) When test writes something to the stdErr there is no guaranteed way to link a test-output event to a target test using ITestEventListener +* [2516](https://github.com/nunit/nunit/issues/2516) When test writes something to the stdErr there is no guaranteed way + to link a test-output event to a target test using ITestEventListener * [2525](https://github.com/nunit/nunit/issues/2525) Remove unwanted space from comment * [2526](https://github.com/nunit/nunit/issues/2526) SerializationException in low trust floating point equality test -* [2533](https://github.com/nunit/nunit/issues/2533) Matches`(Predicate)` throws ArgumentException or Fails when actual is null +* [2533](https://github.com/nunit/nunit/issues/2533) Matches`(Predicate)` throws ArgumentException or Fails when + actual is null * [2534](https://github.com/nunit/nunit/issues/2534) SetUpFixture causes NUnit to lock with Apartment( STA ) * [2551](https://github.com/nunit/nunit/issues/2551) CollectionItemsEqualConstraint is missing Using(Func) * [2554](https://github.com/nunit/nunit/issues/2554) Made TestFixtureData.SetName internal for 3.9 ## NUnit 3.8.1 - August 28, 2017 -This release fixes two critical regressions in the 3.8 release. The first caused the console runner to crash if you are using test parameters. The second issue caused collection constraints checking for multiple items in a collection to fail. +This release fixes two critical regressions in the 3.8 release. The first caused the console runner to crash if you are +using test parameters. The second issue caused collection constraints checking for multiple items in a collection to +fail. ### Issues Resolved * [2386](https://github.com/nunit/nunit/issues/2386) Contains.Item() fails for collections in NUnit 3.8 -* [2390](https://github.com/nunit/nunit/issues/2390) Missing value attribute in test parameters setting causes NullReferenceException in console +* [2390](https://github.com/nunit/nunit/issues/2390) Missing value attribute in test parameters setting causes + NullReferenceException in console ## NUnit 3.8 - August 27, 2017 -This release removes several methods and attributes that were marked obsolete in the -original 3.0 release. Support for iOS and Android has been improved. +This release removes several methods and attributes that were marked obsolete in the original 3.0 release. Support for +iOS and Android has been improved. -An issue that caused unit tests to run slower was addressed as was a bug that prevented -the use of Assert.Multiple in async code. +An issue that caused unit tests to run slower was addressed as was a bug that prevented the use of Assert.Multiple in +async code. -The Order attribute can now also be applied to the class level to set the order -that test fixtures will be run. +The Order attribute can now also be applied to the class level to set the order that test fixtures will be run. ### Issues Resolved @@ -683,48 +943,62 @@ that test fixtures will be run. * [1851](https://github.com/nunit/nunit/issues/1851) TestCaseSource unable to pass one element byte array * [1996](https://github.com/nunit/nunit/issues/1996) Timeout does not work if native code is running at the time * [2004](https://github.com/nunit/nunit/issues/2004) Has.One as synonym for Has.Exactly(1).Items -* [2062](https://github.com/nunit/nunit/issues/2062) TestCaseSource attribute causes test to pass when source is not defined +* [2062](https://github.com/nunit/nunit/issues/2062) TestCaseSource attribute causes test to pass when source is not + defined * [2144](https://github.com/nunit/nunit/issues/2144) Allow option on RandomAttribute to produce distinct values -* [2179](https://github.com/nunit/nunit/issues/2179) Some NUnit project's tests fail on systems with CultureInfo other than en +* [2179](https://github.com/nunit/nunit/issues/2179) Some NUnit project's tests fail on systems with CultureInfo other + than en * [2195](https://github.com/nunit/nunit/issues/2195) Contains.Substring with custom StringComparison -* [2196](https://github.com/nunit/nunit/issues/2196) Expose ParallelizableAttribute (and other attribute) constructor arguments as properties -* [2201](https://github.com/nunit/nunit/issues/2201) Invalid platform name passed to PlatformAttribute should mark test NotRunnable +* [2196](https://github.com/nunit/nunit/issues/2196) Expose ParallelizableAttribute (and other attribute) constructor + arguments as properties +* [2201](https://github.com/nunit/nunit/issues/2201) Invalid platform name passed to PlatformAttribute should mark test + NotRunnable * [2208](https://github.com/nunit/nunit/issues/2208) StackFilter trims leading spaces from each line -* [2213](https://github.com/nunit/nunit/issues/2213) SetCultureAttribute: CultureInfo ctor should use default culture settings -* [2217](https://github.com/nunit/nunit/issues/2217) Console runner performance varies wildly depending on environmental characteristics +* [2213](https://github.com/nunit/nunit/issues/2213) SetCultureAttribute: CultureInfo ctor should use default culture + settings +* [2217](https://github.com/nunit/nunit/issues/2217) Console runner performance varies wildly depending on environmental + characteristics * [2219](https://github.com/nunit/nunit/issues/2219) Remove Obsolete Attributes * [2225](https://github.com/nunit/nunit/issues/2225) OneTimeTearDown and Dispose Ordering * [2237](https://github.com/nunit/nunit/issues/2237) System.Runtime.Loader not available for iOS/Android -* [2242](https://github.com/nunit/nunit/issues/2242) Running tests directly should never surface a NullReferenceException +* [2242](https://github.com/nunit/nunit/issues/2242) Running tests directly should never surface a + NullReferenceException * [2244](https://github.com/nunit/nunit/issues/2244) Add KeyValuePair to the default formatters * [2251](https://github.com/nunit/nunit/issues/2251) Randomizer.NextGuid() -* [2253](https://github.com/nunit/nunit/issues/2253) Parallelizable(ParallelScope.Fixtures) doesn't work on a TestFixture +* [2253](https://github.com/nunit/nunit/issues/2253) Parallelizable(ParallelScope.Fixtures) doesn't work on a + TestFixture * [2254](https://github.com/nunit/nunit/issues/2254) EqualTo on ValueTuple with Nullable unexpected -* [2261](https://github.com/nunit/nunit/issues/2261) When an assembly is marked with ParallelScope.None and there are Parallelizable tests NUnit hangs -* [2269](https://github.com/nunit/nunit/issues/2269) Parallelizable and NonParallelizable attributes on setup and teardown silently ignored +* [2261](https://github.com/nunit/nunit/issues/2261) When an assembly is marked with ParallelScope.None and there are + Parallelizable tests NUnit hangs +* [2269](https://github.com/nunit/nunit/issues/2269) Parallelizable and NonParallelizable attributes on setup and + teardown silently ignored * [2276](https://github.com/nunit/nunit/issues/2276) Intermittent test failures in Travis CI: TestContextTests * [2281](https://github.com/nunit/nunit/issues/2281) Add type constraint for Throws and any method requiring Exception * [2288](https://github.com/nunit/nunit/issues/2288) Killing thread cancels test run * [2292](https://github.com/nunit/nunit/issues/2292) Is.Ordered.By() with a field throws NullReferenceException -* [2298](https://github.com/nunit/nunit/issues/2298) Write TestParametersDictionary to xml result file in readable format +* [2298](https://github.com/nunit/nunit/issues/2298) Write TestParametersDictionary to xml result file in readable + format * [2299](https://github.com/nunit/nunit/issues/2299) NUnitLite NuGet package no longer installs NUnit NuGet package * [2304](https://github.com/nunit/nunit/issues/2304) Revert accidental doc removal * [2305](https://github.com/nunit/nunit/issues/2305) Correct misprint ".con" -> ".com" * [2312](https://github.com/nunit/nunit/issues/2312) Prevent crash on invalid --result parsing in NUnitLite * [2313](https://github.com/nunit/nunit/issues/2313) Incorrect xml doc on RetryAttribute * [2332](https://github.com/nunit/nunit/issues/2332) Update build script to use NUnitConsoleRunner v3.7.0 -* [2335](https://github.com/nunit/nunit/issues/2335) Execute OneTimeTearDown as early as possible when running fixtures in parallel +* [2335](https://github.com/nunit/nunit/issues/2335) Execute OneTimeTearDown as early as possible when running fixtures + in parallel * [2342](https://github.com/nunit/nunit/issues/2342) Remove deprecated Is.String* Constraints * [2348](https://github.com/nunit/nunit/issues/2348) Can't use Assert.Multiple with async code * [2353](https://github.com/nunit/nunit/issues/2353) Provide additional Result information through TestContext * [2358](https://github.com/nunit/nunit/issues/2358) Get framework to build under Mono 5.0 * [2360](https://github.com/nunit/nunit/issues/2360) Obsolete CollectionContainsConstraint Constructors -* [2361](https://github.com/nunit/nunit/issues/2361) NUnit Parallelizable and OneTimeSetUp with no namespace results in single-threaded test execution +* [2361](https://github.com/nunit/nunit/issues/2361) NUnit Parallelizable and OneTimeSetUp with no namespace results in + single-threaded test execution * [2370](https://github.com/nunit/nunit/issues/2370) TestCaseAttribute can't convert int to nullable long ## NUnit 3.7.1 - June 6, 2017 -This is a hotfix release that addresses occasional hangs when using test parallelization and fixes crashes in NCrunch prior to version 3.9. +This is a hotfix release that addresses occasional hangs when using test parallelization and fixes crashes in NCrunch +prior to version 3.9. ### Issues Resolved @@ -733,18 +1007,16 @@ This is a hotfix release that addresses occasional hangs when using test paralle ## NUnit 3.7 - May 29, 2017 -This release of NUnit expands on parallel test execution to allow test methods to -be run in parallel. Please see the [Parallelizable Attribute](xref:parallelizableattribute) -for more information. +This release of NUnit expands on parallel test execution to allow test methods to be run in parallel. Please see the +[Parallelizable Attribute](xref:parallelizableattribute) for more information. -NUnit 3.7 also drops the Portable build of the framework and replaces it with a -.NET Standard 1.3 version to compliment the .NET Standard 1.6 version. This change -enables several constraints and other features in the .NET Standard builds that -weren't available in portable like Path and Directory based asserts. +NUnit 3.7 also drops the Portable build of the framework and replaces it with a .NET Standard 1.3 version to compliment +the .NET Standard 1.6 version. This change enables several constraints and other features in the .NET Standard builds +that weren't available in portable like Path and Directory based asserts. -The AssertionHelper class has been deprecated because it is seldom used and has -not received any of the updates that Asserts and Constraints receive. If your code -is using the AssertionHelper class, we recommend that you migrate your asserts. +The AssertionHelper class has been deprecated because it is seldom used and has not received any of the updates that +Asserts and Constraints receive. If your code is using the AssertionHelper class, we recommend that you migrate your +asserts. ### Issues Resolved @@ -756,26 +1028,33 @@ is using the AssertionHelper class, we recommend that you migrate your asserts. * [1143](https://github.com/nunit/nunit/issues/1143) NUnitLite - Explore flag does not apply where filter to output * [1238](https://github.com/nunit/nunit/issues/1238) Feature request: Print LoaderExceptions when fixture loading fails * [1363](https://github.com/nunit/nunit/issues/1363) Make Timeouts work without running test on its own thread -* [1474](https://github.com/nunit/nunit/issues/1474) Several SetUpFixtures at the same level may be active at the same time +* [1474](https://github.com/nunit/nunit/issues/1474) Several SetUpFixtures at the same level may be active at the same + time * [1819](https://github.com/nunit/nunit/issues/1819) TestContext.Progress.Write writes new line * [1830](https://github.com/nunit/nunit/issues/1830) Add --labels switch changes to NUnitLite and NUnitLite tests * [1859](https://github.com/nunit/nunit/issues/1859) ConcurrentQueue is duplicate with System.Threading.dll package -* [1877](https://github.com/nunit/nunit/issues/1877) Resolve differences between NUnit Console and NUnitLite implementations of @filename +* [1877](https://github.com/nunit/nunit/issues/1877) Resolve differences between NUnit Console and NUnitLite + implementations of @filename * [1885](https://github.com/nunit/nunit/issues/1885) Test parameter containing a semicolon -* [1896](https://github.com/nunit/nunit/issues/1896) Test has passed however Reason with an empty message is printed in the xml -* [1918](https://github.com/nunit/nunit/issues/1918) Changing DefaultFloatingPointTolerance breaks tests running in parallel +* [1896](https://github.com/nunit/nunit/issues/1896) Test has passed however Reason with an empty message is printed in + the xml +* [1918](https://github.com/nunit/nunit/issues/1918) Changing DefaultFloatingPointTolerance breaks tests running in + parallel * [1932](https://github.com/nunit/nunit/issues/1932) NUnit Warn class should be removed from stack trace by filter -* [1934](https://github.com/nunit/nunit/issues/1934) NullReferenceException when null arguments are used in TestFixtureAttribute +* [1934](https://github.com/nunit/nunit/issues/1934) NullReferenceException when null arguments are used in + TestFixtureAttribute * [1952](https://github.com/nunit/nunit/issues/1952) TestContext.Out null when used in task with .NET Core * [1963](https://github.com/nunit/nunit/issues/1963) Investigate removing SpecialValue * [1965](https://github.com/nunit/nunit/issues/1965) TestContext does not flow in async method * [1971](https://github.com/nunit/nunit/issues/1971) Switch CHANGES.txt to Markdown -* [1973](https://github.com/nunit/nunit/issues/1973) Implemented TestExecutionContext to use AsyncLocal<> for `NETSTANDARD1_6` +* [1973](https://github.com/nunit/nunit/issues/1973) Implemented TestExecutionContext to use AsyncLocal<> for + `NETSTANDARD1_6` * [1975](https://github.com/nunit/nunit/issues/1975) TestFixtureSource doesn't work with a class that has no namespace * [1983](https://github.com/nunit/nunit/issues/1983) Add missing ConstraintExpression.Contain overload * [1990](https://github.com/nunit/nunit/issues/1990) Add namespace filter * [1997](https://github.com/nunit/nunit/issues/1997) Remove unused --verbose and --full command line options -* [1999](https://github.com/nunit/nunit/issues/1999) Author Tests assume ICustomAttributeProvider.GetCustomAttributes return order is defined +* [1999](https://github.com/nunit/nunit/issues/1999) Author Tests assume ICustomAttributeProvider.GetCustomAttributes + return order is defined * [2003](https://github.com/nunit/nunit/issues/2003) Better user info about ParallelizableAttribute and ParallelScope * [2005](https://github.com/nunit/nunit/issues/2005) Exclude empty failure messages from results xml * [2007](https://github.com/nunit/nunit/issues/2007) 3.6 Multiple assertion backwards compatibility @@ -790,11 +1069,14 @@ is using the AssertionHelper class, we recommend that you migrate your asserts. * [2040](https://github.com/nunit/nunit/issues/2040) Cannot catch AssertionException * [2045](https://github.com/nunit/nunit/issues/2045) NUnitLite-runner crashes if no file is provided * [2050](https://github.com/nunit/nunit/issues/2050) Creation of TestExecutionContext should be explicit -* [2052](https://github.com/nunit/nunit/issues/2052) NullReferenceException with TestCaseSource if a property has no setter +* [2052](https://github.com/nunit/nunit/issues/2052) NullReferenceException with TestCaseSource if a property has no + setter * [2061](https://github.com/nunit/nunit/issues/2061) TestContext.WorkDirectory not initialized during build process -* [2079](https://github.com/nunit/nunit/issues/2079) Make TestMethod.Arguments public or otherwise accessible (e.g. TestContext) +* [2079](https://github.com/nunit/nunit/issues/2079) Make TestMethod.Arguments public or otherwise accessible (e.g. + TestContext) * [2080](https://github.com/nunit/nunit/issues/2080) Allow comments in @FILE files -* [2087](https://github.com/nunit/nunit/issues/2087) Enhance error message: Test is not runnable in single-threaded context. Timeout +* [2087](https://github.com/nunit/nunit/issues/2087) Enhance error message: Test is not runnable in single-threaded + context. Timeout * [2092](https://github.com/nunit/nunit/issues/2092) Convert Portable library to .NET Standard 1.3 * [2095](https://github.com/nunit/nunit/issues/2095) Extend use of tolerance to ComparisonConstraints * [2099](https://github.com/nunit/nunit/issues/2099) Include type in start-suite/start-test report elements @@ -802,38 +1084,47 @@ is using the AssertionHelper class, we recommend that you migrate your asserts. * [2115](https://github.com/nunit/nunit/issues/2115) Mark AssertionHelper as Obsolete * [2121](https://github.com/nunit/nunit/issues/2121) Chained PropertyConstraint constraints report incorrect ActualValue * [2131](https://github.com/nunit/nunit/issues/2131) Remove "Version 3" suffix from NUnitLite NuGet Package -* [2132](https://github.com/nunit/nunit/issues/2132) TestFixtureTests.CapturesArgumentsForConstructorWithMultipleArgsSupplied assumes order of custom attributes -* [2143](https://github.com/nunit/nunit/issues/2143) Non-parallel fixture with parallel children runs in parallel with other fixtures -* [2147](https://github.com/nunit/nunit/issues/2147) Test Assembly using NUnitLite & NUnit 3.6.1 hangs under .NET Core when `--timeout` is supplied on command line +* [2132](https://github.com/nunit/nunit/issues/2132) + TestFixtureTests.CapturesArgumentsForConstructorWithMultipleArgsSupplied assumes order of custom attributes +* [2143](https://github.com/nunit/nunit/issues/2143) Non-parallel fixture with parallel children runs in parallel with + other fixtures +* [2147](https://github.com/nunit/nunit/issues/2147) Test Assembly using NUnitLite & NUnit 3.6.1 hangs under .NET Core + when `--timeout` is supplied on command line * [2150](https://github.com/nunit/nunit/issues/2150) Add portable-slow-tests to Cake file * [2152](https://github.com/nunit/nunit/issues/2152) Allow attaching files to TestResults * [2154](https://github.com/nunit/nunit/issues/2154) Fix execution of non-parallel test fixtures -* [2157](https://github.com/nunit/nunit/issues/2157) Getting WorkerId inside Assert.Throws / DoesNotThrow returns null instead of previous non-null value +* [2157](https://github.com/nunit/nunit/issues/2157) Getting WorkerId inside Assert.Throws / DoesNotThrow returns null + instead of previous non-null value * [2158](https://github.com/nunit/nunit/issues/2158) Update SetupFixtureAttribute XML Docs * [2159](https://github.com/nunit/nunit/issues/2159) Prevent crash in .NET standard with log file path -* [2165](https://github.com/nunit/nunit/issues/2165) Trying to install NUnit 3.6.1 on .NET Framework asks for download of 20 more packages +* [2165](https://github.com/nunit/nunit/issues/2165) Trying to install NUnit 3.6.1 on .NET Framework asks for download + of 20 more packages * [2169](https://github.com/nunit/nunit/issues/2169) Incorrect xml docs for SetUpAttribute * [2170](https://github.com/nunit/nunit/issues/2170) Cake build fails if only Visual Studio 2017 installed * [2173](https://github.com/nunit/nunit/issues/2173) Remove PreTestAttribute and PostTestAttribute -* [2186](https://github.com/nunit/nunit/issues/2186) Replace special characters as part of converting branch names to package versions -* [2191](https://github.com/nunit/nunit/issues/2191) System.Reflection.TargetInvocationException with nunit3-console --debug on Mono +* [2186](https://github.com/nunit/nunit/issues/2186) Replace special characters as part of converting branch names to + package versions +* [2191](https://github.com/nunit/nunit/issues/2191) System.Reflection.TargetInvocationException with nunit3-console + --debug on Mono ## NUnit 3.6.1 - February 26, 2017 -This is a hotfix release of the framework that addresses critical issues found in -the 3.6 release. +This is a hotfix release of the framework that addresses critical issues found in the 3.6 release. ### Issues Resolved * [1962](https://github.com/nunit/nunit/issues/1962) A Theory with no data passes * [1986](https://github.com/nunit/nunit/issues/1986) NUnitLite ignores --workers option * [1994](https://github.com/nunit/nunit/issues/1994) NUnitLite runner crashing when --trace is specified -* [2017](https://github.com/nunit/nunit/issues/2017) Two NUnit project's tests fail on systems with comma decimal mark settings +* [2017](https://github.com/nunit/nunit/issues/2017) Two NUnit project's tests fail on systems with comma decimal mark + settings * [2043](https://github.com/nunit/nunit/issues/2043) Regression in 3.6.0 when catching AssertionException ## NUnit 3.6 - January 9, 2017 -This release of the framework no longer includes builds for Compact Framework or for SilverLight, but adds a .NET Standard 1.6 build. If anyone still using Compact Framework or SilverLight and would like to continue development on those versions of the framework, please contact the NUnit team. +This release of the framework no longer includes builds for Compact Framework or for SilverLight, but adds a .NET +Standard 1.6 build. If anyone still using Compact Framework or SilverLight and would like to continue development on +those versions of the framework, please contact the NUnit team. ### Framework @@ -844,7 +1135,8 @@ This release of the framework no longer includes builds for Compact Framework or * Improved assert error messages to help differentiate differences in values * Added warnings with Warn.If(), Warn.Unless() and Assert.Warn() * Enabled Path, File and Directory Asserts/Constraints for .NET Core testing -* Added NonTestAssemblyAttribute for use by third-party developers to indicate that their assemblies reference the NUnit framework, but do not contain tests +* Added NonTestAssemblyAttribute for use by third-party developers to indicate that their assemblies reference the NUnit + framework, but do not contain tests ### Issues Resolved @@ -856,7 +1148,8 @@ This release of the framework no longer includes builds for Compact Framework or * [1601](https://github.com/nunit/nunit/issues/1601) Move SilverLight to a separate project * [1609](https://github.com/nunit/nunit/issues/1609) Upgrade Cake build to latest version * [1661](https://github.com/nunit/nunit/issues/1661) Create .NET Standard Framework Build -* [1668](https://github.com/nunit/nunit/issues/1668) Need implementation-independent way to test number of items in a collection +* [1668](https://github.com/nunit/nunit/issues/1668) Need implementation-independent way to test number of items in a + collection * [1743](https://github.com/nunit/nunit/issues/1743) Provide multiple results for a test case in the XML output * [1758](https://github.com/nunit/nunit/issues/1758) No direct inverse for Contains.Key * [1765](https://github.com/nunit/nunit/issues/1765) TestCaseSourceAttribute constructor for method with parameters @@ -870,21 +1163,27 @@ This release of the framework no longer includes builds for Compact Framework or * [1836](https://github.com/nunit/nunit/issues/1836) Support nullable enums in Theories * [1837](https://github.com/nunit/nunit/issues/1837) [Request] AfterConstraint to support more readable usage * [1840](https://github.com/nunit/nunit/issues/1840) Remove SL and CF #Defined source -* [1866](https://github.com/nunit/nunit/issues/1866) [Request] More readable way to set polling interval in After constraint -* [1870](https://github.com/nunit/nunit/issues/1870) EqualConstraint result failure message for DateTime doesn't show sufficient resolution +* [1866](https://github.com/nunit/nunit/issues/1866) [Request] More readable way to set polling interval in After + constraint +* [1870](https://github.com/nunit/nunit/issues/1870) EqualConstraint result failure message for DateTime doesn't show + sufficient resolution * [1872](https://github.com/nunit/nunit/issues/1872) Parameterized method being called with no parameter * [1876](https://github.com/nunit/nunit/issues/1876) What should we do about Env.cs * [1880](https://github.com/nunit/nunit/issues/1880) AttributeUsage for various Attributes * [1889](https://github.com/nunit/nunit/issues/1889) Modify NUnitLite to display multiple assert information -* [1891](https://github.com/nunit/nunit/issues/1891) TestContext.Progress and TestContext.Error silently drop text that is not properly XML encoded -* [1901](https://github.com/nunit/nunit/issues/1901) Make NUnitLite-runner Prefer32Bit option consistent across Debug/Release +* [1891](https://github.com/nunit/nunit/issues/1891) TestContext.Progress and TestContext.Error silently drop text that + is not properly XML encoded +* [1901](https://github.com/nunit/nunit/issues/1901) Make NUnitLite-runner Prefer32Bit option consistent across + Debug/Release * [1904](https://github.com/nunit/nunit/issues/1904) Add .NET Standard 1.6 Dependencies to the Nuspec Files * [1907](https://github.com/nunit/nunit/issues/1907) Handle early termination of multiple assert block -* [1911](https://github.com/nunit/nunit/issues/1911) Changing misleading comment that implies that every `ICollection` is a list +* [1911](https://github.com/nunit/nunit/issues/1911) Changing misleading comment that implies that every + `ICollection` is a list * [1912](https://github.com/nunit/nunit/issues/1912) Add new warning status and result state * [1913](https://github.com/nunit/nunit/issues/1913) Report Warnings in NUnitLite * [1914](https://github.com/nunit/nunit/issues/1914) Extra AssertionResult entries in TestResults -* [1915](https://github.com/nunit/nunit/issues/1915) Enable Path, File and Directory Assert/Constraints in the .NET Standard Build +* [1915](https://github.com/nunit/nunit/issues/1915) Enable Path, File and Directory Assert/Constraints in the .NET + Standard Build * [1917](https://github.com/nunit/nunit/issues/1917) Use of IsolatedContext breaks tests in user-created AppDomain * [1924](https://github.com/nunit/nunit/issues/1924) Run tests using the NUnit Console Runner * [1929](https://github.com/nunit/nunit/issues/1929) Rename zip and remove source zip @@ -903,3 +1202,5 @@ This release of the framework no longer includes builds for Compact Framework or * Release Notes for [NUnit 2.5 through 2.5.10](https://nunit.org/?p=releaseNotes&r=2.5.10) * Release Notes for [NUnit 2.4 through 2.4.8](https://nunit.org/?p=releaseNotes&r=2.4.8) * Release Notes for [NUnit 2.0 through 2.2.10](https://nunit.org/?p=releaseNotes&r=2.2.10) + +[TeamLink]: https://docs.nunit.org/articles/developer-info/The-Teams.html#current-team-memberships-listed-in-a-kind-of-chronological-order diff --git a/docs/articles/nunit/running-tests/Console-Command-Line.md b/docs/articles/nunit/running-tests/Console-Command-Line.md index 636573000..a79a89b8d 100644 --- a/docs/articles/nunit/running-tests/Console-Command-Line.md +++ b/docs/articles/nunit/running-tests/Console-Command-Line.md @@ -10,23 +10,20 @@ The console interface runner is invoked by a command in the form NUNIT3-CONSOLE [inputfiles] [options] ``` -where **inputfiles** is one or more assemblies or test projects of -a type that NUnit can process and **options** is zero or more options. -Input files and options may be mixed in any order. +where **inputfiles** is one or more assemblies or test projects of a type that NUnit can process and **options** is zero +or more options. Input files and options may be mixed in any order. ## Input Files -The console program must always have an assembly or project specified. -Assemblies are specified by file name or path, which may be absolute or -relative. Relative paths are interpreted based on the current directory. +The console program must always have an assembly or project specified. Assemblies are specified by file name or path, +which may be absolute or relative. Relative paths are interpreted based on the current directory. -In addition to assemblies, you may specify any project type that is -understood by NUnit. Out of the box, this includes various -Visual Studio project types as well as NUnit (.nunit) test projects (see [NUnit Test Projects](xref:nunittestprojects) for a description of NUnit test projects). +In addition to assemblies, you may specify any project type that is understood by NUnit. Out of the box, this includes +various Visual Studio project types as well as NUnit (.nunit) test projects (see [NUnit Test +Projects](xref:nunittestprojects) for a description of NUnit test projects). -If the NUnit V2 framework driver is installed, test assemblies may -be run based on any version of the NUnit framework beginning with 2.0. -Without the V2 driver, only version 3.0 and higher tests may be run. +If the NUnit V2 framework driver is installed, test assemblies may be run based on any version of the NUnit framework +beginning with 2.0. Without the V2 driver, only version 3.0 and higher tests may be run. ## Options @@ -75,13 +72,10 @@ Without the V2 driver, only version 3.0 and higher tests may be run. ### Description -By default, this command runs the tests contained in the -assemblies and projects specified. If the **--explore** option -is used, no tests are executed but a description of the tests -is saved in the specified or default format. +By default, this command runs the tests contained in the assemblies and projects specified. If the **--explore** option +is used, no tests are executed but a description of the tests is saved in the specified or default format. -Several options that specify processing of XML output take -an output specification as a value. A SPEC may take one of +Several options that specify processing of XML output take an output specification as a value. A SPEC may take one of the following forms: * `--OPTION:filename` @@ -98,10 +92,8 @@ The --explore option may use any of the following formats: * nunit3 - the native XML format for NUnit 3 * cases - a text file listing the full names of all test cases. -If --explore is used without any specification following, a list of -test cases is output to the console. +If --explore is used without any specification following, a list of test cases is output to the console. -If neither --result nor --explore is used, -NUnit saves the results to TestResult.xml in nunit3 format. +If neither --result nor --explore is used, NUnit saves the results to TestResult.xml in nunit3 format. Any transforms provided must handle input in the native nunit3 format. diff --git a/docs/articles/nunit/running-tests/Console-Runner.md b/docs/articles/nunit/running-tests/Console-Runner.md index 405301144..aa8bc5bf8 100644 --- a/docs/articles/nunit/running-tests/Console-Runner.md +++ b/docs/articles/nunit/running-tests/Console-Runner.md @@ -1,20 +1,22 @@ # Console Runner -The nunit3-console.exe program is a text-based runner for listing and running -our tests from the command-line. It is able to run all NUnit 3.0 or higher tests natively and can run NUnit 2.x tests if the v2 driver is installed. +The nunit3-console.exe program is a text-based runner for listing and running our tests from the command-line. It is +able to run all NUnit 3.0 or higher tests natively and can run NUnit 2.x tests if the v2 driver is installed. -This runner is useful for automation of tests and integration into other systems. -It automatically saves its results in XML format, allowing you to produce reports or otherwise process the results. The following is a screenshot of the console program output. +This runner is useful for automation of tests and integration into other systems. It automatically saves its results in +XML format, allowing you to produce reports or otherwise process the results. The following is a screenshot of the +console program output. ![Screen shot of nunit-console](~/images/console-mock.png) -In this example, nunit3-console has just run selected tests in the mock-nunit-assembly.exe assembly that is part of the NUnit distribution. This assembly contains a number of tests, some -of which are either ignored or marked explicit. The summary line shows the -result of the test run. +In this example, nunit3-console has just run selected tests in the mock-nunit-assembly.exe assembly that is part of the +NUnit distribution. This assembly contains a number of tests, some of which are either ignored or marked explicit. The +summary line shows the result of the test run. ## Console Exit Codes -The console will exit with zero if all tests pass, a positive number if there are any test failures, and a negative number in the case of any errors in running the test suite. The current exit codes used are summarized below: +The console will exit with zero if all tests pass, a positive number if there are any test failures, and a negative +number in the case of any errors in running the test suite. The current exit codes used are summarized below: | Exit code | Meaning | |---|---| diff --git a/docs/articles/nunit/running-tests/Index.md b/docs/articles/nunit/running-tests/Index.md index 339be3af7..b397caade 100644 --- a/docs/articles/nunit/running-tests/Index.md +++ b/docs/articles/nunit/running-tests/Index.md @@ -4,19 +4,26 @@ uid: runningtests # Running Tests -There are several ways to run your tests, depending on your needs. -The most common way is to use one of the common IDEs, such as Visual Studio, Visual Studio Code or Rider, or to use `dotnet test` from the command line. All of these use different parts of the NUnit ecosystem to run your tests. The Microsoft tools use the NUnit3TestAdapter, whereas Jetbrains Rider use the NUnit.Engine. +There are several ways to run your tests, depending on your needs. The most common way is to use one of the common IDEs, +such as Visual Studio, Visual Studio Code or Rider, or to use `dotnet test` from the command line. All of these use +different parts of the NUnit ecosystem to run your tests. The Microsoft tools use the NUnit3TestAdapter, whereas +Jetbrains Rider use the NUnit.Engine. To start using NUnit with these tools, see the [Installation section](xref:installation). -Also see the information on the [NUnit3TestAdapter](https://docs.nunit.org/articles/vs-test-adapter/Index.html) for more detailed information on how to use it and configure it. +Also see the information on the [NUnit3TestAdapter](https://docs.nunit.org/articles/vs-test-adapter/Index.html) for more +detailed information on how to use it and configure it. -In addition to these NUnit provides two special runners, the NUnit.Console and the NUnitLite runners, which are described below. +In addition to these NUnit provides two special runners, the NUnit.Console and the NUnitLite runners, which are +described below. * The [Console Runner](Console-Runner.md), `nunit-console.exe`, is used for batch execution. -* The [NUnitLite runner](NUnitLite-Runner.md), `nunitlite-runner.exe`, is a light weight runner originally used internally in the team, but can be used by anyone who wants to have a simple way of running tests from the command line. +* The [NUnitLite runner](NUnitLite-Runner.md), `nunitlite-runner.exe`, is a light weight runner originally used + internally in the team, but can be used by anyone who wants to have a simple way of running tests from the command + line. -Just for fun, to see how the different runners are being used, we can look at the `nuget.org` download statistics for each of the runners, per Oct 2023: +Just for fun, to see how the different runners are being used, we can look at the `nuget.org` download statistics for +each of the runners, per Oct 2023: |Runner|Downloads|Comment| |------|---------|-------| @@ -26,21 +33,28 @@ Just for fun, to see how the different runners are being used, we can look at th ## Other runners -The `VSTest.Console` is also a Microsoft runner, but it is less used now as `dotnet test` has taken over. It does use the `NUnit3TestAdapter` as well. +The `VSTest.Console` is also a Microsoft runner, but it is less used now as `dotnet test` has taken over. It does use +the `NUnit3TestAdapter` as well. -The `Azure Pipelines` have some tasks for running tests, like [VSTest](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/vstest-v2?view=azure-pipelines), which also use the `NUnit3TestAdapter` under the hood. +The `Azure Pipelines` have some tasks for running tests, like +[VSTest](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/vstest-v2?view=azure-pipelines), which +also use the `NUnit3TestAdapter` under the hood. ## Some information on the internal working ### NUnit.Engine -All runners except NUnitLite use the NUnit.Engine, including Rider. -It should not be used alone, as the different runners have different requirements for how the engine is used and which version is being used. -See [Compatibility of the Test Adapter with the Test Engine](https://docs.nunit.org/articles/vs-test-adapter/Adapter-Engine-Compatibility.html) for some more detailed information on this. +All runners except NUnitLite use the NUnit.Engine, including Rider. It should not be used alone, as the different +runners have different requirements for how the engine is used and which version is being used. See [Compatibility of +the Test Adapter with the Test +Engine](https://docs.nunit.org/articles/vs-test-adapter/Adapter-Engine-Compatibility.html) for some more detailed +information on this. ### NUnit Agent -When running tests in a separate process, the console and gui runners make use of the NUnit Agent program, nunit-agent.exe. Although not directly run by users, nunit-agent does load and execute tests and users need to be aware of it, especially when debugging is involved. +When running tests in a separate process, the console and gui runners make use of the NUnit Agent program, +nunit-agent.exe. Although not directly run by users, nunit-agent does load and execute tests and users need to be aware +of it, especially when debugging is involved. ## Additional Information diff --git a/docs/articles/nunit/running-tests/NUnit-Test-Projects.md b/docs/articles/nunit/running-tests/NUnit-Test-Projects.md index 1b8a711d8..53d547070 100644 --- a/docs/articles/nunit/running-tests/NUnit-Test-Projects.md +++ b/docs/articles/nunit/running-tests/NUnit-Test-Projects.md @@ -4,9 +4,9 @@ uid: nunittestprojects # NUnit Test Projects -Although you may simply enter multiple assembly names on the console command-line, running tests from multiple assemblies is facilitated by the use of NUnit test projects. These are -files with the extension .nunit containing information about the assemblies to be loaded. The -following is an example of a hypothetical test project file: +Although you may simply enter multiple assembly names on the console command-line, running tests from multiple +assemblies is facilitated by the use of NUnit test projects. These are files with the extension .nunit containing +information about the assemblies to be loaded. The following is an example of a hypothetical test project file: ```xml @@ -22,15 +22,15 @@ following is an example of a hypothetical test project file: ``` -This project contains two configurations, each of which contains two assemblies. The Debug -configuration is currently active. By default, the assemblies will be loaded using the directory -containing this file as the ApplicationBase. The PrivateBinPath will be set automatically to -`LibraryCore\bin\Debug;LibraryUI\bin\Debug` or to the corresponding release path. -XML attributes are used to specify non-default values for the ApplicationBase, Configuration -File and PrivateBinPath. +This project contains two configurations, each of which contains two assemblies. The Debug configuration is currently +active. By default, the assemblies will be loaded using the directory containing this file as the ApplicationBase. The +PrivateBinPath will be set automatically to `LibraryCore\bin\Debug;LibraryUI\bin\Debug` or to the corresponding release +path. XML attributes are used to specify non-default values for the ApplicationBase, Configuration File and +PrivateBinPath. -The [Project Editor](https://github.com/nunit-legacy/nunit-project-editor/wiki/Project-Editor) may be used to create or modify NUnit projects. If you edit the XML manually, you should make sure to -use a path relative to the directory containing the project file as the location of any assemblies. +The [Project Editor](https://github.com/nunit-legacy/nunit-project-editor/wiki/Project-Editor) may be used to create or +modify NUnit projects. If you edit the XML manually, you should make sure to use a path relative to the directory +containing the project file as the location of any assemblies. For details, see [NUnit Project XML Format](xref:nunitprojectxmlformat) diff --git a/docs/articles/nunit/running-tests/NUnitLite-Runner.md b/docs/articles/nunit/running-tests/NUnitLite-Runner.md index 2f42cbcd1..d458cc7a2 100644 --- a/docs/articles/nunit/running-tests/NUnitLite-Runner.md +++ b/docs/articles/nunit/running-tests/NUnitLite-Runner.md @@ -4,16 +4,20 @@ 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. +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. -With NUnit 3.0, the NUnitLite framework has been merged with the full NUnit framework. There -is now only one framework, **nunit.framework.dll**. The built-in runner, which was a part of the old NUnitLite, is now packaged as **nunitlite.dll**. +With NUnit 3.0, the NUnitLite framework has been merged with the full NUnit framework. There is now only one framework, +**nunit.framework.dll**. The built-in runner, which was a part of the old NUnitLite, is now packaged as +**nunitlite.dll**. ## Using NUnitLite To run tests under NUnitLite, proceed as follows: -* Create a console application to use as your test assembly. If you have already placed tests in a dll, you can change the project so that it produces a console application and reload it. +* Create a console application to use as your test assembly. If you have already placed tests in a dll, you can change + the project so that it produces a console application and reload it. * Make sure your test assembly references both **nunit.framework** and **nunitlite**. @@ -28,8 +32,8 @@ public static int Main(string[] args) * Execute your test application in order to run the tests. -If you install the NUnitLite runner via the NuGet package, steps 2 is handled -automatically. Both assemblies are installed and referenced for you. +If you install the NUnitLite runner via the NuGet package, steps 2 is handled automatically. Both assemblies are +installed and referenced for you. ## NUnitLite Output diff --git a/docs/articles/nunit/running-tests/Template-Based-Test-Naming.md b/docs/articles/nunit/running-tests/Template-Based-Test-Naming.md index a0b59a7ab..c7835f256 100644 --- a/docs/articles/nunit/running-tests/Template-Based-Test-Naming.md +++ b/docs/articles/nunit/running-tests/Template-Based-Test-Naming.md @@ -4,45 +4,58 @@ uid: templatebasedtestnaming # Template-Based Test Naming -NUnit uses a standard naming convention for all tests, which in the language described below corresponds to `{m}{a}`. The most used runners, Visual Studio and dotnet depends on this being the default, and trying to change this will cause display issues in these runners. +NUnit uses a standard naming convention for all tests, which in the language described below corresponds to `{m}{a}`. +The most used runners, Visual Studio and dotnet depends on this being the default, and trying to change this will cause +display issues in these runners. **We strongly recommend you to NOT change the test naming.** ## If you still want to do it -However, if you're out on your own, the naming *can* be overridden by the user if required. TestName generation is driven by a name formatting string, which may contain any of the following format specifiers: +However, if you're out on your own, the naming *can* be overridden by the user if required. TestName generation is +driven by a name formatting string, which may contain any of the following format specifiers: * `{n}` The namespace of the test or empty if there is no namespace. If empty, any immediately following '.' is ignored. -* `{c}` The class name of the test or empty if there is no class. This name includes any type arguments, enclosed in angle braces and separated by commas. +* `{c}` The class name of the test or empty if there is no class. This name includes any type arguments, enclosed in + angle braces and separated by commas. * `{C}` The full name of the class. Equivalent to `{n}.{c}` -* `{m}` The method name of the test or empty if there is no method. The name includes any type arguments, enclosed in angle braces and separated by commas. +* `{m}` The method name of the test or empty if there is no method. The name includes any type arguments, enclosed in + angle braces and separated by commas. * `{M}` The full name of the method. -* `{a}` The full argument representation, enclosed in parentheses and separated by commas. Each argument is represented by the standard NUnit format for certain types, otherwise by the result of ToString(). +* `{a}` The full argument representation, enclosed in parentheses and separated by commas. Each argument is represented + by the standard NUnit format for certain types, otherwise by the result of ToString(). -* `{p}` Same as `{a}` but with a parameter name before each argument in the same style as the [*named arguments* C# language feature](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#named-arguments). +* `{p}` Same as `{a}` but with a parameter name before each argument in the same style as the [*named arguments* C# + language + feature](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#named-arguments). -* `{0}`, `{1}`...`{9}`. An individual argument. This form is only useful when setting the name of an individual test case. If used in the default format string, any arguments not used will be ignored. +* `{0}`, `{1}`...`{9}`. An individual argument. This form is only useful when setting the name of an individual test + case. If used in the default format string, any arguments not used will be ignored. * `{i}` The test id, which is normally of the form mmm-nnn. * Any text not included between curly braces is copied to the name as is. -After the name is formatted, any leading or trailing '.' characters are removed. Otherwise, all non-format characters in the string are included as is. +After the name is formatted, any leading or trailing '.' characters are removed. Otherwise, all non-format characters in +the string are included as is. -String arguments may be truncated to a maximum length. Either the {a} specifier or any of the individual argument specifiers may be followed by a colon and a length: +String arguments may be truncated to a maximum length. Either the {a} specifier or any of the individual argument +specifiers may be followed by a colon and a length: -* `{a:40}` Truncate **each string argument** to 40 characters. All strings more than 37 characters are truncated to the first 37 followed by "..." +* `{a:40}` Truncate **each string argument** to 40 characters. All strings more than 37 characters are truncated to the + first 37 followed by "..." * `{0:20}` Truncate argument zero to 20 characters. ## Standard Name Formats -Internally, NUnit uses certain standard formats unless overridden by the user. The standard format for generating a name from a test method and its arguments is: +Internally, NUnit uses certain standard formats unless overridden by the user. The standard format for generating a name +from a test method and its arguments is: ```text {m}{a} // Name @@ -59,9 +72,12 @@ This leads to test names like: ## Modifying the Name Format -The `SetName` method of `TestCaseData` allows setting the name of an individual test case. In normal use, the provided string simply becomes the name of the test. +The `SetName` method of `TestCaseData` allows setting the name of an individual test case. In normal use, the provided +string simply becomes the name of the test. -However, if one of the template format specifiers is used in the argument to `SetName`, the name is regenerated using that format. For example, if the user wishes to specify only the argument portion of the name of a test method, while still retaining the method name, the name could be set to +However, if one of the template format specifiers is used in the argument to `SetName`, the name is regenerated using +that format. For example, if the user wishes to specify only the argument portion of the name of a test method, while +still retaining the method name, the name could be set to ```text {m}(User argument) @@ -73,4 +89,5 @@ This would result in the display of the test name as SomeMethod(User Argument) ``` -Note that in this usage, it will generally only make sense to use `{m}`, `{a}` or `{0}` through `{9}` specifiers. However, NUnit will use whatever is provided. +Note that in this usage, it will generally only make sense to use `{m}`, `{a}` or `{0}` through `{9}` specifiers. +However, NUnit will use whatever is provided. diff --git a/docs/articles/nunit/running-tests/Test-Selection-Language.md b/docs/articles/nunit/running-tests/Test-Selection-Language.md index d8edd9a96..c56bc25d8 100644 --- a/docs/articles/nunit/running-tests/Test-Selection-Language.md +++ b/docs/articles/nunit/running-tests/Test-Selection-Language.md @@ -4,11 +4,17 @@ uid: testselectionlanguage # Test Selection Language -The console command-line allows you to specify a filter, which will select which tests are executed. This is done using the --where option, followed by an expression in NUnit's Test Selection Language (TSL), a simple domain-specific language designed for this purpose. +The console command-line allows you to specify a filter, which will select which tests are executed. This is done using +the --where option, followed by an expression in NUnit's Test Selection Language (TSL), a simple domain-specific +language designed for this purpose. -The --where option can be used with the `dotnet test` as `-- NUnit.Where` (note the space after the --). This will inject this into the runsettings. You can also add the same to a `.runsettings` file, see [Adapter options](https://docs.nunit.org/articles/vs-test-adapter/Tips-And-Tricks.html) and [this blog post](https://blog.prokrams.com/2019/12/16/nunit3-filter-dotnet/). +The --where option can be used with the `dotnet test` as `-- NUnit.Where` (note the space after the --). This will +inject this into the runsettings. You can also add the same to a `.runsettings` file, see [Adapter +options](https://docs.nunit.org/articles/vs-test-adapter/Tips-And-Tricks.html) and [this blog +post](https://blog.prokrams.com/2019/12/16/nunit3-filter-dotnet/). -Some of the characters used in the expression, such as space, | or &, may have a special meaning when entered on the command-line. In such a case, you should place the expression in quotation marks. +Some of the characters used in the expression, such as space, | or &, may have a special meaning when entered on the +command-line. In such a case, you should place the expression in quotation marks. ```cmd dotnet test -- NUnit.Where="cat == Urgent or Priority == High" @@ -18,7 +24,8 @@ Some of the characters used in the expression, such as space, | or &, may have a ## Simple Expressions -Simple Expressions are essentially comparisons, consisting of a key word or property name on the left-hand side, an operator and some constant value on the right-hand side. Here are some examples: +Simple Expressions are essentially comparisons, consisting of a key word or property name on the left-hand side, an +operator and some constant value on the right-hand side. Here are some examples: ```text cat == Data @@ -38,7 +45,8 @@ The following key words are recognized on the left-hand side of the comparison: * `method` - The name of the method, e.g. TestMethod * `cat` - A category assigned to the test, e.g. SmokeTests -If the left-hand side of the comparison does not consist of a key word, it is treated as the name of a property on the test whose value is to be checked. See below for restrictions on use of properties. +If the left-hand side of the comparison does not consist of a key word, it is treated as the name of a property on the +test whose value is to be checked. See below for restrictions on use of properties. The following operators are supported @@ -47,7 +55,11 @@ The following operators are supported * `=~` to match a regular expression * `!~` to not match a regular expression -The right-hand side of the comparison may be a sequence of non-blank, non-special characters or a quoted string. Quoted strings may be surrounded by single quotes (`'`), double quotes (`"`) or slashes (`/`) and may contain any character except the quote character used to delimit them. If it is necessary to include the quote character in the string, it may be escaped using a backslash (\) as may the backslash itself should you need to include one. The following expressions all do the same thing: +The right-hand side of the comparison may be a sequence of non-blank, non-special characters or a quoted string. Quoted +strings may be surrounded by single quotes (`'`), double quotes (`"`) or slashes (`/`) and may contain any character +except the quote character used to delimit them. If it is necessary to include the quote character in the string, it may +be escaped using a backslash (\) as may the backslash itself should you need to include one. The following expressions +all do the same thing: ```text test =~ /TestCaseAttributeTest/ @@ -57,19 +69,28 @@ The right-hand side of the comparison may be a sequence of non-blank, non-specia test=~TestCaseAttributeTest ``` -For matching regular expressions, NUnit uses .NET's `Regex.IsMatch` method. For detailed information on the syntax of regular expressions in .NET, see [Regular Expressions in .NET](https://docs.microsoft.com/dotnet/standard/base-types/regular-expression-language-quick-reference). +For matching regular expressions, NUnit uses .NET's `Regex.IsMatch` method. For detailed information on the syntax of +regular expressions in .NET, see [Regular Expressions in +.NET](https://docs.microsoft.com/dotnet/standard/base-types/regular-expression-language-quick-reference). -For specifying qualified names, the same format as used for reflection should be used. For example `My.Name.Space.TestFixture+NestedFixture` can be used to select a nested fixture. For detailed information see: [Specifying Special Characters](https://learn.microsoft.com/en-us/dotnet/framework/reflection-and-codedom/specifying-fully-qualified-type-names#specifying-special-characters) +For specifying qualified names, the same format as used for reflection should be used. For example +`My.Name.Space.TestFixture+NestedFixture` can be used to select a nested fixture. For detailed information see: +[Specifying Special +Characters](https://learn.microsoft.com/en-us/dotnet/framework/reflection-and-codedom/specifying-fully-qualified-type-names#specifying-special-characters) ## Filtering By Namespace -Using the `namespace` keyword with `==` will _not_ match on sub-namespaces. For example by using the filter `namespace == My.Name.Space`, a test `My.Name.Space.MyFixture` will be selected but a test `My.Name.Space.SubNamespace.MyFixture` will not, since its namespace is not __equal__ to the namespace provided. +Using the `namespace` keyword with `==` will _not_ match on sub-namespaces. For example by using the filter `namespace +== My.Name.Space`, a test `My.Name.Space.MyFixture` will be selected but a test `My.Name.Space.SubNamespace.MyFixture` +will not, since its namespace is not __equal__ to the namespace provided. -In order to inclusively select namespaces, a regular expression can be used. For example to match _all_ namespaces under the root namespace `My.Name.Space`, the following filter can be used `namespace =~ ^My\.Name\.Space($|\.)` +In order to inclusively select namespaces, a regular expression can be used. For example to match _all_ namespaces under +the root namespace `My.Name.Space`, the following filter can be used `namespace =~ ^My\.Name\.Space($|\.)` ## Filtering Based on Properties -Although the syntax will accept any property name - including names that don't actually exist - filtering will only work on existing, string-valued properties. The following properties are created by NUnit and have string values: +Although the syntax will accept any property name - including names that don't actually exist - filtering will only work +on existing, string-valued properties. The following properties are created by NUnit and have string values: * Author * Category @@ -79,19 +100,30 @@ Although the syntax will accept any property name - including names that don't a * TestOf * IgnoreUntilDate -In general, these properties were not created with filtering in mind, but you can use them if it suits your needs. Using the Category property currently accomplishes the same thing as the cat keyword. You should be aware that the use of these properties by NUnit is considered an implementation detail and they may change in the future. +In general, these properties were not created with filtering in mind, but you can use them if it suits your needs. Using +the Category property currently accomplishes the same thing as the cat keyword. You should be aware that the use of +these properties by NUnit is considered an implementation detail and they may change in the future. -We envision that most filtering by property will be based on user-defined properties, created for this purpose by inheriting from [Property Attribute](xref:propertyattribute). When defining a property, you should keep the limitation to string values in mind. For example, a PriorityAttribute taking values of "High", "Medium" and "Low" could be used for filtering, while one that took the integers 1, 2 and 3 could not. +We envision that most filtering by property will be based on user-defined properties, created for this purpose by +inheriting from [Property Attribute](xref:propertyattribute). When defining a property, you should keep the limitation +to string values in mind. For example, a PriorityAttribute taking values of "High", "Medium" and "Low" could be used for +filtering, while one that took the integers 1, 2 and 3 could not. ## Filtering by Test Id -In addition to the left-hand-side items listed, NUnit supports filtering by the test id through the `id` keyword. The id may only be selected using the `==` operator and is intended only for use by programs that have explored the tests and cached the ids, not for general use by users. The reason for this restriction is that users have no way of predicting the id that will be assigned to a test. The id is not persistent across test runs and its format can differ between different framework drivers. +In addition to the left-hand-side items listed, NUnit supports filtering by the test id through the `id` keyword. The id +may only be selected using the `==` operator and is intended only for use by programs that have explored the tests and +cached the ids, not for general use by users. The reason for this restriction is that users have no way of predicting +the id that will be assigned to a test. The id is not persistent across test runs and its format can differ between +different framework drivers. ## Compound Expressions Simple expressions may be combined using logical and, logical or, parentheses or negation operators. -Logical and is expressed as `&&`, `&` or `and`. Logical or is expressed as `||`, `|`, or `or`. The negation operator is `!` and may only appear before a left parenthesis. The letter variants, `and` and `or`, are provided for use on the command-line in systems that give `&` and `|` a special meaning. +Logical and is expressed as `&&`, `&` or `and`. Logical or is expressed as `||`, `|`, or `or`. The negation operator is +`!` and may only appear before a left parenthesis. The letter variants, `and` and `or`, are provided for use on the +command-line in systems that give `&` and `|` a special meaning. The following are valid compound expressions: @@ -104,7 +136,9 @@ The following are valid compound expressions: ## Usage on the Command Line -Because TSL contains special characters and may contain blank spaces, you will usually want to put the expression in quotes on the command line. Consequently, any strings within the TSL expression will most likely need to use an alternate quote character. For example: +Because TSL contains special characters and may contain blank spaces, you will usually want to put the expression in +quotes on the command line. Consequently, any strings within the TSL expression will most likely need to use an +alternate quote character. For example: ```cmd nunit-console test.dll --where "method =~ /Source.*Test/ && class =~ 'My.Namespace.Classname'" @@ -112,6 +146,9 @@ Because TSL contains special characters and may contain blank spaces, you will u ## Support in NUnit V2 -The driver for NUnit V2 supports a subset of TSL. Because the V2 NUnit framework only allowed filtering on test names and categories, you may only use the `cat` and `test` keywords in comparisons. In addition, the regular expression operators `=~` and `!~` are not supported. +The driver for NUnit V2 supports a subset of TSL. Because the V2 NUnit framework only allowed filtering on test names +and categories, you may only use the `cat` and `test` keywords in comparisons. In addition, the regular expression +operators `=~` and `!~` are not supported. -If you use any of the unsupported keywords or operators with V2 tests, an error message is displayed and the tests are not run. +If you use any of the unsupported keywords or operators with V2 tests, an error message is displayed and the tests are +not run. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/Active-Attributes.md b/docs/articles/nunit/technical-notes/nunit-internals/Active-Attributes.md index d56cd2922..ad81af86a 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/Active-Attributes.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/Active-Attributes.md @@ -3,48 +3,66 @@ > [!WARNING] > Out Of Date - Needs Rewrite -NUnit identifies tests and fixtures of custom attributes. Additional attributes -are used to identify test data, modify tests and control how they execute. -NUnit 3.0 is changing how attributes are used and recognized internally, while -maintaining the same API for the test writer. This specification describes how -the new version will recognize and use attributes, the interfaces implemented -by attributes and the class hierarchy of NUnit's custom attributes. +NUnit identifies tests and fixtures of custom attributes. Additional attributes are used to identify test data, modify +tests and control how they execute. NUnit 3.0 is changing how attributes are used and recognized internally, while +maintaining the same API for the test writer. This specification describes how the new version will recognize and use +attributes, the interfaces implemented by attributes and the class hierarchy of NUnit's custom attributes. ## Rationale -In the NUnit 2.x releases, attributes are recognized by the text of their name -rather than using the attribute Type. This means that there is no need or the -runner to have an actual reference to the nunit.framework assembly, where -attributes are defined. This approach was taken in order to support multiple -versions of the framework. Each new release of NUnit was able to run tests -built against older frameworks, so long as the names remained the same. +In the NUnit 2.x releases, attributes are recognized by the text of their name rather than using the attribute Type. +This means that there is no need or the runner to have an actual reference to the nunit.framework assembly, where +attributes are defined. This approach was taken in order to support multiple versions of the framework. Each new release +of NUnit was able to run tests built against older frameworks, so long as the names remained the same. However, this approach has some drawbacks: -* As new attributes were added to the framework, it became necessary to also add the name of each attribute to the nunit core, which contained the code to load and run tests. The growing number of attributes in the framework now presents and extremely large surface area for the core to be aware of. -* Inheritance from attributes does not work as users would expect with NUnit failing to automatically recognize those attributes as equivalent to their base classes. In a few cases, NUnit contains special code to scan the base classes of any attributes found but it is not easy for users to discover which attributes allow this. -* NUnit must examine all attributes of a given class or method, comparing their names with the names it understands. This is quite inefficient and can slow down loading of assemblies containing large numbers of classes or methods. +* As new attributes were added to the framework, it became necessary to also add the name of each attribute to the nunit + core, which contained the code to load and run tests. The growing number of attributes in the framework now presents + and extremely large surface area for the core to be aware of. +* Inheritance from attributes does not work as users would expect with NUnit failing to automatically recognize those + attributes as equivalent to their base classes. In a few cases, NUnit contains special code to scan the base classes + of any attributes found but it is not easy for users to discover which attributes allow this. +* NUnit must examine all attributes of a given class or method, comparing their names with the names it understands. + This is quite inefficient and can slow down loading of assemblies containing large numbers of classes or methods. -By locating the code to load and run tests in the framework assembly, NUnit 3.0 eliminates the first problem above. Test runners now need only be aware of a much narrower API. The design section below describes how we are handling the second and third issues. +By locating the code to load and run tests in the framework assembly, NUnit 3.0 eliminates the first problem above. Test +runners now need only be aware of a much narrower API. The design section below describes how we are handling the second +and third issues. ## Design -With NUnit 3.0, attributes are now only used within the framework assembly. Since all references are within that assembly, we can now handle them as Types rather than strings. All existing code that uses attribute names will be modified to use Type references, improving efficiency and allowing use of standard object-oriented programming techniques. The following sections provide an outline of the planned design. As implementation progresses, the code itself should be examined for updated information and further details. +With NUnit 3.0, attributes are now only used within the framework assembly. Since all references are within that +assembly, we can now handle them as Types rather than strings. All existing code that uses attribute names will be +modified to use Type references, improving efficiency and allowing use of standard object-oriented programming +techniques. The following sections provide an outline of the planned design. As implementation progresses, the code +itself should be examined for updated information and further details. ## Active Attributes -NUnit has a relatively small number of test types (e.g. TestFixture, TestMethod, Theory) and a relatively larger number of attributes. The current (2.x) design uses attributes almost exclusively as passive containers for their arguments and properties. All active code around attributes is located in the code around loading and running tests. +NUnit has a relatively small number of test types (e.g. TestFixture, TestMethod, Theory) and a relatively larger number +of attributes. The current (2.x) design uses attributes almost exclusively as passive containers for their arguments and +properties. All active code around attributes is located in the code around loading and running tests. -In almost all cases, it is possible to reverse this logic and have the attributes play an active part in modifying the operation of tests. For example, the NUnit 2.6 test building logic understands that a test description may be found as a property of a DescriptionAttribute, TestAttribute or TestFixtureAttribute. In NUnit 3.0, each of those attributes will simply be called upon to update the test under construction with whatever information they can supply using the **IApplyToTest** interface. +In almost all cases, it is possible to reverse this logic and have the attributes play an active part in modifying the +operation of tests. For example, the NUnit 2.6 test building logic understands that a test description may be found as a +property of a DescriptionAttribute, TestAttribute or TestFixtureAttribute. In NUnit 3.0, each of those attributes will +simply be called upon to update the test under construction with whatever information they can supply using the +**IApplyToTest** interface. ## Attribute Hierarchy -With just a few exceptions, NUnit's current set of attributes inherit from System.Attribute directly. Since we are now switching to use of the standard .NET reflection mechanism via -attribute Types, it is useful to categorize attributes according to how and when they are used. +With just a few exceptions, NUnit's current set of attributes inherit from System.Attribute directly. Since we are now +switching to use of the standard .NET reflection mechanism via attribute Types, it is useful to categorize attributes +according to how and when they are used. -For example, at a certain point in the construction of tests, NUnit must scan the attributes on a method to apply all those that provide modifications to the test being built. This is currently done by looking at **all** attributes of the method but it will be much more convenient to only retrieve TestModificationAttributes. +For example, at a certain point in the construction of tests, NUnit must scan the attributes on a method to apply all +those that provide modifications to the test being built. This is currently done by looking at **all** attributes of the +method but it will be much more convenient to only retrieve TestModificationAttributes. -The top levels of the Attribute hierarchy are listed here to the extent that they have been thought out. This will change as we implement it and will not necessarily remain stable in future releases because the hierarchy is considered to be an internal implementation detail. +The top levels of the Attribute hierarchy are listed here to the extent that they have been thought out. This will +change as we implement it and will not necessarily remain stable in future releases because the hierarchy is considered +to be an internal implementation detail. * NUnitAttribute * TestIdentificationAttribute @@ -57,7 +75,10 @@ The top levels of the Attribute hierarchy are listed here to the extent that the ### Interface Usage -While class inheritance of attributes is useful for retrieving groups of them and for sharing implementation, public access to capabilities of an attribute is better provided through an interface. For example, most TestModificationAttributes will implement the **IApplyToTest** interface, allowing them to be called upon to modify the test under construction. +While class inheritance of attributes is useful for retrieving groups of them and for sharing implementation, public +access to capabilities of an attribute is better provided through an interface. For example, most +TestModificationAttributes will implement the **IApplyToTest** interface, allowing them to be called upon to modify the +test under construction. ```csharp public interface IApplyToTest @@ -70,17 +91,29 @@ Interfaces are defined in the NUnit.Framework.Api namespace. ### Properties Versus Separate Attributes -In some cases, there is a design choice to be made between use of a separate attribute or a property of the primary attribute for holding a particular of information. For example, the description of a test may be given as a property of TestAttribute or using a separate DescriptionAttribute. Recent versions of NUnit have deprecated use of properties in favor of separate attributes. Separate attributes provide a more orthogonal design and have been preferred for that reason. +In some cases, there is a design choice to be made between use of a separate attribute or a property of the primary +attribute for holding a particular of information. For example, the description of a test may be given as a property of +TestAttribute or using a separate DescriptionAttribute. Recent versions of NUnit have deprecated use of properties in +favor of separate attributes. Separate attributes provide a more orthogonal design and have been preferred for that +reason. -However, the introduction of parameterized tests has necessitated adding properties to the TestCaseAttribute and other attributes, representing functionality that was provided by a separate attribute on non-parameterized tests. For example, a test is ignored using the IgnoreAttribute while a TestCase is ignored by setting the Ignore property of TestCaseAttribute to true. +However, the introduction of parameterized tests has necessitated adding properties to the TestCaseAttribute and other +attributes, representing functionality that was provided by a separate attribute on non-parameterized tests. For +example, a test is ignored using the IgnoreAttribute while a TestCase is ignored by setting the Ignore property of +TestCaseAttribute to true. -For NUnit 3.0, we will try to provide some consistency of use for cases like this. This may result in "un-deprecating" certain existing properties and creating new ones. +For NUnit 3.0, we will try to provide some consistency of use for cases like this. This may result in "un-deprecating" +certain existing properties and creating new ones. ### Attribute Targets -NUnit will continue to rely on the AttributeUsageAttribute being properly defined on each of its attributes. This allows us to use one attribute type for both methods and classes while still counting on a given attribute only appearing in the proper context. +NUnit will continue to rely on the AttributeUsageAttribute being properly defined on each of its attributes. This allows +us to use one attribute type for both methods and classes while still counting on a given attribute only appearing in +the proper context. ## Unresolved Issues -One problem that is created by the new approach is that NUnit will no longer "just work" with -tests compiled against framework versions prior to 3.0. This requires the NUnit test execution engine to use the old approach when dealing with tests compiled against a pre-3.0 framework version. This specification does not cover the execution engine, so the problem is not discussed further here. +One problem that is created by the new approach is that NUnit will no longer "just work" with tests compiled against +framework versions prior to 3.0. This requires the NUnit test execution engine to use the old approach when dealing with +tests compiled against a pre-3.0 framework version. This specification does not cover the execution engine, so the +problem is not discussed further here. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/Architectural-Overview.md b/docs/articles/nunit/technical-notes/nunit-internals/Architectural-Overview.md index c02559539..8eff45656 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/Architectural-Overview.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/Architectural-Overview.md @@ -3,7 +3,8 @@ > [!WARNING] > This is a draft. The contents may be out of date. -This specification describes the overall layered architecture of the NUnit Platform. Details of individual components are covered only as they are relevant to the overall architecture. +This specification describes the overall layered architecture of the NUnit Platform. Details of individual components +are covered only as they are relevant to the overall architecture. ## Layers @@ -15,41 +16,70 @@ The basic architecture of the NUnit Extended testing platform consists of three The layering can be seen in the diagram below. -> This is the original architectural document, which is a bit out of date with regard to some details. A replacement is being created. +> This is the original architectural document, which is a bit out of date with regard to some details. A replacement is +> being created. ![topology](~/images/nunit-xtp-2008.png) ### Test Runner Layer -The Test Runner or UI layer contains various runners, some provided by the NUnit team, others by independent projects leveraging the NUnit platform. Some runners are stand-alone programs, while others are tasks or plugins running under the control of an IDE or other application. This diversity of runners is part of the reason we refer to NUnit 3.0 as a Testing Platform – we expect many different runners to come into existence and will facilitate their development by providing reusable controls for several key environments. +The Test Runner or UI layer contains various runners, some provided by the NUnit team, others by independent projects +leveraging the NUnit platform. Some runners are stand-alone programs, while others are tasks or plugins running under +the control of an IDE or other application. This diversity of runners is part of the reason we refer to NUnit 3.0 as a +Testing Platform – we expect many different runners to come into existence and will facilitate their development by +providing reusable controls for several key environments. -Programs in this layer are able to participate in the NUnit platform plugin architecture, providing extension points that allow them to be extended. Plugins at this level will usually add some functionality to the UI. Some of them may be standalone while others may require the presence of specific test engine plugins in order to operate. +Programs in this layer are able to participate in the NUnit platform plugin architecture, providing extension points +that allow them to be extended. Plugins at this level will usually add some functionality to the UI. Some of them may be +standalone while others may require the presence of specific test engine plugins in order to operate. -The NUnit project will continue to provide both a console runner and a WinForms-based GUI with extended capabilities those in NUnit 2.6. In addition, two new GUI runners will be developed, one based on WPF, the other on GTK#. +The NUnit project will continue to provide both a console runner and a WinForms-based GUI with extended capabilities +those in NUnit 2.6. In addition, two new GUI runners will be developed, one based on WPF, the other on GTK#. -We’ll work with the NAnt project to provide updates to the NAnt task for use with NUnit 3.0, with the goal of keeping that task current as new versions of NUnit are released. We will provide an NUnit plugin for the new Gallio platform. +We’ll work with the NAnt project to provide updates to the NAnt task for use with NUnit 3.0, with the goal of keeping +that task current as new versions of NUnit are released. We will provide an NUnit plugin for the new Gallio platform. -In the area of IDE integration, we will deliver a Visual Studio addin or package for running NUnit tests. Since other folks are already providing open source plugins for SharpDevelop and MonoDevelop, we’ll work with them to ensure compatibility. +In the area of IDE integration, we will deliver a Visual Studio addin or package for running NUnit tests. Since other +folks are already providing open source plugins for SharpDevelop and MonoDevelop, we’ll work with them to ensure +compatibility. -There is a long-standing need for a runner that executes tests in an actual or simulated web server environment. While good practice calls for extracting as much functionality as possible into separately testable assemblies, more complex applications often contain code which can only be tested in such an environment. For that reason, NUnit 3.0 will feature a web runner, which allows tests to be executed on a web server, reporting results back to the desktop. +There is a long-standing need for a runner that executes tests in an actual or simulated web server environment. While +good practice calls for extracting as much functionality as possible into separately testable assemblies, more complex +applications often contain code which can only be tested in such an environment. For that reason, NUnit 3.0 will feature +a web runner, which allows tests to be executed on a web server, reporting results back to the desktop. -Each of the runners will have the option of participating in the NUnit plugin architecture and using functionality provided by NUnit to whatever degree desired. For the runners developed directly by the NUnit team, this capability will be used to the max, allowing others to add GUI features that function by themselves or in conjunction with other plugins operating at the level of the test engine. +Each of the runners will have the option of participating in the NUnit plugin architecture and using functionality +provided by NUnit to whatever degree desired. For the runners developed directly by the NUnit team, this capability will +be used to the max, allowing others to add GUI features that function by themselves or in conjunction with other plugins +operating at the level of the test engine. ### Test Engine Layer -The Test Engine Layer is the core of the NUnit platform. It provides a public API for use by applications that want to locate, load and run tests and display test results. Many aspects of the Test Engine are already present in NUnit 2.6, while others are new. I’ll focus on the new features here. +The Test Engine Layer is the core of the NUnit platform. It provides a public API for use by applications that want to +locate, load and run tests and display test results. Many aspects of the Test Engine are already present in NUnit 2.6, +while others are new. I’ll focus on the new features here. -NUnit 2.6 already supports running tests in a separate process, allowing selection of the CLR version under which the test is to be run. NUnit 3.0 will extend this feature to allow test processes to run on other machines. It will also support distribution of test execution across a network of remote Test Agents. This facility is intended to be used in several distinct scenarios: +NUnit 2.6 already supports running tests in a separate process, allowing selection of the CLR version under which the +test is to be run. NUnit 3.0 will extend this feature to allow test processes to run on other machines. It will also +support distribution of test execution across a network of remote Test Agents. This facility is intended to be used in +several distinct scenarios: * Simple load sharing when test execution time is excessive * Testing applications on multiple platforms * Testing applications, which are themselves distributed -A great deal of distributed function is already present in NUnit 2.6 through pNUnit, the distributed testing runner contributed to our project by Codice Software. With NUnit 3.0, we plan to integrate this function more completely into NUnit, allowing them to be executed by any runner that uses the NUnit Test Engine. +A great deal of distributed function is already present in NUnit 2.6 through pNUnit, the distributed testing runner +contributed to our project by Codice Software. With NUnit 3.0, we plan to integrate this function more completely into +NUnit, allowing them to be executed by any runner that uses the NUnit Test Engine. -NUnit will support performance and coverage analysis, test result reporting and maintenance of a history of test results. These features will function only as called upon by the user. That is, we will not carry on data collection activities with the potential of impacting performance when the user simply wants to run tests. +NUnit will support performance and coverage analysis, test result reporting and maintenance of a history of test +results. These features will function only as called upon by the user. That is, we will not carry on data collection +activities with the potential of impacting performance when the user simply wants to run tests. -Through use of plugins, NUnit will be able to support a wide variety of test types beyond low-level, isolated programmer tests. What is available in this area will be dependent on the interests of users and their willingness to contribute their efforts to creating them. Examples of the kinds of things we envision, some of which we will provide directly, are: +Through use of plugins, NUnit will be able to support a wide variety of test types beyond low-level, isolated programmer +tests. What is available in this area will be dependent on the interests of users and their willingness to contribute +their efforts to creating them. Examples of the kinds of things we envision, some of which we will provide directly, +are: * Randomization of test execution order * Deterministic test ordering for integration tests @@ -63,20 +93,40 @@ Through use of plugins, NUnit will be able to support a wide variety of test typ ### Framework Layer -In NUnit 3.0, the NUnit framework itself – the assembly that is referenced by user tests – will be split along two dimensions. First, there will be separate framework assemblies for different version levels of the Common Language Runtime. By splitting the framework in this way, we will be able to take advantage of newer features, and allow users to take advantage of them, without compromising basic support for older runtimes. +In NUnit 3.0, the NUnit framework itself – the assembly that is referenced by user tests – will be split along two +dimensions. First, there will be separate framework assemblies for different version levels of the Common Language +Runtime. By splitting the framework in this way, we will be able to take advantage of newer features, and allow users to +take advantage of them, without compromising basic support for older runtimes. -The second split we plan is between the core framework capabilities and the syntactic features that make it easy to access those features. A key example of this is the fluent interface introduced in NUnit 2.4 – the “Assert.That” syntax. One thing we learned through that experiment is that the same syntactic “sugar” does not work well for different language environments. Many of the 2.4/2.5/2.6 constructs are unusable or very difficult to use in other languages – C++ for example. By a combination of separate namespaces and separate assemblies, we will allow users to select the appropriate syntax for the work they are doing. Other people will be able to build on the syntax we provide or create entirely new syntactic overlays for their own purposes. +The second split we plan is between the core framework capabilities and the syntactic features that make it easy to +access those features. A key example of this is the fluent interface introduced in NUnit 2.4 – the “Assert.That” syntax. +One thing we learned through that experiment is that the same syntactic “sugar” does not work well for different +language environments. Many of the 2.4/2.5/2.6 constructs are unusable or very difficult to use in other languages – C++ +for example. By a combination of separate namespaces and separate assemblies, we will allow users to select the +appropriate syntax for the work they are doing. Other people will be able to build on the syntax we provide or create +entirely new syntactic overlays for their own purposes. -Through use of plugins in the Test Engine layer, NUnit will be able to recognize, load and run tests written using other frameworks. Our focus will be on facilitating the creation of plugins in support of external frameworks by the projects that produce those frameworks or by interested users. For frameworks where that sort of support is not possible – commercial frameworks, for example – we have the option of creating the plugins ourselves. +Through use of plugins in the Test Engine layer, NUnit will be able to recognize, load and run tests written using other +frameworks. Our focus will be on facilitating the creation of plugins in support of external frameworks by the projects +that produce those frameworks or by interested users. For frameworks where that sort of support is not possible – +commercial frameworks, for example – we have the option of creating the plugins ourselves. -In some cases, individuals with an idea for a new framework may be able to create them more simply by writing an adapter on top of the NUnit framework itself. We will encourage and support this by giving priority to framework modifications that provide the necessary infrastructure for such projects. +In some cases, individuals with an idea for a new framework may be able to create them more simply by writing an adapter +on top of the NUnit framework itself. We will encourage and support this by giving priority to framework modifications +that provide the necessary infrastructure for such projects. -NUnit will also provide or re-package some framework extensions for specific types of applications, including Windows Forms development, WPF development, web page access, XML testing, performance measurement and load testing. At this point, it is not yet possible to state which of these will involve existing third-party packages and which will be developed from scratch, because discussions are ongoing. +NUnit will also provide or re-package some framework extensions for specific types of applications, including Windows +Forms development, WPF development, web page access, XML testing, performance measurement and load testing. At this +point, it is not yet possible to state which of these will involve existing third-party packages and which will be +developed from scratch, because discussions are ongoing. -The NUnitLite framework will be supported running on devices and reporting results back to the Test Engine through a communications channel. +The NUnitLite framework will be supported running on devices and reporting results back to the Test Engine through a +communications channel. -Various popular mock frameworks will be supported. NUnit's own self-tests now use the NSubstitute framework, which is packaged with NUnit, but users may make use of whatever mocking framework they prefer. +Various popular mock frameworks will be supported. NUnit's own self-tests now use the NSubstitute framework, which is +packaged with NUnit, but users may make use of whatever mocking framework they prefer. ## See Also -You can also view the [Original Architectural Overview Document](xref:nunit3architecture2009) created for NUnit 3.0 in 2009. +You can also view the [Original Architectural Overview Document](xref:nunit3architecture2009) created for NUnit 3.0 in +2009. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/Attribute-Hierarchy.md b/docs/articles/nunit/technical-notes/nunit-internals/Attribute-Hierarchy.md index e5ea4c35c..a6082d339 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/Attribute-Hierarchy.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/Attribute-Hierarchy.md @@ -3,9 +3,13 @@ > [!WARNING] > This is a draft. The contents may be out of date. -This technical note describes the inheritance hierarchy used for attributes in NUnit. It applies to the built-in attributes and may also be used as a guide for where to place custom attributes in the hierarchy. However, use of these attributes as base classes is entirely optional for custom attributes, as all functionality is accessed through the implemented interfaces. +This technical note describes the inheritance hierarchy used for attributes in NUnit. It applies to the built-in +attributes and may also be used as a guide for where to place custom attributes in the hierarchy. However, use of these +attributes as base classes is entirely optional for custom attributes, as all functionality is accessed through the +implemented interfaces. -Essentially, we use attribute inheritance to define the "what" of an attribute... that is, what it primarily **is** and what it primarily is used for. The actual functionality of an attribute is defined by the use of interfaces. +Essentially, we use attribute inheritance to define the "what" of an attribute... that is, what it primarily **is** and +what it primarily is used for. The actual functionality of an attribute is defined by the use of interfaces. ## Abstract Attribute Classes @@ -13,22 +17,28 @@ The base of the hierarchy is formed by a number of abstract classes. They genera ### NUnitAttribute -All NUnit attributes inherit directly or indirectly from `NUnitAttribute`. Its only purpose is to allow easy selection of all NUnit attributes on a member. If a custom attribute does not fit under any of the other attribute classes, you may derive it directly from `NUnitAttribute`. +All NUnit attributes inherit directly or indirectly from `NUnitAttribute`. Its only purpose is to allow easy selection +of all NUnit attributes on a member. If a custom attribute does not fit under any of the other attribute classes, you +may derive it directly from `NUnitAttribute`. ### TestFixtureBuilderAttribute -`TestFixtureBuilderAttribute` is the base class for any attribute that knows how to build a test fixture of some kind from a provided class. In this context, a test fixture means any test that is based on a user class. +`TestFixtureBuilderAttribute` is the base class for any attribute that knows how to build a test fixture of some kind +from a provided class. In this context, a test fixture means any test that is based on a user class. NUnit includes the following attributes derived from `TestFixtureBuilderAttribute`: * `TestFixtureAttribute` * `SetUpFixtureAttribute`. -Derived classes that build fixtures should implement the `IFixtureBuilder` interface. `TestFixtureBuilderAttribute` does not implement this interface itself since future versions of NUnit may introduce additional interfaces that build fixtures. Therefore, the choice of interface is left to the derived class. +Derived classes that build fixtures should implement the `IFixtureBuilder` interface. `TestFixtureBuilderAttribute` does +not implement this interface itself since future versions of NUnit may introduce additional interfaces that build +fixtures. Therefore, the choice of interface is left to the derived class. ### TestCaseBuilderAttribute -`TestCaseBuilderAttribute` is the base class for any attribute that knows how to build a test case from a given method. Test cases may be simple (without arguments) or parameterized (taking arguments) and are always based on a `MethodInfo`. +`TestCaseBuilderAttribute` is the base class for any attribute that knows how to build a test case from a given method. +Test cases may be simple (without arguments) or parameterized (taking arguments) and are always based on a `MethodInfo`. NUnit includes the following attributes derived from `TestCaseBuilderAttribute`: @@ -41,15 +51,22 @@ NUnit includes the following attributes derived from `TestCaseBuilderAttribute`: * `TestCaseSourceAttribute` * `TheoryAttribute` -As with `TestFixtureBuilderAttribute`, the choice of a specific interface to implement is left to the derived class. Custom classes that build test cases should implement one of the interfaces designed for the purpose: `ISimpleTestCaseBuilder` or `ITestCaseBuilder`. Further interfaces may be defined in the future. In addition, any builder that is intended to cause a non-attributed class to be used as an NUnit TestFixture should implement `IImplyFixture`. +As with `TestFixtureBuilderAttribute`, the choice of a specific interface to implement is left to the derived class. +Custom classes that build test cases should implement one of the interfaces designed for the purpose: +`ISimpleTestCaseBuilder` or `ITestCaseBuilder`. Further interfaces may be defined in the future. In addition, any +builder that is intended to cause a non-attributed class to be used as an NUnit TestFixture should implement +`IImplyFixture`. ### IncludeExcludeAttribute -`IncludeExcludeAttribute` is the base class for any attributes used to decide whether to include a test in the current run or exclude it based on the string properties `Include`, `Exclude` and `Reason`. The abstract base simply makes these properties available to the derived class, which is responsible for taking action on them. +`IncludeExcludeAttribute` is the base class for any attributes used to decide whether to include a test in the current +run or exclude it based on the string properties `Include`, `Exclude` and `Reason`. The abstract base simply makes these +properties available to the derived class, which is responsible for taking action on them. NUnit currently defines two attributes that derive from `IncludeExcludeAttribute`: * `CultureAttribute` * `PlatformAttribute` -These two attributes implement `IApplyToTest` and set the `RunState` of the test based on interpreting the arguments and the current environment. Custom classes derived from `IncludeExcludeAttribute` should do the same thing. +These two attributes implement `IApplyToTest` and set the `RunState` of the test based on interpreting the arguments and +the current environment. Custom classes derived from `IncludeExcludeAttribute` should do the same thing. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/Framework-Api.md b/docs/articles/nunit/technical-notes/nunit-internals/Framework-Api.md index 435e4560b..e95970106 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/Framework-Api.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/Framework-Api.md @@ -1,10 +1,17 @@ # Framework API -The NUnit 3 Framework API consists of a number of related classes with well-known names contained in the framework. The NUnit 3 Framework Driver, which is part of the engine, performs actions by creating these classes. All required actions are performed in the constructor. The driver only needs to know the names of the classes and the arguments each one accepts. +The NUnit 3 Framework API consists of a number of related classes with well-known names contained in the framework. The +NUnit 3 Framework Driver, which is part of the engine, performs actions by creating these classes. All required actions +are performed in the constructor. The driver only needs to know the names of the classes and the arguments each one +accepts. -This document describes the interface between the driver and framework and the rules that must be followed to provide continued backward compatibility as new versions of the framework are created. Note that it __only__ applies to the NUnit 3 framework. +This document describes the interface between the driver and framework and the rules that must be followed to provide +continued backward compatibility as new versions of the framework are created. Note that it __only__ applies to the +NUnit 3 framework. -The following is a simplified example of how a calling program might use the framework to load and run tests in a particular `AppDomain`. This sort of code is expected to reside only in a driver. User-created runners should use the Engine API rather than dealing with the framework at this low level. See below for explanations of each call. +The following is a simplified example of how a calling program might use the framework to load and run tests in a +particular `AppDomain`. This sort of code is expected to reside only in a driver. User-created runners should use the +Engine API rather than dealing with the framework at this low level. See below for explanations of each call. ```csharp var myHandler = new MyHandlerClass(); // implements ICallbackEventHandler @@ -49,13 +56,18 @@ The following classes provide the API: ### FrameworkPackageSettings -This static class defines constants for the names of all settings recognized by the framework. We use `FrameworkPackageSettings` rather than constants spread throughout the code in order to keep things consistent. A copy of this class is maintained in both the console runner and the framework and the settings are passed through to the framework by the engine. +This static class defines constants for the names of all settings recognized by the framework. We use +`FrameworkPackageSettings` rather than constants spread throughout the code in order to keep things consistent. A copy +of this class is maintained in both the console runner and the framework and the settings are passed through to the +framework by the engine. -As new versions of the framework are released, settings in this file are not changed, although new settings may be added. See the code itself for a list of the settings in use. +As new versions of the framework are released, settings in this file are not changed, although new settings may be +added. See the code itself for a list of the settings in use. ### FrameworkController -The driver creates a `FrameworkController` instance using reflection for each test assembly that must be loaded for browsing or execution. The constructor is defined as follows: +The driver creates a `FrameworkController` instance using reflection for each test assembly that must be loaded for +browsing or execution. The constructor is defined as follows: ```csharp public FrameworkController(string assemblyPath, string idPrefix, IDictionary settings) @@ -64,24 +76,37 @@ public FrameworkController(string assemblyPath, string idPrefix, IDictionary set where * `assemblyPath` is the full path to the test assembly. -* `idPrefix` is a prefix used for all test ids created under this controller. This is how the engine is able to provide unique ids for each test identified, even though multiple assemblies, frameworks and controllers may be involved. -* `settings` is an IDictionary containing the settings to be used in loading and running this assembly. A non-generic dictionary is used to allow for implementation of the framework on platforms that don't support Generics. +* `idPrefix` is a prefix used for all test ids created under this controller. This is how the engine is able to provide + unique ids for each test identified, even though multiple assemblies, frameworks and controllers may be involved. +* `settings` is an IDictionary containing the settings to be used in loading and running this assembly. A non-generic + dictionary is used to allow for implementation of the framework on platforms that don't support Generics. -This constructor always succeeds, provided that the arguments are of the correct types. Any operational errors will occur when specific actions like Load or Run are taken. +This constructor always succeeds, provided that the arguments are of the correct types. Any operational errors will +occur when specific actions like Load or Run are taken. ### FrameworkControllerAction -As the driver needs to perform some action, it creates a temporary instance of a class derived from `FrameworkControllerAction`. The constructors for all actions have the following points in common: +As the driver needs to perform some action, it creates a temporary instance of a class derived from +`FrameworkControllerAction`. The constructors for all actions have the following points in common: -* They take an instance of `FrameworkController` as their first argument. This must be the instance originally created by the driver for the particular assembly. This instance provides a common point of communication among various actions taken against the assembly. -* Another argument, the last one, is an object that implements `System.Web.UI.ICallbackEventHandler`. The handler receives the result of each action and - in the case of executing tests - progress notifications. -* Due to the nature of the `ICallbackEventHandler` interface, the results returned are always strings. The specific content of each result depends on the particular action. -* Exceptions are only thrown in the case of completely unanticipated errors, generally meaning an error in the calling program or a bug in the framework. We don't consider things like missing or bad files or exceptions thrown in user code as unanticipated. +* They take an instance of `FrameworkController` as their first argument. This must be the instance originally created + by the driver for the particular assembly. This instance provides a common point of communication among various + actions taken against the assembly. +* Another argument, the last one, is an object that implements `System.Web.UI.ICallbackEventHandler`. The handler + receives the result of each action and - in the case of executing tests - progress notifications. +* Due to the nature of the `ICallbackEventHandler` interface, the results returned are always strings. The specific + content of each result depends on the particular action. +* Exceptions are only thrown in the case of completely unanticipated errors, generally meaning an error in the calling + program or a bug in the framework. We don't consider things like missing or bad files or exceptions thrown in user + code as unanticipated. -Some actions take the string representation of a test filter as an argument. The NUnit Engine and Framework have shared knowledge of the format of a filter. For an empty filter (no filtering) use `""`. A null or empty string is also accepted for an empty filter as of NUnit 3.7.1, but `""` should be used for backwards compatibility. +Some actions take the string representation of a test filter as an argument. The NUnit Engine and Framework have shared +knowledge of the format of a filter. For an empty filter (no filtering) use `""`. A null or empty string is +also accepted for an empty filter as of NUnit 3.7.1, but `""` should be used for backwards compatibility. > [!NOTE] -> The `ICallbackEventHandler` is actually passed as an object and cast to the interface by the framework. This is intended to allow future use of other interfaces for progress. +> The `ICallbackEventHandler` is actually passed as an object and cast to the interface by the framework. This +> is intended to allow future use of other interfaces for progress. ### LoadTestsAction @@ -96,7 +121,9 @@ where * `controller` is the FrameworkController instance that was created for managing the test assembly. * `handler` is an object implementing `ICallbackEventHandler`, to receive the result of the load. -The result returned from `handler.GetCallbackResult()` is the XML representation of the loaded test assembly. No child tests are included in the XML, since this method will be called by programs with no need for such a level of detail. Programs requiring the full tree of tests, such as Gui runners, should follow up by using the `ExploreTestsAction`. +The result returned from `handler.GetCallbackResult()` is the XML representation of the loaded test assembly. No child +tests are included in the XML, since this method will be called by programs with no need for such a level of detail. +Programs requiring the full tree of tests, such as Gui runners, should follow up by using the `ExploreTestsAction`. If the assembly can not be found or loaded, the same result is returned, but with a `RunState` of `NotRunnable`. @@ -114,7 +141,8 @@ where * __filter__ is the string representation of a filter in XML format to be used when exploring tests. * __handler__ is an object implementing ICallbackEventHandler, to receive the result of the call. -The result returned from `handler.GetCallbackResult()` is the XML representation of the test assembly, containing all tests that passed the filter, arranged as a tree with child tests contained within their parents. +The result returned from `handler.GetCallbackResult()` is the XML representation of the test assembly, containing all +tests that passed the filter, arranged as a tree with child tests contained within their parents. If the assembly was not found or unable to be loaded, a non-runnable assembly with no child tests is returned. @@ -122,7 +150,8 @@ If this action is invoked without first invoking `LoadTestsAction`, an `InvalidO ### CountTestsAction -CountTestsAction is used to get the number of test cases that will be executed under a specified filter, for use in a progress display. Its constructor is as follows. +CountTestsAction is used to get the number of test cases that will be executed under a specified filter, for use in a +progress display. Its constructor is as follows. ```csharp public CountTestsAction(FrameworkController controller, string filter, object handler); @@ -134,7 +163,8 @@ where * `filter` is the string representation of a filter in XML format to be used when counting tests. * `handler` is an object implementing `ICallbackEventHandler`, to receive the result of the call. -The result returned from `handler.GetCallbackResult()` is the string representation of the integer number of test cases that match the filter. +The result returned from `handler.GetCallbackResult()` is the string representation of the integer number of test cases +that match the filter. If the assembly was not found or unable to be loaded, "0" is returned. @@ -154,7 +184,8 @@ where * `filter` is the string representation of a filter in XML format to be used when counting tests. * `handler` is an object implementing `ICallbackEventHandler`, to receive the result of the call. -The result returned from `handler.GetCallbackResult` is the XML representation of the test result, including all child results. +The result returned from `handler.GetCallbackResult` is the XML representation of the test result, including all child +results. If the assembly was not found or could not be loaded, a non-runnable result with no child tests is returned. @@ -174,7 +205,8 @@ where * `filter` is the string representation of a filter in XML format to be used when counting tests. * `handler` is an object implementing `ICallbackEventHandler`, to receive the result of the call. -No actual result is returned immediately from the call. The `handler` progress notices must be tracked in order to know what is going on with the tests and eventually the final result may be retrieved. +No actual result is returned immediately from the call. The `handler` progress notices must be tracked in order to know +what is going on with the tests and eventually the final result may be retrieved. If the assembly was not found or could not be loaded, a non-runnable result with no child tests is returned. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/Framework-Design.md b/docs/articles/nunit/technical-notes/nunit-internals/Framework-Design.md index 523080c3b..8457c5e2a 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/Framework-Design.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/Framework-Design.md @@ -3,77 +3,79 @@ > [!WARNING] > This is a draft. The contents may be out of date. -NUnit 3.0 is intentionally changing certain design decisions made in earlier versions. We document those changes here so that developers may find them all in one place. +NUnit 3.0 is intentionally changing certain design decisions made in earlier versions. We document those changes here so +that developers may find them all in one place. -For details, see the individual specifications referenced under each -design change subheading. +For details, see the individual specifications referenced under each design change subheading. ## Key Design Changes ### Multiple Framework Distributions -NUnit 3.0 introduces separate framework builds for each supported runtime version, including .NET 2.0, 3.5, 4.0 and 4.5. We will continue to use the same framework assemblies for both the Microsoft and Mono implementations. +NUnit 3.0 introduces separate framework builds for each supported runtime version, including .NET 2.0, 3.5, 4.0 and 4.5. +We will continue to use the same framework assemblies for both the Microsoft and Mono implementations. ### Merge NUnitLite -NUnitLite is a light-weight version of NUnit, requiring minimal resources and running on platforms not supported by full NUnit. NUnitLite is approximately equivalent to the framework portion of NUnit, with the addition of a rudimentary test runner. +NUnitLite is a light-weight version of NUnit, requiring minimal resources and running on platforms not supported by full +NUnit. NUnitLite is approximately equivalent to the framework portion of NUnit, with the addition of a rudimentary test +runner. -For the NUnit 3.0 release, the NUnitLite project code has been merged with the code of NUnit itself, using conditional compilation to support a reduced feature set. +For the NUnit 3.0 release, the NUnitLite project code has been merged with the code of NUnit itself, using conditional +compilation to support a reduced feature set. ### Framework Boundary -Historically, most xUnit frameworks incorporate the logic for loading and -running tests in the same module that includes assertions, attributes and -other types referenced by the tests. NUnit started that way but the loading -and test execution logic was extracted into a separate assembly in later -versions. - -This approach had some benefit - most notably NUnit's ability to run -tests built against older versions of the framework - but has proven -less useful as more features were added. Essentially, the surface area -that NUnit presents to a client program wanting to run tests grows -each time a new feature is added. This has made it very difficult for +Historically, most xUnit frameworks incorporate the logic for loading and running tests in the same module that includes +assertions, attributes and other types referenced by the tests. NUnit started that way but the loading and test +execution logic was extracted into a separate assembly in later versions. + +This approach had some benefit -- most notably NUnit's ability to run tests built against older versions of the +framework -- but has proven less useful as more features were added. Essentially, the surface area that NUnit presents +to a client program wanting to run tests grows each time a new feature is added. This has made it very difficult for third parties to keep up with NUnit's feature growth. -For NUnit 3.0, the boundary has been moved. Each version of the framework -incorporates a test runner that knows how to load and execute the -tests supported by that version. +For NUnit 3.0, the boundary has been moved. Each version of the framework incorporates a test runner that knows how to +load and execute the tests supported by that version. ### Framework Api -The internal (core) interfaces used by earlier versions of NUnit are not suitable for external use because they tend to change as features are added. The 3.0 release incorporates a new interface, supporting the same functionality as the existing interfaces, but with fewer dependencies on custom types. It is usable by both NUnit and third-party runners and will provide functions of test discovery, loading and execution. +The internal (core) interfaces used by earlier versions of NUnit are not suitable for external use because they tend to +change as features are added. The 3.0 release incorporates a new interface, supporting the same functionality as the +existing interfaces, but with fewer dependencies on custom types. It is usable by both NUnit and third-party runners and +will provide functions of test discovery, loading and execution. See [Framework Api](Framework-Api.md) ### Active Attributes -In the NUnit 2.x series, Attributes are fundamentally passive objects. They are used as markers for certain kinds of functionality, but that functionality is implemented in the nunit.core assembly. Reflection is used to identify attributes, in order to avoid a reference from the core to a specific version of the framework. +In the NUnit 2.x series, Attributes are fundamentally passive objects. They are used as markers for certain kinds of +functionality, but that functionality is implemented in the nunit.core assembly. Reflection is used to identify +attributes, in order to avoid a reference from the core to a specific version of the framework. -In NUnit 3.0, since the test loader is part of the framework assembly, we'll be able to identify attributes without use of reflection, which should improve load performance. Attributes will actually contain the code that carries out the necessary functionality. +In NUnit 3.0, since the test loader is part of the framework assembly, we'll be able to identify attributes without use +of reflection, which should improve load performance. Attributes will actually contain the code that carries out the +necessary functionality. See [DRAFT:Active Attributes](Active-Attributes.md) ### Test Loading -Earlier releases of NUnit load tests in a hierarchy based on the namespace and may optionally load them as a flat list of fixtures. The test hierarchy is built as the tests are loaded and reflected in the gui display. +Earlier releases of NUnit load tests in a hierarchy based on the namespace and may optionally load them as a flat list +of fixtures. The test hierarchy is built as the tests are loaded and reflected in the gui display. -With NUnit 3.0, the test loader will only load fixtures and will not -create a hierarchy. It will be the responsibility of the Gui to construct -whatever display hierarchy the user chooses as a view of the tests. +With NUnit 3.0, the test loader will only load fixtures and will not create a hierarchy. It will be the responsibility +of the Gui to construct whatever display hierarchy the user chooses as a view of the tests. -This will simplify the loading of tests and is compatible with NUnitLite, -which already loads tests this way. +This will simplify the loading of tests and is compatible with NUnitLite, which already loads tests this way. ### Test Execution -Currently, the sequencing of tests is the responsibility of the tests -themselves. That is, each test suite executes its own child tests and each -test reports its own results. +Currently, the sequencing of tests is the responsibility of the tests themselves. That is, each test suite executes its +own child tests and each test reports its own results. -The absence of a distinct test execution object makes it difficult to -support certain features, such as high-level setup and teardown, parallel -test execution and cancellation of running tests with restart. +The absence of a distinct test execution object makes it difficult to support certain features, such as high-level setup +and teardown, parallel test execution and cancellation of running tests with restart. -In NUnit 3.0, the objects representing tests will no longer have the -responsibility of running any subordinate tests and a separate test runner -will sequence through the tests to execute them in the desired order. +In NUnit 3.0, the objects representing tests will no longer have the responsibility of running any subordinate tests and +a separate test runner will sequence through the tests to execute them in the desired order. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/NUnit-3.0-Architecture-(2009).md b/docs/articles/nunit/technical-notes/nunit-internals/NUnit-3.0-Architecture-(2009).md index fb8bc7f9a..aac042438 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/NUnit-3.0-Architecture-(2009).md +++ b/docs/articles/nunit/technical-notes/nunit-internals/NUnit-3.0-Architecture-(2009).md @@ -4,12 +4,14 @@ uid: nunit3architecture2009 # NUnit 3.0 Architecture (2009) -> This is the original - now out of date - document created to describe the planned architecture for NUnit 3.0. We are keeping it for whatever historical interest it may have. -> The diagram was created first and was shown for the first time by Charlie Poole at a Mono gathering in Madrid in 2008. The complete document was published the following year. +> This is the original - now out of date - document created to describe the planned architecture for NUnit 3.0. We are +> keeping it for whatever historical interest it may have. The diagram was created first and was shown for the first +> time by Charlie Poole at a Mono gathering in Madrid in 2008. The complete document was published the following year. ## Summary -This specification describes the overall layered architecture of the NUnit Platform. Details of individual components are covered only as they are relevant to the overall architecture. +This specification describes the overall layered architecture of the NUnit Platform. Details of individual components +are covered only as they are relevant to the overall architecture. ### Launchpad Blueprint @@ -46,35 +48,63 @@ The basic architecture of the NUnit Extended testing platform consists of three ### Test Runner Layer -The Test Runner or UI layer contains various runners, some provided by the NUnit team, others by independent projects leveraging the NUnit platform. Some runners are stand-alone programs, while others are tasks or plugins running under the control of an IDE or other application. This diversity of runners is part of the reason we refer to NUnit 3.0 as a Testing Platform – we expect many different runners to come into existence and will facilitate their development by providing reusable controls for several key environments. +The Test Runner or UI layer contains various runners, some provided by the NUnit team, others by independent projects +leveraging the NUnit platform. Some runners are stand-alone programs, while others are tasks or plugins running under +the control of an IDE or other application. This diversity of runners is part of the reason we refer to NUnit 3.0 as a +Testing Platform – we expect many different runners to come into existence and will facilitate their development by +providing reusable controls for several key environments. -Programs in this layer are able to participate in the NUnit platform plugin architecture, providing extension points that allow them to be extended. Plugins at this level will usually add some functionality to the UI. Some of them may be standalone while others may require the presence of specific test engine plugins in order to operate. +Programs in this layer are able to participate in the NUnit platform plugin architecture, providing extension points +that allow them to be extended. Plugins at this level will usually add some functionality to the UI. Some of them may be +standalone while others may require the presence of specific test engine plugins in order to operate. -The NUnit project will continue to provide both a console runner and a WinForms-based GUI with extended capabilities those in NUnit 2.5. In addition, two new GUI runners will be developed, one based on WPF, the other on GTK#. +The NUnit project will continue to provide both a console runner and a WinForms-based GUI with extended capabilities +those in NUnit 2.5. In addition, two new GUI runners will be developed, one based on WPF, the other on GTK#. -We’ll work with the NAnt project to provide updates to the NAnt task for use with NUnit 3.0, with the goal of keeping that task current as new versions of NUnit are released. We will provide an NUnit plugin for the new Gallio platform. +We’ll work with the NAnt project to provide updates to the NAnt task for use with NUnit 3.0, with the goal of keeping +that task current as new versions of NUnit are released. We will provide an NUnit plugin for the new Gallio platform. -In the area of IDE integration, we will deliver a Visual Studio addin or package for running NUnit tests. Since other folks are already providing open source plugins for SharpDevelop and MonoDevelop, we’ll work with them to ensure compatibility. +In the area of IDE integration, we will deliver a Visual Studio addin or package for running NUnit tests. Since other +folks are already providing open source plugins for SharpDevelop and MonoDevelop, we’ll work with them to ensure +compatibility. -There is a long-standing need for a runner that executes tests in an actual or simulated web server environment. While good practice calls for extracting as much functionality as possible into separately testable assemblies, more complex applications often contain code which can only be tested in such an environment. For that reason, NUnit 3.0 will feature a web runner, which allows tests to be executed on a web server, reporting results back to the desktop. +There is a long-standing need for a runner that executes tests in an actual or simulated web server environment. While +good practice calls for extracting as much functionality as possible into separately testable assemblies, more complex +applications often contain code which can only be tested in such an environment. For that reason, NUnit 3.0 will feature +a web runner, which allows tests to be executed on a web server, reporting results back to the desktop. -Each of the runners will have the option of participating in the NUnit plugin architecture and using functionality provided by NUnit to whatever degree desired. For the runners developed directly by the NUnit team, this capability will be used to the max, allowing others to add GUI features that function by themselves or in conjunction with other plugins operating at the level of the test engine. +Each of the runners will have the option of participating in the NUnit plugin architecture and using functionality +provided by NUnit to whatever degree desired. For the runners developed directly by the NUnit team, this capability will +be used to the max, allowing others to add GUI features that function by themselves or in conjunction with other plugins +operating at the level of the test engine. ### Test Engine Layer -The Test Engine Layer is the core of the NUnit platform. It provides a public API for use by applications that want to locate, load and run tests and display test results. Many aspects of the Test Engine are already present in NUnit 2.4, while others are new. I’ll focus on the new features here. +The Test Engine Layer is the core of the NUnit platform. It provides a public API for use by applications that want to +locate, load and run tests and display test results. Many aspects of the Test Engine are already present in NUnit 2.4, +while others are new. I’ll focus on the new features here. -NUnit 2.5 already supports running tests in a separate process, allowing selection of the CLR version under which the test is to be run. NUnit 3.0 will extend this feature to allow test processes to run on other machines. It will also support distribution of test execution across a network of remote Test Agents. This facility is intended to be used in several distinct scenarios: +NUnit 2.5 already supports running tests in a separate process, allowing selection of the CLR version under which the +test is to be run. NUnit 3.0 will extend this feature to allow test processes to run on other machines. It will also +support distribution of test execution across a network of remote Test Agents. This facility is intended to be used in +several distinct scenarios: * Simple load sharing when test execution time is excessive * Testing applications on multiple platforms * Testing applications, which are themselves distributed -A great deal of distributed function is already present in NUnit 2.5 through pNUnit, the distributed testing runner contributed to our project by Codice Software. With NUnit 3.0, we plan to integrate this function more completely into NUnit, allowing them to be executed by any runner that uses the NUnit Test Engine. +A great deal of distributed function is already present in NUnit 2.5 through pNUnit, the distributed testing runner +contributed to our project by Codice Software. With NUnit 3.0, we plan to integrate this function more completely into +NUnit, allowing them to be executed by any runner that uses the NUnit Test Engine. -NUnit will support performance and coverage analysis, test result reporting and maintenance of a history of test results. These features will function only as called upon by the user. That is, we will not carry on data collection activities with the potential of impacting performance when the user simply wants to run tests. +NUnit will support performance and coverage analysis, test result reporting and maintenance of a history of test +results. These features will function only as called upon by the user. That is, we will not carry on data collection +activities with the potential of impacting performance when the user simply wants to run tests. -Through use of plugins, NUnit will be able to support a wide variety of test types beyond low-level, isolated programmer tests. What is available in this area will be dependent on the interests of users and their willingness to contribute their efforts to creating them. Examples of the kinds of things we envision, some of which we will provide directly, are: +Through use of plugins, NUnit will be able to support a wide variety of test types beyond low-level, isolated programmer +tests. What is available in this area will be dependent on the interests of users and their willingness to contribute +their efforts to creating them. Examples of the kinds of things we envision, some of which we will provide directly, +are: * Randomization of test execution order * Deterministic test ordering for integration tests @@ -88,20 +118,40 @@ Through use of plugins, NUnit will be able to support a wide variety of test typ #### Framework Layer -In NUnit 3.0, the NUnit framework itself – the assembly that is referenced by user tests – will be split along two dimensions. First, there will be separate framework assemblies for different version levels of the Common Language Runtime. By splitting the framework in this way, we will be able to take advantage of newer features, and allow users to take advantage of them, without compromising basic support for older runtimes. +In NUnit 3.0, the NUnit framework itself – the assembly that is referenced by user tests – will be split along two +dimensions. First, there will be separate framework assemblies for different version levels of the Common Language +Runtime. By splitting the framework in this way, we will be able to take advantage of newer features, and allow users to +take advantage of them, without compromising basic support for older runtimes. -The second split we plan is between the core framework capabilities and the syntactic features that make it easy to access those features. A key example of this is the fluent interface introduced in NUnit 2.4 – the “Assert.That” syntax. One thing we learned through that experiment is that the same syntactic “sugar” does not work well for different language environments. Many of the 2.4/2.5 constructs are unusable or very difficult to use in other languages – C++ for example. By a combination of separate namespaces and separate assemblies, we will allow users to select the appropriate syntax for the work they are doing. Other people will be able to build on the syntax we provide or create entirely new syntactic overlays for their own purposes. +The second split we plan is between the core framework capabilities and the syntactic features that make it easy to +access those features. A key example of this is the fluent interface introduced in NUnit 2.4 – the “Assert.That” syntax. +One thing we learned through that experiment is that the same syntactic “sugar” does not work well for different +language environments. Many of the 2.4/2.5 constructs are unusable or very difficult to use in other languages – C++ for +example. By a combination of separate namespaces and separate assemblies, we will allow users to select the appropriate +syntax for the work they are doing. Other people will be able to build on the syntax we provide or create entirely new +syntactic overlays for their own purposes. -Through use of plugins in the Test Engine layer, NUnit will be able to recognize, load and run tests written using other frameworks. Our focus will be on facilitating the creation of plugins in support of external frameworks by the projects that produce those frameworks or by interested users. For frameworks where that sort of support is not possible – commercial frameworks, for example – we have the option of creating the plugins ourselves. +Through use of plugins in the Test Engine layer, NUnit will be able to recognize, load and run tests written using other +frameworks. Our focus will be on facilitating the creation of plugins in support of external frameworks by the projects +that produce those frameworks or by interested users. For frameworks where that sort of support is not possible – +commercial frameworks, for example – we have the option of creating the plugins ourselves. -In some cases, individuals with an idea for a new framework may be able to create them more simply by writing an adapter on top of the NUnit framework itself. We will encourage and support this by giving priority to framework modifications that provide the necessary infrastructure for such projects. +In some cases, individuals with an idea for a new framework may be able to create them more simply by writing an adapter +on top of the NUnit framework itself. We will encourage and support this by giving priority to framework modifications +that provide the necessary infrastructure for such projects. -NUnit will also provide or re-package some framework extensions for specific types of applications, including Windows Forms development, WPF development, web page access, XML testing, performance measurement and load testing. At this point, it is not yet possible to state which of these will involve existing third-party packages and which will be developed from scratch, because discussions are ongoing. +NUnit will also provide or re-package some framework extensions for specific types of applications, including Windows +Forms development, WPF development, web page access, XML testing, performance measurement and load testing. At this +point, it is not yet possible to state which of these will involve existing third-party packages and which will be +developed from scratch, because discussions are ongoing. -The NUnitLite framework will be supported running on devices and reporting results back to the Test Engine through a communications channel. +The NUnitLite framework will be supported running on devices and reporting results back to the Test Engine through a +communications channel. -Various popular mock frameworks will be supported. One framework will be selected for use by NUnit’s own self-tests and will be packaged with NUnit. +Various popular mock frameworks will be supported. One framework will be selected for use by NUnit’s own self-tests and +will be packaged with NUnit. ### Further Details -More detailed specifications are being developed for each of the layers. Consult the [Specifications](xref:specifications) index for their current status. +More detailed specifications are being developed for each of the layers. Consult the +[Specifications](xref:specifications) index for their current status. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/NUnit-APIs.md b/docs/articles/nunit/technical-notes/nunit-internals/NUnit-APIs.md index 8eb56a89e..f583b1bfe 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/NUnit-APIs.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/NUnit-APIs.md @@ -3,25 +3,34 @@ NUnit provides three levels of public APIs for discovering and running tests. From highest to lowest level they are: * **Test Engine API** - for general use by any program that needs to discover and execute tests. -* **Engine Driver API** - implemented by framework drivers to allow the engine to communicate with a particular framework. +* **Engine Driver API** - implemented by framework drivers to allow the engine to communicate with a particular + framework. * **Framework API** - used by the NUnit 3 framework driver to communicate with the framework. ![Diagram of NUnit topology](~/images/nunit-topology.png) ## Test Engine API -The NUnit TestEngine is a separate component, introduced in NUnit 3.0, which knows how to discover and execute tests. It provides an API for both simple batch execution and more complex interaction as needed by Gui test runners. It also provides additional Engine services beyond what the framework provides. This is what we recommend for use by anyone needing to run NUnit tests programmatically. +The NUnit TestEngine is a separate component, introduced in NUnit 3.0, which knows how to discover and execute tests. It +provides an API for both simple batch execution and more complex interaction as needed by Gui test runners. It also +provides additional Engine services beyond what the framework provides. This is what we recommend for use by anyone +needing to run NUnit tests programmatically. See [Test Engine API](xref:testengineapi) for more info. ## Engine Driver API -The NUnit TestEngine uses drivers to communicate with test frameworks. It is possible to create a driver for running any sort of test framework, supporting any language at all. The driver API is what makes this possible. The TestEngine has support for the NUnit 3 framework built in. An extension driver for running NUnit 2 tests is also available. +The NUnit TestEngine uses drivers to communicate with test frameworks. It is possible to create a driver for running any +sort of test framework, supporting any language at all. The driver API is what makes this possible. The TestEngine has +support for the NUnit 3 framework built in. An extension driver for running NUnit 2 tests is also available. -The driver API is only intended to be implemented by drivers and is only used by the NUnit engine. See [Engine Driver API](xref:frameworkdrivers) for more info. +The driver API is only intended to be implemented by drivers and is only used by the NUnit engine. See [Engine Driver +API](xref:frameworkdrivers) for more info. ## NUnit Framework API -This is a primitive API implemented by the NUnit 3 Framework. The NUnitFrameworkDriver in the engine uses this API. The API is a bit complicated to use. Since it needs to support multiple versions of the framework, it uses well-known framework class names, which are constructed via reflection. All results are returned as raw XML. +This is a primitive API implemented by the NUnit 3 Framework. The NUnitFrameworkDriver in the engine uses this API. The +API is a bit complicated to use. Since it needs to support multiple versions of the framework, it uses well-known +framework class names, which are constructed via reflection. All results are returned as raw XML. This API is not intended for any use except by NUnit itself. See [Framework API](Framework-Api.md) for more info. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/Test-Discovery-And-Execution.md b/docs/articles/nunit/technical-notes/nunit-internals/Test-Discovery-And-Execution.md index 022dd8144..d33c99b55 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/Test-Discovery-And-Execution.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/Test-Discovery-And-Execution.md @@ -3,30 +3,40 @@ > [!WARNING] > This is a draft. The contents may be out of date. -This spec summarizes the three levels of APIs provided by NUnit for discovering and running tests. Note that only one of them - the highest level - is supported for general usage. The others have very specific purposes and should only be used for those purposes. +This spec summarizes the three levels of APIs provided by NUnit for discovering and running tests. Note that only one of +them - the highest level - is supported for general usage. The others have very specific purposes and should only be +used for those purposes. The three APIs, from highest to lowest level, are: * **Test Engine API** - for use by any program that needs to discover and execute tests. -* **Engine Driver API** - for use by framework drivers, intended to be loaded by the engine to enable communication with a particular framework. +* **Engine Driver API** - for use by framework drivers, intended to be loaded by the engine to enable communication with + a particular framework. * **Framework API** - only used by NUnit's own framework driver to communicate with the framework. ![Diagram of the layers of test discovery](~/images/nunit-topology.png) ## Test Engine API -The NUnit TestEngine is a separate component, new to NUnit 3.0, which knows how to discover and execute tests. It provides an API for both simple batch execution and more complex interaction as needed by typical Gui test runners. It also provides additional Engine services beyond what the framework provides. +The NUnit TestEngine is a separate component, new to NUnit 3.0, which knows how to discover and execute tests. It +provides an API for both simple batch execution and more complex interaction as needed by typical Gui test runners. It +also provides additional Engine services beyond what the framework provides. This API is currently under development. See [Test Engine API](xref:testengineapi) for more info. ## Engine Driver API -The NUnit TestEngine uses drivers to communicate with test frameworks. Initially, the engine will come with a driver for NUnit 3.0, followed by an NUnit 2.x driver. It is possible to create a driver for running any sort of test framework, supporting any language at all. The driver API is what makes this possible. +The NUnit TestEngine uses drivers to communicate with test frameworks. Initially, the engine will come with a driver for +NUnit 3.0, followed by an NUnit 2.x driver. It is possible to create a driver for running any sort of test framework, +supporting any language at all. The driver API is what makes this possible. -The driver API is only intended to be implemented by drivers and is only used by the NUnit engine. This API is currently under development. See [Engine Driver API](xref:frameworkdrivers) for more info. +The driver API is only intended to be implemented by drivers and is only used by the NUnit engine. This API is currently +under development. See [Engine Driver API](xref:frameworkdrivers) for more info. ## NUnit Framework API -This is a primitive API implemented by the nunit.framework and NUnitLite assemblies. The NUnitFrameworkDriver in the engine uses this API. The API is a bit complicated to use. Since it needs to support multiple versions of the framework, it uses well-known framework class names, which are constructed via reflection. All results are returned as raw XML. +This is a primitive API implemented by the nunit.framework and NUnitLite assemblies. The NUnitFrameworkDriver in the +engine uses this API. The API is a bit complicated to use. Since it needs to support multiple versions of the framework, +it uses well-known framework class names, which are constructed via reflection. All results are returned as raw XML. This API is not intended for any use except by NUnit itself. See [Framework API](Framework-Api.md) for more info. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Dynamic-Test-Cases-Spec.md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Dynamic-Test-Cases-Spec.md index a7a1fce1c..128ba0a02 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Dynamic-Test-Cases-Spec.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Dynamic-Test-Cases-Spec.md @@ -7,35 +7,31 @@ This specification describes changes in how test cases will be generated in NUni ## Rationale -NUnit currently supports parameterized tests using the TestCase, TestCaseSource, -Values, ValueSource, Random and Range attributes. All these data sources provide -data that is used to generate test cases as the tests are loaded. We refer to these -as "pre-generated" test cases. - -There is also a need for what we are calling "dynamically generated" test cases, -which are not created until the test is about to run and which may be re-created -each time the test is run. - -For example, it may be desirable to perform some initialization of the data in -a OneTimeFixtureSetUp method. This is not possible using the pre-generated model, -because the tests are generated before any execution. -As another example, the data may consist of the names of files in a certain -directory. If the directory content is changing dynamically, we may want our -tests to reflect those changes, which is only possible using the dynamic model. - -For all these reasons - and because users have requested it - we are introducing -the notion of "dynamically generated" test cases in NUnit 3.0. Some existing -attributes will be re-purposed and new attributes created to support it. +NUnit currently supports parameterized tests using the TestCase, TestCaseSource, Values, ValueSource, Random and Range +attributes. All these data sources provide data that is used to generate test cases as the tests are loaded. We refer to +these as "pre-generated" test cases. + +There is also a need for what we are calling "dynamically generated" test cases, which are not created until the test is +about to run and which may be re-created each time the test is run. + +For example, it may be desirable to perform some initialization of the data in a OneTimeFixtureSetUp method. This is not +possible using the pre-generated model, because the tests are generated before any execution. As another example, the +data may consist of the names of files in a certain directory. If the directory content is changing dynamically, we may +want our tests to reflect those changes, which is only possible using the dynamic model. + +For all these reasons - and because users have requested it - we are introducing the notion of "dynamically generated" +test cases in NUnit 3.0. Some existing attributes will be re-purposed and new attributes created to support it. > [!NOTE] -> Dynamic test case generation is also required for the proper implementation of **Theories**, which will be described in a separate specification. +> Dynamic test case generation is also required for the proper implementation of **Theories**, which will be +> described in a separate specification. ## Design ### Key Tradeoffs -The two types of test cases have important differences in how they may -be used by NUnit and each has certain advantages and limitations as well. +The two types of test cases have important differences in how they may be used by NUnit and each has certain advantages +and limitations as well. | Pre-Generated | Dynamically Generated | |-----------------|-------------------------| @@ -53,43 +49,56 @@ be used by NUnit and each has certain advantages and limitations as well. * Introduce dynamic test case generation, as described above. * For ease of use, each data attribute should use either the pre-generated or dynamically generated model exclusively. -* Parameterized test methods may mix both types of attribute, allowing both pre-generated and dynamically generated test cases. -* Provided that external data sources such as files and databases are not changed, we will support repeatable test runs across different program sessions and within the same session. -* The Gui will display new test cases as they are generated and will provide a visual cue to distinguish the two types of test cases. +* Parameterized test methods may mix both types of attribute, allowing both pre-generated and dynamically generated test + cases. +* Provided that external data sources such as files and databases are not changed, we will support repeatable test runs + across different program sessions and within the same session. +* The Gui will display new test cases as they are generated and will provide a visual cue to distinguish the two types + of test cases. ### Syntax -As in NUnit 2.5, Attributes applied to test methods will provide or point to the data to be used as test arguments. Except as noted below, attributes will not change syntactically and will continue to operate as before even though many of them will now generate test cases dynamically. The following paragraphs describe the impact of the change on each attribute. +As in NUnit 2.5, Attributes applied to test methods will provide or point to the data to be used as test arguments. +Except as noted below, attributes will not change syntactically and will continue to operate as before even though many +of them will now generate test cases dynamically. The following paragraphs describe the impact of the change on each +attribute. **TestCaseAttribute** will continue to work as it now does, producing pre-generated test cases. -**TestCaseSourceAttribute** and **ValueSourceAttribute** will continue to create pre-generated test cases, but will be more limited in their usage than before. The following data sources will be supported: +**TestCaseSourceAttribute** and **ValueSourceAttribute** will continue to create pre-generated test cases, but will be +more limited in their usage than before. The following data sources will be supported: * Static fields, properties or methods of the test fixture. * Static or instance fields properties or methods of an external or nested class. -> It's likely that there will be ways to 'trick' NUnit into accepting an instance member for one of these attributes, leading to instantiation of the test class at load time. If that occurs, the results are undefined. Obviously, such trickery is not recommended and we'll try hard to detect and reject such attempts. +> It's likely that there will be ways to 'trick' NUnit into accepting an instance member for one of these attributes, +> leading to instantiation of the test class at load time. If that occurs, the results are undefined. Obviously, such +> trickery is not recommended and we'll try hard to detect and reject such attempts. -A new **DynamicDataSourceAttribute** (the name is a placeholder) will supplant both **TestCaseSourceAttribute** and **ValueSourceAttribute** for dynamic generation of test cases and parameter values respectively. Suggestions are welcome for the final name of this attribute. +A new **DynamicDataSourceAttribute** (the name is a placeholder) will supplant both **TestCaseSourceAttribute** and +**ValueSourceAttribute** for dynamic generation of test cases and parameter values respectively. Suggestions are welcome +for the final name of this attribute. -**ValuesAttribute**, **RangeAttribute**, **RandomAttribute**, **CombinatorialAttribute**, **PairwiseAttribute** and **SequentialAttribute** (that is, all other data attributes) will be used to produce test cases dynamically. +**ValuesAttribute**, **RangeAttribute**, **RandomAttribute**, **CombinatorialAttribute**, **PairwiseAttribute** and +**SequentialAttribute** (that is, all other data attributes) will be used to produce test cases dynamically. -**DatapointAttribute** and **DatapointsAttribute** are only used for Theories, but for the sake of completeness it may be noted that they will also operate dynamically. +**DatapointAttribute** and **DatapointsAttribute** are only used for Theories, but for the sake of completeness it may +be noted that they will also operate dynamically. -Where necessary, additional properties may be added to some attributes in order to provide for repeatability of tests. At the moment, the only known requirement is for specification of a random seed for **RandomAttribute** but others may arise in implementation. +Where necessary, additional properties may be added to some attributes in order to provide for repeatability of tests. +At the moment, the only known requirement is for specification of a random seed for **RandomAttribute** but others may +arise in implementation. #### Gui Design Notes Since we don't have an NUnit 3.0 Gui yet, these notes are for the future... -When tests are run in batch mode using the console runner, the distinction -between fixed and dynamic data is moot. In that environment, tests are loaded -and executed in rapid sequence, after which the process is terminated. +When tests are run in batch mode using the console runner, the distinction between fixed and dynamic data is moot. In +that environment, tests are loaded and executed in rapid sequence, after which the process is terminated. -But when using the Gui, the affect of using dynamic data is quite visible. -Dynamic tests are initially loaded without showing any subordinate test cases. -After each run, test cases are repopulated and may even be different. -This has several important consequences for the Gui... +But when using the Gui, the affect of using dynamic data is quite visible. Dynamic tests are initially loaded without +showing any subordinate test cases. After each run, test cases are repopulated and may even be different. This has +several important consequences for the Gui... * It must be able to deal with test cases added during test execution. * It must be able to trigger regeneration of test cases for a rerun. @@ -98,7 +107,10 @@ This has several important consequences for the Gui... ### Implementation Notes -Interface changes will be required to identify the presence of either pre-generated or dynamic data for a method. NUnitTestCaseBuilder will accept a test method with arguments so long as either type is present but will only create pre-generated test cases. Dynamic test case generation will take place in the Run method of ParameterizedMethodSuite class using registered extensions that support dynamic data. +Interface changes will be required to identify the presence of either pre-generated or dynamic data for a method. +NUnitTestCaseBuilder will accept a test method with arguments so long as either type is present but will only create +pre-generated test cases. Dynamic test case generation will take place in the Run method of ParameterizedMethodSuite +class using registered extensions that support dynamic data. The result will be a new addition to the standard sequence of test execution, as follows: diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Engine-Addins-Spec.md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Engine-Addins-Spec.md index 8dac9e465..80567d6b7 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Engine-Addins-Spec.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Engine-Addins-Spec.md @@ -1,17 +1,24 @@ # Engine Addins Spec > [!NOTE] -> This page is a specification that was used as a starting point for creating the feature in NUnit. It needs to be reviewed and revised in order to accurately reflect what was actually built. If you take it with a grain of salt, it may still be helpful to you as documentation. This notice will be removed when the page is brought up to date. +> This page is a specification that was used as a starting point for creating the feature in NUnit. It needs to +> be reviewed and revised in order to accurately reflect what was actually built. If you take it with a grain of salt, +> it may still be helpful to you as documentation. This notice will be removed when the page is brought up to date. This spec covers a proposed new approach to Engine addins, replacing the use of Mono.Addins. ## Background -We originally planned to use Mono.Addins for the engine and have done so in the first betas. However, Mono.Addins no longer supports .NET 2.0. We are using a modified version that we created and which we will have to maintain in the future. Mono.Addins has many more features than we expect to use and has a rather large memory and disk footprint. +We originally planned to use Mono.Addins for the engine and have done so in the first betas. However, Mono.Addins no +longer supports .NET 2.0. We are using a modified version that we created and which we will have to maintain in the +future. Mono.Addins has many more features than we expect to use and has a rather large memory and disk footprint. -In sum, Mono.Addins is not really carrying its weight for our usage. We will try to replace it with a simple plugin architecture of our own design, using some pieces of our old NUnit 2.x addin feature as well as other features inspired by Mono.Addins. +In sum, Mono.Addins is not really carrying its weight for our usage. We will try to replace it with a simple plugin +architecture of our own design, using some pieces of our old NUnit 2.x addin feature as well as other features inspired +by Mono.Addins. -At a minimum, we need to support existing addins that are supported by Mono.Addins. Once we have that support, we can replace Mono.Addins. Further features could be added later. +At a minimum, we need to support existing addins that are supported by Mono.Addins. Once we have that support, we can +replace Mono.Addins. Further features could be added later. Three addin types are currently supported: @@ -23,11 +30,17 @@ Three addin types are currently supported: ### Extension Points -In both Mono and NUnit (2.x) addins, extensibility centers around `ExtensionPoints`. An `ExtensionPoint` is a place in the application where add-ins can register themselves in order to provide added functionality. extension nodes to provide extra functionality. NUnit 3.0 will continue to use this concept. +In both Mono and NUnit (2.x) addins, extensibility centers around `ExtensionPoints`. An `ExtensionPoint` is a place in +the application where add-ins can register themselves in order to provide added functionality. extension nodes to +provide extra functionality. NUnit 3.0 will continue to use this concept. -In our initial implementation, all extension points must be known in advance and are contained in the engine. At a future point, we will probably want to add a way to dynamically create new extension points so that addins can themselves host extensions. +In our initial implementation, all extension points must be known in advance and are contained in the engine. At a +future point, we will probably want to add a way to dynamically create new extension points so that addins can +themselves host extensions. -`ExtensionPoints` in the engine will be identified by use of `ExtensionPointAttribute` at the assembly level. Each attribute identifies one extension point, specifying an identifying string (the Path) and the required Type of any extension objects to be registered with it. +`ExtensionPoints` in the engine will be identified by use of `ExtensionPointAttribute` at the assembly level. Each +attribute identifies one extension point, specifying an identifying string (the Path) and the required Type of any +extension objects to be registered with it. #### Example @@ -36,11 +49,16 @@ In our initial implementation, all extension points must be known in advance and Type="NUnit.Engine.Extensibility.IDriverFactory")] ``` -In this example, the Path identifying the extension point is "/NUnit/Engine/DriverService." Any type to be plugged into this extension point must implement `IDriverFactory`. Note that even though each extension point is typically implemented by some class in the system, the identity of that class is an implementation detail, which is not revealed in the `ExtensionPoint`. +In this example, the Path identifying the extension point is "/NUnit/Engine/DriverService." Any type to be plugged into +this extension point must implement `IDriverFactory`. Note that even though each extension point is typically +implemented by some class in the system, the identity of that class is an implementation detail, which is not revealed +in the `ExtensionPoint`. ### Extensions -An `Extension` is a single object of the required type, which is registered with an `ExtensionPoint`. Extensions are identified by the `ExtensionAttribute` which is applied to the class. Extensions identified in this way must have a default constructor. See the `Addins` section below for dealing with more complex situations. +An `Extension` is a single object of the required type, which is registered with an `ExtensionPoint`. Extensions are +identified by the `ExtensionAttribute` which is applied to the class. Extensions identified in this way must have a +default constructor. See the `Addins` section below for dealing with more complex situations. #### Example @@ -52,10 +70,12 @@ public class NUnit2DriverFactory : IDriverFactory } ``` -The example above shows an extension Type being used with the `ExtensionPoint` defined in the previous example. An instance of NUnit2DriverFactory will be supplied to the DriverService when needed. The Path property must match the Path for the intended `ExtensionPoint`. +The example above shows an extension Type being used with the `ExtensionPoint` defined in the previous example. An +instance of NUnit2DriverFactory will be supplied to the DriverService when needed. The Path property must match the Path +for the intended `ExtensionPoint`. -The Path is actually optional so long as NUnit is able to deduce the correct ExtensionPoint based on the Type. -In fact, that's the case in this example, which can be rewritten more simply as... +The Path is actually optional so long as NUnit is able to deduce the correct ExtensionPoint based on the Type. In fact, +that's the case in this example, which can be rewritten more simply as... ```csharp [Extension] @@ -65,25 +85,42 @@ public class NUnit2DriverFactory : IDriverFactory } ``` -The Path may be omitted provided that no other extension point is able to accept an object of the same class as the extension. +The Path may be omitted provided that no other extension point is able to accept an object of the same class as the +extension. #### Locating Addins -Assemblies containing Addins and Extensions are stored in one or more locations indicated in files of type `.addins`. Each line of the file contains the path of an addin assembly or a directory containing assemblies. Wildcards may be used for assembly entries and relative paths are interpreted based on the location of the `.addins` file. The default `nunit.engine.addins` is located in the engine directory and lists addins we build with NUnit, which are contained in the addins directory. +Assemblies containing Addins and Extensions are stored in one or more locations indicated in files of type `.addins`. +Each line of the file contains the path of an addin assembly or a directory containing assemblies. Wildcards may be used +for assembly entries and relative paths are interpreted based on the location of the `.addins` file. The default +`nunit.engine.addins` is located in the engine directory and lists addins we build with NUnit, which are contained in +the addins directory. -Any assemblies specified in a `.addins` file will be scanned fully, looking for addins and extensions. Any directories specified will be browsed, first looking for any `.addins` files. If one or more files are found, the content of the files will direct all further browsing. If no such file is found, then all `.dll` files in the directory will be scanned, just as if a `.addins` file contained "*.dll." +Any assemblies specified in a `.addins` file will be scanned fully, looking for addins and extensions. Any directories +specified will be browsed, first looking for any `.addins` files. If one or more files are found, the content of the +files will direct all further browsing. If no such file is found, then all `.dll` files in the directory will be +scanned, just as if a `.addins` file contained "*.dll." -Assemblies are be examined using Cecil. Any assembly that cannot be opened is be ignored, with a log message generated. This be a normal occurrence in cases where the assembly targets a higher level runtime than that which is in use. Info is saved for actual instantiation of extensions on a just-in-time basis. +Assemblies are be examined using Cecil. Any assembly that cannot be opened is be ignored, with a log message generated. +This be a normal occurrence in cases where the assembly targets a higher level runtime than that which is in use. Info +is saved for actual instantiation of extensions on a just-in-time basis. -We hope that the combination of specifically indicating which assemblies to scan and the use of Cecil to do the scanning will make this process quite efficient. If that turns out not to be the case, we can use an assembly-level attribute to identify assemblies containing extensions. +We hope that the combination of specifically indicating which assemblies to scan and the use of Cecil to do the scanning +will make this process quite efficient. If that turns out not to be the case, we can use an assembly-level attribute to +identify assemblies containing extensions. ## Future Enhancements ### Addins -An `Addin` is a Type that provides `Extensions`. As indicated in the previous section, simple extensions providing a single instance of the object through a default constructor do not require an Addin. For more complex situations, an Addin object could be allowed to create and register one or more extensions. This is the approach that we took in NUnit 2.x. +An `Addin` is a Type that provides `Extensions`. As indicated in the previous section, simple extensions providing a +single instance of the object through a default constructor do not require an Addin. For more complex situations, an +Addin object could be allowed to create and register one or more extensions. This is the approach that we took in NUnit +2.x. -Addins would be identified by the `AddinAttribute` and implement the IAddin interface. They actively participate in the installation of extensions and may be used to create objects that require parameters, to install multiple extensions or to select among different extensions. +Addins would be identified by the `AddinAttribute` and implement the IAddin interface. They actively participate in the +installation of extensions and may be used to create objects that require parameters, to install multiple extensions or +to select among different extensions. #### Example @@ -104,15 +141,22 @@ public class NUnit2DriverFactory : IDriverFactory } ``` -The above example does the same thing as the previous example in a more complicated way. Obviously, you would use this approach only in more complex situations. Note that the factory class does not have an `ExtensionAttribute` as this would lead to its being installed twice. +The above example does the same thing as the previous example in a more complicated way. Obviously, you would use this +approach only in more complex situations. Note that the factory class does not have an `ExtensionAttribute` as this +would lead to its being installed twice. #### Notes -1. This design feature is not required initially and will be omitted from the implementation until we actually require it. +1. This design feature is not required initially and will be omitted from the implementation until we actually require + it. 2. The interfaces used in this section are notionally based on NUnit 2.6.4. ### Addins on Addins -Initially, we only need one level of addins to allow for everything we now do. It may be convenient at some point to support addins on top of other addins. For example, a given framework driver might be enhanced with some special feature through an addin. +Initially, we only need one level of addins to allow for everything we now do. It may be convenient at some point to +support addins on top of other addins. For example, a given framework driver might be enhanced with some special feature +through an addin. -An `ExtensionPoint` in an extension assembly could be identified in the same way as an engine extension point is known, using the `ExtensionPointAttribute` at assembly level. However, this is not a feature we need for the 3.0 release, only one to keep in mind for the future. +An `ExtensionPoint` in an extension assembly could be identified in the same way as an engine extension point is known, +using the `ExtensionPointAttribute` at assembly level. However, this is not a feature we need for the 3.0 release, only +one to keep in mind for the future. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Extended-Constraint-Syntax-Spec.md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Extended-Constraint-Syntax-Spec.md index effdd5965..7d2834594 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Extended-Constraint-Syntax-Spec.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Extended-Constraint-Syntax-Spec.md @@ -3,7 +3,10 @@ > [!WARNING] > This is a draft. The contents may be out of date. -This specification is about a new syntax for expressing NUnit assertions using the features of .NET framework 3.5 including language improvements. There are two key features this enables: Extension methods permit a modular, extensible fluent constraint syntax, and LINQ expression trees permit using plain C# (or VB) as a expression-based constraint language. +This specification is about a new syntax for expressing NUnit assertions using the features of .NET framework 3.5 +including language improvements. There are two key features this enables: Extension methods permit a modular, +extensible fluent constraint syntax, and LINQ expression trees permit using plain C# (or VB) as a expression-based +constraint language. ## User Stories @@ -27,19 +30,27 @@ This improves NUnit by making it easier to learn and less necessary to extend. There are already a couple of implementations implementing a fluent syntax or expression-based syntax or both: -* Extension Methods for NUnit: this is substantially an aliasing mechanism which, without touching the constraints themselves, provides a fluent way to express them -* [SharpTestsEx](http://sharptestsex.codeplex.com): this is an improvement of [NUnitEx](https://code.google.com/p/nunitex/) and provides an extension-method based constraint syntax in addition to a starting point for an expression-based mechanism of assertions. -* [ExpressionToCode](https://code.google.com/p/expressiontocode/): this is an expression-based assertion library. It is a reimplementation of [Power Assert .NET](http://powerassert.codeplex.com/), which is itself a port of [Groovy's Power Assert](https://dontmindthelanguage.wordpress.com/2009/12/11/groovy-1-7-power-assert/). +* Extension Methods for NUnit: this is substantially an aliasing mechanism which, without touching the constraints + themselves, provides a fluent way to express them +* [SharpTestsEx](http://sharptestsex.codeplex.com): this is an improvement of + [NUnitEx](https://code.google.com/p/nunitex/) and provides an extension-method based constraint syntax in addition to + a starting point for an expression-based mechanism of assertions. +* [ExpressionToCode](https://code.google.com/p/expressiontocode/): this is an expression-based assertion library. It is + a reimplementation of [Power Assert .NET](http://powerassert.codeplex.com/), which is itself a port of [Groovy's Power + Assert](https://dontmindthelanguage.wordpress.com/2009/12/11/groovy-1-7-power-assert/). ## Extensible Fluent Constraint Proposal -Ideally we would like to be able to use a constraint syntax similar to the current fluent syntax that is extensible. This requires using extension methods instead of static classes, as the following example demonstrates: +Ideally we would like to be able to use a constraint syntax similar to the current fluent syntax that is extensible. +This requires using extension methods instead of static classes, as the following example demonstrates: ```csharp Assert.That(1, Is.GreaterThan(0)) ``` -This example is not extensible since it uses the static ''Is'' class. If I wanted to write something like ''Is.MuchGreaterThan(int x)'' and thus a constraint ''MuchGreaterThan'' which NUnit doesn't provide, I would have to alter and recompile NUnit's code. Patching NUnit like this and maintaining such a patch is a high barrier to entry. +This example is not extensible since it uses the static ''Is'' class. If I wanted to write something like +''Is.MuchGreaterThan(int x)'' and thus a constraint ''MuchGreaterThan'' which NUnit doesn't provide, I would have to +alter and recompile NUnit's code. Patching NUnit like this and maintaining such a patch is a high barrier to entry. The same assertion could be written as: @@ -47,13 +58,15 @@ The same assertion could be written as: Assert.That(1).Is.GreaterThan(0) ``` -This allows for extensions since any user can define a new extension method for the class of the ''Is'' property. Say ''Is'' were to return a value of type ''IIsConstraint'', then I could just write +This allows for extensions since any user can define a new extension method for the class of the ''Is'' property. Say +''Is'' were to return a value of type ''IIsConstraint'', then I could just write ```csharp public static void MuchGreaterThan(this IIsConstraint iis) { /* ... */ } ``` -Taking syntax shown on the [SharpTestsEx homepage](http://sharptestex.codeplex.com/) as an example, some assertions with the new NUnit syntax could be written as following: +Taking syntax shown on the [SharpTestsEx homepage](http://sharptestex.codeplex.com/) as an example, some assertions with +the new NUnit syntax could be written as following: | SharpTestsEx | NUnit 3.0 proposal | |-----------------------------------------------------------|---------------------------------| @@ -71,7 +84,8 @@ How would the following actually work? Assert.That("something").StartsWith("so").Or.EndsWith("ing"); ``` -How would ''StartsWith'' know that it's not supposed to do anything if it fails, since there is a chance ''EndsWith'' might succeed? +How would ''StartsWith'' know that it's not supposed to do anything if it fails, since there is a chance ''EndsWith'' +might succeed? Remember, the above code is semantically identical to this: @@ -80,11 +94,15 @@ var temp = Assert.That("something").StartsWith("so"); temp.Or.EndsWith("ing"); ``` -Extension methods can lead to namespace pollution; in particular if defined on ''object'' (which we therefore should try to avoid). +Extension methods can lead to namespace pollution; in particular if defined on ''object'' (which we therefore should try +to avoid). ## Expression Based Constraint Proposal -NUnit provides a wealth of constraints. This means that knowing how to expression non-trivial constraints isn't always easy (particularly for new or casual users). Finding the appropriate constraint (or combination of constraints) requires knowledge NUnit's many constraints, and the semantics of a particular constraint may not be clear without reading the documentation. +NUnit provides a wealth of constraints. This means that knowing how to expression non-trivial constraints isn't always +easy (particularly for new or casual users). Finding the appropriate constraint (or combination of constraints) +requires knowledge NUnit's many constraints, and the semantics of a particular constraint may not be clear without +reading the documentation. For example, consider the assertion (valid for many uppercase strings, for most cultures): @@ -92,7 +110,8 @@ For example, consider the assertion (valid for many uppercase strings, for most Assert.That(() => x == x.ToLower().ToUpper()); ``` -This expression can be expressed as a standard equality constraint, but doing so means not showing the intermediate steps in the computation. Using expression trees, a failure could be rendered as: +This expression can be expressed as a standard equality constraint, but doing so means not showing the intermediate +steps in the computation. Using expression trees, a failure could be rendered as: ```none Assert.That failed for: @@ -106,6 +125,11 @@ x == x.ToLower().ToUpper() "ABC İ" ``` -This variant requires very little knowledge of NUnit, yet is still usable even for complex constraints by leveraging a language the user already knows (namely VB or C#). +This variant requires very little knowledge of NUnit, yet is still usable even for complex constraints by leveraging a +language the user already knows (namely VB or C#). -Possible extensions to this concept could be "Helpers" that recognize specific patterns and improve readability. For instance, if an expression consists of a sequence of ''&&'' operators, a helper might suppress showing the details of non-failing clauses. Or, if an expression contains multiple DateTime, the helper could ensure the accuracy of the DateTime.ToString is high enough to represent any differences. If an ''=='' operator fails but ''.Equals'' would have succeeded, this could be mentioned. +Possible extensions to this concept could be "Helpers" that recognize specific patterns and improve readability. For +instance, if an expression consists of a sequence of ''&&'' operators, a helper might suppress showing the details of +non-failing clauses. Or, if an expression contains multiple DateTime, the helper could ensure the accuracy of the +DateTime.ToString is high enough to represent any differences. If an ''=='' operator fails but ''.Equals'' would have +succeeded, this could be mentioned. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Include and Exclude Attributes (Alternatives).md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Include and Exclude Attributes (Alternatives).md index c53eea2c2..53924aab3 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Include and Exclude Attributes (Alternatives).md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Include and Exclude Attributes (Alternatives).md @@ -4,7 +4,9 @@ uid: includeexcludeattributesalternatives # Include And Exclude Attributes Alternatives -This spec describes proposed new attributes to replace and extend the existing CultureAttribute and PlatformAttribute. These attributes derive from the abstract IncludeExcludeAttribute, which provides `Include` and `Exclude` named properties. The following examples show how these attributes are currently used: +This spec describes proposed new attributes to replace and extend the existing CultureAttribute and PlatformAttribute. +These attributes derive from the abstract IncludeExcludeAttribute, which provides `Include` and `Exclude` named +properties. The following examples show how these attributes are currently used: ```csharp [Culture("fr-FR")] @@ -18,38 +20,52 @@ This spec describes proposed new attributes to replace and extend the existing C ## Alternative Approaches > [!NOTE] -> Three alternative approaches were identified in March, 2014. This is the final update of the document prior to choosing an alternative. Approach #3 seems to be the front-runner at this time. +> Three alternative approaches were identified in March, 2014. This is the final update of the document prior to +> choosing an alternative. Approach #3 seems to be the front-runner at this time. ### 1. Keep the current approach #### How it Works -Exclude has priority. If any attribute excludes a test, it remains excluded, even if another attribute matches it for inclusion. The default constructor argument represents inclusion, so you should not use it along with the Include parameter. Comma-separated alternatives form a union, so that if any item is matched, the test is included (or excluded). +Exclude has priority. If any attribute excludes a test, it remains excluded, even if another attribute matches it for +inclusion. The default constructor argument represents inclusion, so you should not use it along with the Include +parameter. Comma-separated alternatives form a union, so that if any item is matched, the test is included (or +excluded). #### Pros * Having a separate attribute for each domain from which we are making a selection is easy for users to understand. -* With the new attribute-based framework extensibility model in NUnit 3.0, this is probably the easiest approach of all to extend. +* With the new attribute-based framework extensibility model in NUnit 3.0, this is probably the easiest approach of all + to extend. #### Cons -* The current Platform attribute actually works across three different domains: the OS, the runtime and the bit-ness of the process. It's very difficult to define criteria like Windows 7 or 8 running .NET 4.5 using a single attribute. `[Platform("Windows7,Windows8,Net-4.5)]` will include Win 7 or 8 with any runtime and .NET 4.5 with any OS. The best we can do is `[Platform("Windows7,Windows8",Exclude="Net-2.0,Net-3.0,Net-3.5")]`. -* Boolean expressions involving the accepted values would permit the above more cleanly. For example, we might write `Platform("(Windows7 | Windows8) & !Net-4.5)")`. Such logic would have to be implemented for each attribute, most likely in the base class. However, any such logic would only apply within the single attribute: it would not be possible to include both OS and Culture (for example) in the same expression. +* The current Platform attribute actually works across three different domains: the OS, the runtime and the bit-ness of + the process. It's very difficult to define criteria like Windows 7 or 8 running .NET 4.5 using a single attribute. + `[Platform("Windows7,Windows8,Net-4.5)]` will include Win 7 or 8 with any runtime and .NET 4.5 with any OS. The best + we can do is `[Platform("Windows7,Windows8",Exclude="Net-2.0,Net-3.0,Net-3.5")]`. +* Boolean expressions involving the accepted values would permit the above more cleanly. For example, we might write + `Platform("(Windows7 | Windows8) & !Net-4.5)")`. Such logic would have to be implemented for each attribute, most + likely in the base class. However, any such logic would only apply within the single attribute: it would not be + possible to include both OS and Culture (for example) in the same expression. #### Extensibility -Create a new attribute that inherits from IncludeExcludeAttribute and implement the necessary selection logic to decide whether a given string tag is supported. +Create a new attribute that inherits from IncludeExcludeAttribute and implement the necessary selection logic to decide +whether a given string tag is supported. ### 2. Keep Current Approach, but Split PlatformAttribute #### How It Would Work -As mentioned above, PlatformAttribute actually tests over three different domains. We would create a separate attribute for each domain, for example: PlatformAttribute, RuntimeAttribute and ProcessAttribute. +As mentioned above, PlatformAttribute actually tests over three different domains. We would create a separate attribute +for each domain, for example: PlatformAttribute, RuntimeAttribute and ProcessAttribute. #### Pros * All the same as for approach #1, plus... -* The first 'con' in approach #1 would be eliminated. The example given would work as `[Platform("Windows7,Windows8"), Runtime("Net-4.5")]`. +* The first 'con' in approach #1 would be eliminated. The example given would work as `[Platform("Windows7,Windows8"), + Runtime("Net-4.5")]`. * Having separate attributes might make it easier to understand for some users. (see cons) #### Cons @@ -60,13 +76,15 @@ As mentioned above, PlatformAttribute actually tests over three different domain #### Extensibility -Create a new attribute that inherits from IncludeExcludeAttribute and implement the necessary selection logic to decide whether a given string tag is supported. +Create a new attribute that inherits from IncludeExcludeAttribute and implement the necessary selection logic to decide +whether a given string tag is supported. ### 3. Create Replacement Attributes #### How It Would Work -Invert the implied hierarchy by providing an IncludeAttribute and an ExcludeAttribute, which specify what is to be tested in one of several ways. For example: +Invert the implied hierarchy by providing an IncludeAttribute and an ExcludeAttribute, which specify what is to be +tested in one of several ways. For example: ```csharp [Include(Culture="fr-FR")] @@ -77,17 +95,22 @@ Invert the implied hierarchy by providing an IncludeAttribute and an ExcludeAttr #### Pros -* This seems to be at least as easy to understand as the current approach. In some cases it may be better, since use of `Include` as the attribute name makes it quite clear what is happening, whereas `Culture` may be misunderstood as **changing** the culture. +* This seems to be at least as easy to understand as the current approach. In some cases it may be better, since use of + `Include` as the attribute name makes it quite clear what is happening, whereas `Culture` may be misunderstood as + **changing** the culture. * May be extended by the user, depending on which syntactic sub-option we select below. #### Cons -* Allows future development of an expression syntax that would combine all selection elements, but again, depending on the syntax option chosen. +* Allows future development of an expression syntax that would combine all selection elements, but again, depending on + the syntax option chosen. * Some of the syntactic sub-options are not so easy to extend. See below. #### Syntax Options -For this alternative we will want to use a separate namespace for each domain. There would be one set of unique names for the Operating System, one for Runtimes, one for Culture, etc. There are two options we might use to implement this, which are designated as alternatives 3A and 3B. +For this alternative we will want to use a separate namespace for each domain. There would be one set of unique names +for the Operating System, one for Runtimes, one for Culture, etc. There are two options we might use to implement this, +which are designated as alternatives 3A and 3B. ### 3A. Create Replacement Attributes Using Named Properties @@ -105,12 +128,14 @@ Map each domain to a separate named property. For example: #### Cons -* Need to decide how to combine tests across multiple domains. Does [Include(Culture="fr-FR", Runtime="Net-2.0")] mean both or either? +* Need to decide how to combine tests across multiple domains. Does [Include(Culture="fr-FR", Runtime="Net-2.0")] mean + both or either? * Not possible to have logical expressions that combine domains (but maybe they are not needed). #### Extensibility -We would need to provide a registration mechanism, whereby a program provided the name of the domain, the value and a function for evaluating whether the feature is supported or not. It would not be possible to add new domains. +We would need to provide a registration mechanism, whereby a program provided the name of the domain, the value and a +function for evaluating whether the feature is supported or not. It would not be possible to add new domains. ### 3B. Create Replacement Attributes Using Prefixes @@ -134,7 +159,8 @@ Prefix each value with the domain name, thereby creating a unified namespace. #### Extensibility -We would need to provide a registration mechanism, whereby a program provided the name of the domain, the value and a function for evaluating whether the feature is supported or not. New domains could be added in addition to new values. +We would need to provide a registration mechanism, whereby a program provided the name of the domain, the value and a +function for evaluating whether the feature is supported or not. New domains could be added in addition to new values. ## Next Steps diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Include-and-Exclude-Attributes-Spec.md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Include-and-Exclude-Attributes-Spec.md index 7b441fd21..206e6ceb9 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Include-and-Exclude-Attributes-Spec.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Include-and-Exclude-Attributes-Spec.md @@ -3,7 +3,9 @@ > [!WARNING] > This is a draft. The contents may be out of date. -This spec describes proposed new attributes to replace and extend the existing CultureAttribute and PlatformAttribute. We considered several alternative approaches to doing this and selected the approach described here. See [Include and Exclude Attributes (Alternatives)](xref:includeexcludeattributesalternatives) for the original discussion of choices. +This spec describes proposed new attributes to replace and extend the existing CultureAttribute and PlatformAttribute. +We considered several alternative approaches to doing this and selected the approach described here. See [Include and +Exclude Attributes (Alternatives)](xref:includeexcludeattributesalternatives) for the original discussion of choices. ## Attributes @@ -19,23 +21,30 @@ We would define two new attributes, **IncludeAttribute** and **ExcludeAttribute* ## Syntax Options -There are a number of possible alternatives for specifying when a test is to be included or excluded. Each of them is illustrated in the examples above, from which we need to select a subset. +There are a number of possible alternatives for specifying when a test is to be included or excluded. Each of them is +illustrated in the examples above, from which we need to select a subset. ### 1. Named Properties -As illustrated in the first two examples, this approach allows us to clearly separate the namespaces for each selection domain. Comma-separated values are intended to be alternatives, so the second example would include the test under either Win7 or Win8. Separate properties (domains) would be "and-ed" together. +As illustrated in the first two examples, this approach allows us to clearly separate the namespaces for each selection +domain. Comma-separated values are intended to be alternatives, so the second example would include the test under +either Win7 or Win8. Separate properties (domains) would be "and-ed" together. ### 2. Prefixes -By prefixing each value with the domain name, we can create a unified namespace. The third example above uses this approach, making it clear that Net-4.5 represents a runtime and nothing else. As in #1, comma-separated values are alternatives. There is no other way to create logical combinations. +By prefixing each value with the domain name, we can create a unified namespace. The third example above uses this +approach, making it clear that Net-4.5 represents a runtime and nothing else. As in #1, comma-separated values are +alternatives. There is no other way to create logical combinations. ### 3. Implied Domain -To the extent that the accepted values are exclusive, it's possible to deduce the domain from the value. The fourth example above takes advantage of this. Note that this approach can be combined with #2 as a kind of shorthand. +To the extent that the accepted values are exclusive, it's possible to deduce the domain from the value. The fourth +example above takes advantage of this. Note that this approach can be combined with #2 as a kind of shorthand. ### 4. Logical Expression -We can define a DSL that allows us to specify arbitrary expressions for including or excluding tests. The last example above does this. If the expression language included **not**, then we could do away with the ExcludeAttribute. +We can define a DSL that allows us to specify arbitrary expressions for including or excluding tests. The last example +above does this. If the expression language included **not**, then we could do away with the ExcludeAttribute. ## Comparison of Options diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Internal-Trace-Spec.md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Internal-Trace-Spec.md index 43cf5d07f..c351f3e6f 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Internal-Trace-Spec.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Internal-Trace-Spec.md @@ -7,7 +7,10 @@ uid: internaltracespec > [!WARNING] > This is a draft. The contents may be out of date. -NUnit traps text output directed to the Console, Trace or a logging subsystem. This makes it difficult to use text output when debugging the framework itself, particularly when working on the classes that redirect output. For that reason, NUnit incorporates a simple internal tracing mechanism for use by developers and for debugging problems in the field. +NUnit traps text output directed to the Console, Trace or a logging subsystem. This makes it difficult to use text +output when debugging the framework itself, particularly when working on the classes that redirect output. For that +reason, NUnit incorporates a simple internal tracing mechanism for use by developers and for debugging problems in the +field. ## User Stories @@ -21,7 +24,8 @@ NUnit traps text output directed to the Console, Trace or a logging subsystem. T ### Design -NUnit provides a simple internal trace facility using the **InternalTrace** class. The following public methods are provided for creating output: +NUnit provides a simple internal trace facility using the **InternalTrace** class. The following public methods are +provided for creating output: ```csharp public static void Error(string message, params object[] args) @@ -30,18 +34,25 @@ public static void Info(string message, params object[] args) public static void Debug(string message, params object[] args) ``` -By default, all output through **InternalTrace** is sent to the console, which means it is mixed with other console output. Note that the trace mechanism bypasses NUnit's redirection of output and displays on the actual Console. Of course, if NUnit is being run without a console - from the Gui, for example - the output will be lost. +By default, all output through **InternalTrace** is sent to the console, which means it is mixed with other console +output. Note that the trace mechanism bypasses NUnit's redirection of output and displays on the actual Console. Of +course, if NUnit is being run without a console - from the Gui, for example - the output will be lost. ## Redirecting Output -The **InternalTrace.Open()** method allows the programmer to specify a file to which the output will be written. Any absolute or relative path may be used as an argument. Relative paths are interpreted as relative to the location of the assembly being tested. A programmer working on NUnit may call this method at any point in the code. **InternalTrace.Close()** is also provided. +The **InternalTrace.Open()** method allows the programmer to specify a file to which the output will be written. Any +absolute or relative path may be used as an argument. Relative paths are interpreted as relative to the location of the +assembly being tested. A programmer working on NUnit may call this method at any point in the code. +**InternalTrace.Close()** is also provided. > [!NOTE] -> Since the path is saved as a static property, it must be specified separately within each AppDomain. Writing to the same file from two different AppDomains is not supported. +> Since the path is saved as a static property, it must be specified separately within each AppDomain. Writing +> to the same file from two different AppDomains is not supported. ## Specifying Verbosity -Verbosity is specified using the nested enum InternalTrace.TraceLevel. Although the values currently match those of System.Diagnostics.TraceLevel, they have no actual relation to that class. Additional values may be added in the future. +Verbosity is specified using the nested enum InternalTrace.TraceLevel. Although the values currently match those of +System.Diagnostics.TraceLevel, they have no actual relation to that class. Additional values may be added in the future. ```csharp public class InternalTrace @@ -58,7 +69,8 @@ public class InternalTrace } ``` -A programmer working on NUnit may set the TraceLevel at any point in the code by setting the **InternalTrace.Level** property. +A programmer working on NUnit may set the TraceLevel at any point in the code by setting the **InternalTrace.Level** +property. ## Unresolved Issues diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Parameterized-Test-Fixtures-Spec.md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Parameterized-Test-Fixtures-Spec.md index 1a414a537..9d8704303 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Parameterized-Test-Fixtures-Spec.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Parameterized-Test-Fixtures-Spec.md @@ -1,19 +1,29 @@ # Parameterized Test Fixtures Spec > [!NOTE] -> This page is a specification that was used as a starting point for creating the feature in NUnit. It needs to be reviewed and revised in order to accurately reflect what was actually built. If you take it with a grain of salt, it may still be helpful to you as documentation. This notice will be removed when the page is brought up to date. +> This page is a specification that was used as a starting point for creating the feature in NUnit. It needs to +> be reviewed and revised in order to accurately reflect what was actually built. If you take it with a grain of salt, +> it may still be helpful to you as documentation. This notice will be removed when the page is brought up to date. -NUnit 2.6.4 supports parameterized test fixtures using constructor arguments specified on the `TestFixtureAttribute`. This is similar to the way that `TestCaseAttribute` handles parameterized methods. However, methods in 2.6.4 benefit from a very rich set of attributes in addition, allowing the data to be kept separately from the test and permitting use of data types that cannot appear as arguments to an Attribute constructor in .NET. +NUnit 2.6.4 supports parameterized test fixtures using constructor arguments specified on the `TestFixtureAttribute`. +This is similar to the way that `TestCaseAttribute` handles parameterized methods. However, methods in 2.6.4 benefit +from a very rich set of attributes in addition, allowing the data to be kept separately from the test and permitting use +of data types that cannot appear as arguments to an Attribute constructor in .NET. -For NUnit 3.0, we would like to create a similarly rich set of attributes for specifying how TestFixture instances should be created. This spec will outline the features we plan to support. Type names are placeholders and may be changed as the work proceeds. +For NUnit 3.0, we would like to create a similarly rich set of attributes for specifying how TestFixture instances +should be created. This spec will outline the features we plan to support. Type names are placeholders and may be +changed as the work proceeds. ## TestFixtureSourceAttribute -This will work similarly to `TestCaseSourceAttribute` and will supply the constructor arguments for the fixture. The two types will probably be unified under a common base. +This will work similarly to `TestCaseSourceAttribute` and will supply the constructor arguments for the fixture. The two +types will probably be unified under a common base. ## TestFixtureData -This will work similarly to `TestCaseData` with the addition of a number of features that are needed for fixtures. In particular, the Type will need to support a TypeArgs property and possibly a separate set of arguments for use with the OneTimeSetUp method. +This will work similarly to `TestCaseData` with the addition of a number of features that are needed for fixtures. In +particular, the Type will need to support a TypeArgs property and possibly a separate set of arguments for use with the +OneTimeSetUp method. ## ValuesAttribute @@ -23,7 +33,8 @@ This will work similarly to `TestCaseData` with the addition of a number of feat ## RandomAttribute -These attributes may be used on a TestFixture constructor with arguments. Their effect will be similar to use on method arguments, causing the fixture to be constructed a number of times. +These attributes may be used on a TestFixture constructor with arguments. Their effect will be similar to use on method +arguments, causing the fixture to be constructed a number of times. ## CombinatorialAttribute @@ -31,4 +42,5 @@ These attributes may be used on a TestFixture constructor with arguments. Their ## SequentialAttribute -These attributes will need to be modified to work on test fixtures as well as methods. They specify how individual argument values are to be combined to for a set of arguments for constructing the fixture. +These attributes will need to be modified to work on test fixtures as well as methods. They specify how individual +argument values are to be combined to for a set of arguments for constructing the fixture. diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Specifications.md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Specifications.md index b356ddd5a..730a6e7ea 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Specifications.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Specifications.md @@ -5,9 +5,12 @@ uid: specifications # Specifications > [!NOTE] -> Some of these items are actually implemented in the latest release. We are in the process of reviewing all the specs in this section to determine what needs to be converted into actual documentation pages. +> Some of these items are actually implemented in the latest release. We are in the process of reviewing all the +> specs in this section to determine what needs to be converted into actual documentation pages. -Specifications are descriptions of work we are doing or plan to do. They may vary in degree of specificity and the actual code may sometimes deviate from the spec as work progresses, without necessarily going back to change the spec. When the work is done, the spec is removed from the site or incorporated into a tech note as needed. +Specifications are descriptions of work we are doing or plan to do. They may vary in degree of specificity and the +actual code may sometimes deviate from the spec as work progresses, without necessarily going back to change the spec. +When the work is done, the spec is removed from the site or incorporated into a tech note as needed. | Component | Title | Implemented? | |-----------------|--------------------------------------------|----------------| diff --git a/docs/articles/nunit/technical-notes/nunit-internals/specs/Test-Dependency-Attribute-Spec.md b/docs/articles/nunit/technical-notes/nunit-internals/specs/Test-Dependency-Attribute-Spec.md index 34184f5af..a2d427080 100644 --- a/docs/articles/nunit/technical-notes/nunit-internals/specs/Test-Dependency-Attribute-Spec.md +++ b/docs/articles/nunit/technical-notes/nunit-internals/specs/Test-Dependency-Attribute-Spec.md @@ -3,7 +3,8 @@ > [!WARNING] > This is a draft. The contents may be out of date. -This spec describes a proposed new attribute to be used to specify dependencies between tests within a test fixture, and between different test fixtures. +This spec describes a proposed new attribute to be used to specify dependencies between tests within a test fixture, and +between different test fixtures. Attribute @@ -27,7 +28,8 @@ AfterAllSuccess This attribute would apply to Test's within a single TestFixture, or to TextFixture's within a single test assembly. -Each dependency-specification is described in more detail below (in all cases, `` should be replaced with a `` if the attribute is being applied to a TestFixture): +Each dependency-specification is described in more detail below (in all cases, `` should be replaced with a +`` if the attribute is being applied to a TestFixture): ```none is a string containing a comma separated list of Test's to @@ -81,13 +83,21 @@ AfterAllSuccess Afterxxx dependency referencing this Test or TestFixture. ``` -Note that a single Test or TestFixture may have multiple `` elements as long as they do not conflict with each other. +Note that a single Test or TestFixture may have multiple `` elements as long as they do not +conflict with each other. -Any loops or contradictory references in the dependencies will be discovered, and will result in the specified dependencies being ignored, and a warning being given. For example, if TestA has Before="TestB" and TestB has Before="TestA", both will be ignored, and a warning given. (An alternative would be to use whichever was specified first or last). +Any loops or contradictory references in the dependencies will be discovered, and will result in the specified +dependencies being ignored, and a warning being given. For example, if TestA has Before="TestB" and TestB has +Before="TestA", both will be ignored, and a warning given. (An alternative would be to use whichever was specified first +or last). -If multiple tests or test fixtures are in the same relative position in the dependency tree, the order in which they will be run will be the default order. For example, if multiple tests have a BeforeAll dependency, they will run in the default order, but before all other tests not having that dependency specified. +If multiple tests or test fixtures are in the same relative position in the dependency tree, the order in which they +will be run will be the default order. For example, if multiple tests have a BeforeAll dependency, they will run in the +default order, but before all other tests not having that dependency specified. Items to consider: -* Is the name in a `` the name in the code, or the generated name for the test? I would prefer to use the static name that is in the code, but there may be a case for using the generated name. -* Should there be a simple dependency language to be used to specify the dependency rather then the static properties? e.g. `before("TestA") && afterFails ("TestB") || afterSuccess ("TestC")` +* Is the name in a `` the name in the code, or the generated name for the test? I would prefer to use the + static name that is in the code, but there may be a case for using the generated name. +* Should there be a simple dependency language to be used to specify the dependency rather then the static properties? + e.g. `before("TestA") && afterFails ("TestB") || afterSuccess ("TestC")` diff --git a/docs/articles/nunit/technical-notes/usage/Addin-Replacement-in-the-Framework.md b/docs/articles/nunit/technical-notes/usage/Addin-Replacement-in-the-Framework.md index d1cc063a6..e079eb514 100644 --- a/docs/articles/nunit/technical-notes/usage/Addin-Replacement-in-the-Framework.md +++ b/docs/articles/nunit/technical-notes/usage/Addin-Replacement-in-the-Framework.md @@ -15,34 +15,48 @@ NUnit 2.6 supports six types of addins, all of which are being removed from NUni ## General Approach -The addin design for NUnit 2.6 was intended to extend to the console and gui runners in addition to the framework. However, this was never implemented and all six of the existing addin types apply to the framework only. +The addin design for NUnit 2.6 was intended to extend to the console and gui runners in addition to the framework. +However, this was never implemented and all six of the existing addin types apply to the framework only. -In NUnit 3.0, the functions provided by these addins are being taken over by the use of custom attributes. NUnit 3.0 attributes are generally active. That is, they contain code to perform the function they call for rather than simply serving as markers to be interpreted by the runner. +In NUnit 3.0, the functions provided by these addins are being taken over by the use of custom attributes. NUnit 3.0 +attributes are generally active. That is, they contain code to perform the function they call for rather than simply +serving as markers to be interpreted by the runner. ## Advantages -In general, all the same capabilities will be present in NUnit 3.0 and will be much more easily accessible to those who create extensions. Currently, creating an extension is complex and error prone. Use of active attributes generally involves one of two approaches: +In general, all the same capabilities will be present in NUnit 3.0 and will be much more easily accessible to those who +create extensions. Currently, creating an extension is complex and error prone. Use of active attributes generally +involves one of two approaches: -1. Derive the new attribute class from an existing NUnit base that provides the needed facilities. For example, a new data-providing attribute might derive from `DataAttribute`. +1. Derive the new attribute class from an existing NUnit base that provides the needed facilities. For example, a new + data-providing attribute might derive from `DataAttribute`. -2. Derive directly from `NUnitAttribute`, the base of the NUnit attribute hierarchy, and implement one or more interfaces that perform the desired function. +2. Derive directly from `NUnitAttribute`, the base of the NUnit attribute hierarchy, and implement one or more + interfaces that perform the desired function. ## Limitations All existing addins will need to be re-implemented as custom attributes. They will not work in NUnit 3.0. -Addins not based on custom attributes are no longer possible. In NUnit 2.6, for example, it was possible to write an addin that defined tests based on the name of a method, e.g.: methods beginning with "Test". This sort of extension will no longer be possible in the NUnit 3.0 framework. However, this does not seem to be a big problem, since virtually all addins that we know about have been based on attributes. +Addins not based on custom attributes are no longer possible. In NUnit 2.6, for example, it was possible to write an +addin that defined tests based on the name of a method, e.g.: methods beginning with "Test". This sort of extension will +no longer be possible in the NUnit 3.0 framework. However, this does not seem to be a big problem, since virtually all +addins that we know about have been based on attributes. ## Implementation -Because parts of NUnit are implemented as *internal addins*, it's not possible to simply remove all addin support at once. Many things would stop working if we did this. Therefore, we will refactor code for each of the internal types to conform to the new design, only removing the overall addin framework when this is complete. +Because parts of NUnit are implemented as *internal addins*, it's not possible to simply remove all addin support at +once. Many things would stop working if we did this. Therefore, we will refactor code for each of the internal types to +conform to the new design, only removing the overall addin framework when this is complete. -The remaining sections of this spec deal with how each of the addin types is being replaced. The order of the sections reflects the order in which we are implementing the changes. The implementation status of each of the types is shown in parentheses. +The remaining sections of this spec deal with how each of the addin types is being replaced. The order of the sections +reflects the order in which we are implementing the changes. The implementation status of each of the types is shown in +parentheses. -> This spec refers to a number of interfaces that form part of the NUnit framework. Until a technical note -> covering these interfaces is published, please rely on the source code for documentation. -> Some of the sections that follow have not had all their design work completed, so the degree of detail -> varies among them. More information will be added as work progresses. +> This spec refers to a number of interfaces that form part of the NUnit framework. Until a technical note covering +> these interfaces is published, please rely on the source code for documentation. Some of the sections that follow have +> not had all their design work completed, so the degree of detail varies among them. More information will be added as +> work progresses. ### TestDecorators @@ -60,9 +74,13 @@ To modify the properties of the test, create an attribute that implements `IAppl To modify the execution context, implement `IApplyToContext`. This is a new capability. -It is no longer possible - but not necessary either - to replace the test. In NUnit 3.0, the test object does not execute itself. Instead, a series of commands is created, which carry out the necessary operations to run the test. An attribute that implements `ICommandDecorator` is able to contribute to add additional commands to be executed when running the test. +It is no longer possible - but not necessary either - to replace the test. In NUnit 3.0, the test object does not +execute itself. Instead, a series of commands is created, which carry out the necessary operations to run the test. An +attribute that implements `ICommandDecorator` is able to contribute to add additional commands to be executed when +running the test. -It is no longer possible to simply eliminate the test. Once created, a test will always appear in the UI, for example. However, by use of a command decorator, it is possible to prevent the test from executing. +It is no longer possible to simply eliminate the test. Once created, a test will always appear in the UI, for example. +However, by use of a command decorator, it is possible to prevent the test from executing. ### DataPointProviders @@ -71,13 +89,23 @@ It is no longer possible to simply eliminate the test. Once created, a test will NUnit 2.6 has two built-in providers of data for individual parameters of test methods: * `ParameterDataProvider` gets data from attributes that appear directly on the parameter. -* `DatapointProvider` gets data from `DataPoint` and `DataPointSource` attributes, which appear on the data source rather than on the parameter. +* `DatapointProvider` gets data from `DataPoint` and `DataPointSource` attributes, which appear on the data source + rather than on the parameter. -In the current 3.0 code, `ParameterDataProvider` actually delegates its work to the attributes, which must implement `IParameterDataSource`. In NUnit 3.0, users will be able to create additional attributes implementing this interface and they will be used as data sources. +In the current 3.0 code, `ParameterDataProvider` actually delegates its work to the attributes, which must implement +`IParameterDataSource`. In NUnit 3.0, users will be able to create additional attributes implementing this interface and +they will be used as data sources. -On the other hand, `DataPointProvider` contains the code for accessing the data specified by the `DataPoint` and `DataPointSource` attributes, which are simply used as markers. This is because the attributes do not have a reference to the member on which they are placed. It would be necessary to introduce a method to provide them with this reference in order to do the processing within the attribute and this would appear to introduce otherwise unneeded code with no particular benefit. Consequently, for the initial implementation of NUnit 3.0, it will not be possible to create custom attributes that work in similar fashion to `DataPoint` or `DataPointSource`. If the need arises, some interface may be introduced. +On the other hand, `DataPointProvider` contains the code for accessing the data specified by the `DataPoint` and +`DataPointSource` attributes, which are simply used as markers. This is because the attributes do not have a reference +to the member on which they are placed. It would be necessary to introduce a method to provide them with this reference +in order to do the processing within the attribute and this would appear to introduce otherwise unneeded code with no +particular benefit. Consequently, for the initial implementation of NUnit 3.0, it will not be possible to create custom +attributes that work in similar fashion to `DataPoint` or `DataPointSource`. If the need arises, some interface may be +introduced. -Since `DataPointProvider`s are only called from within `TestCaseProvider`s, implementation of these changes may need to be interleaved with changes related to `TestCaseProvider`s. See the next section for details. +Since `DataPointProvider`s are only called from within `TestCaseProvider`s, implementation of these changes may need to +be interleaved with changes related to `TestCaseProvider`s. See the next section for details. ### TestCaseProviders @@ -88,34 +116,50 @@ NUnit 2.6 currently has two built-in TestCaseProviders: * `DataAttributeTestCaseProvider` gets test case data from any DataAttribute, such as `TestCaseAttribute`. * `CombinatorialTestCaseProvider` creates test cases by combining parameter data from a `DataPointProvider`. -Currently, `DataAttributeTestCaseProvider` delegates all the work to the `DataAttribute`. This is the desired approach. Users implementing a new custom data attribute may inherit from `DataAttribute` or implement an interface. +Currently, `DataAttributeTestCaseProvider` delegates all the work to the `DataAttribute`. This is the desired approach. +Users implementing a new custom data attribute may inherit from `DataAttribute` or implement an interface. -`CombinatorialTestCaseProvider` works differently. It instantiates one of three available `CombiningStrategy` types, based on attributes appearing on the method. The `CombiningStrategy` is used to generate test cases from the available parameter data. +`CombinatorialTestCaseProvider` works differently. It instantiates one of three available `CombiningStrategy` types, +based on attributes appearing on the method. The `CombiningStrategy` is used to generate test cases from the available +parameter data. -For NUnit 3.0, the work of combining parameter data into cases will be moved into the `CombiningStrategy` attributes. An interface will be defined and users will be able to create new combining strategies by defining a custom attribute that implements the interface. +For NUnit 3.0, the work of combining parameter data into cases will be moved into the `CombiningStrategy` attributes. An +interface will be defined and users will be able to create new combining strategies by defining a custom attribute that +implements the interface. ### EventListeners > Status: REMOVED -EventListeners implement the `ITestListener` interface and are notified when important events in the life of a test occur. Almost all the functions of an `EventListener` can already be emulated in NUnit 2.6 by use of an `ActionAttribute`. `ActionAttribute`s are not yet implemented in NUnit 3.0. +EventListeners implement the `ITestListener` interface and are notified when important events in the life of a test +occur. Almost all the functions of an `EventListener` can already be emulated in NUnit 2.6 by use of an +`ActionAttribute`. `ActionAttribute`s are not yet implemented in NUnit 3.0. -Consequently, the first step in removing EventListeners is to implement `ActionAttribute`s. Some changes may be made in the process and a separate spec will be written to describe them. +Consequently, the first step in removing EventListeners is to implement `ActionAttribute`s. Some changes may be made in +the process and a separate spec will be written to describe them. -The only function of EventListeners that cannot be duplicated by ActionAttributes at this time is the capture of text output from the test. A new approach will be designed for this purpose. +The only function of EventListeners that cannot be duplicated by ActionAttributes at this time is the capture of text +output from the test. A new approach will be designed for this purpose. ### TestCaseBuilders > Status: REMOVED -NUnit 2.6 has one built-in TestCaseBuilder, `NUnitTestCaseBuilder`, which implements `ITestCaseBuilder2`. All TestCaseBuilders must implement either `ITestCaseBuilder` or `ITestCaseBuilder2`. +NUnit 2.6 has one built-in TestCaseBuilder, `NUnitTestCaseBuilder`, which implements `ITestCaseBuilder2`. All +TestCaseBuilders must implement either `ITestCaseBuilder` or `ITestCaseBuilder2`. -In NUnit 3.0, the interface and its implementation will be moved into the attributes that designate a test. For example, `TestAttribute` will actually build a test case. This may be done using `ITestCaseBuilder2` or a new interface may be designed. Users wishing to create a new kind of test case will need to define a new attribute, which implements the interface. +In NUnit 3.0, the interface and its implementation will be moved into the attributes that designate a test. For example, +`TestAttribute` will actually build a test case. This may be done using `ITestCaseBuilder2` or a new interface may be +designed. Users wishing to create a new kind of test case will need to define a new attribute, which implements the +interface. A few issues need to be resolved: -1. Some attributes, such as `TestCaseAttribute` or `TestCaseSourceAttribute` serve dual functions: they both mark a test case and provide data for the test case. Some combination of the code for generating test cases with that for creating tests is likely to be required. -2. For backward compatibility, an extra `TestAttribute` accompanying one or more `TestCaseAttribute`s should not generate an additional `TestCase`. +1. Some attributes, such as `TestCaseAttribute` or `TestCaseSourceAttribute` serve dual functions: they both mark a test + case and provide data for the test case. Some combination of the code for generating test cases with that for + creating tests is likely to be required. +2. For backward compatibility, an extra `TestAttribute` accompanying one or more `TestCaseAttribute`s should not + generate an additional `TestCase`. ### SuiteBuilders @@ -123,7 +167,9 @@ A few issues need to be resolved: NUnit 2.6 has one built-in SuiteBuilder, which implements the required `ISuiteBuilder` interface. -Similarly to what is being done for test cases, the building of a test fixture will be moved into the `TestFixture` attribute. The supporting interface may need to be redefined. Users may create new types of test fixtures by defining a new attribute, which implements the interface. +Similarly to what is being done for test cases, the building of a test fixture will be moved into the `TestFixture` +attribute. The supporting interface may need to be redefined. Users may create new types of test fixtures by defining a +new attribute, which implements the interface. Similar issues as with TestCaseBuilder must be resolved, in addition to a few others: @@ -131,4 +177,5 @@ Similar issues as with TestCaseBuilder must be resolved, in addition to a few ot 2. *Extra* `TestFixtureAttribute`s in the hierarchy must be ignored. 3. We want to add similar data-generation capabilities to `TestFixture` as exist for methods using `TestCaseSource`. 4. We want to allow "TheoryFixtures", which combine multiple related Theories into a single fixture. -5. We want to support an `AbstractTestFixtureAttribute`, which marks a class as the base of a fixture hierarchy but not a fixture itself. +5. We want to support an `AbstractTestFixtureAttribute`, which marks a class as the base of a fixture hierarchy but not + a fixture itself. diff --git a/docs/articles/nunit/technical-notes/usage/Counting-Tests.md b/docs/articles/nunit/technical-notes/usage/Counting-Tests.md index 1c258f6d3..e268af803 100644 --- a/docs/articles/nunit/technical-notes/usage/Counting-Tests.md +++ b/docs/articles/nunit/technical-notes/usage/Counting-Tests.md @@ -1,10 +1,14 @@ # Counting Tests -Counting tests sounds simple but there are a few issues. This page documents how the framework counts tests in various categories. +Counting tests sounds simple but there are a few issues. This page documents how the framework counts tests in various +categories. -1. In general, when counting tests, we are talking about test cases. In the case of non-parameterized test methods, that's the same as the number of methods. Where there are parameters, we count the number of individual cases. +1. In general, when counting tests, we are talking about test cases. In the case of non-parameterized test methods, + that's the same as the number of methods. Where there are parameters, we count the number of individual cases. -2. When all the tests in an assembly are run, the total number of tests is the number of tests present in the assembly. When selection is made - either via the command line or through a Gui - we count only tests that are actually selected. Non-selected tests don't appear at all in the XML result file and are not taken into account by the counts. +2. When all the tests in an assembly are run, the total number of tests is the number of tests present in the assembly. + When selection is made - either via the command line or through a Gui - we count only tests that are actually + selected. Non-selected tests don't appear at all in the XML result file and are not taken into account by the counts. 3. Tests are categorized in one of four statuses: Passed, Failed, Inconclusive and Skipped. @@ -26,10 +30,13 @@ Counting tests sounds simple but there are a few issues. This page documents how 4. Users may define new ResultStates in any of the four statuses. -5. Failures, errors, skipping or ignoring in the SetUp for a test counts the same as if the action happened in the test method itself. +5. Failures, errors, skipping or ignoring in the SetUp for a test counts the same as if the action happened in the test + method itself. -6. When fixtures are ignored or otherwise skipped using an attribute on the class, all tests within the fixture are given the corresponding result. +6. When fixtures are ignored or otherwise skipped using an attribute on the class, all tests within the fixture are + given the corresponding result. -7. Failures, errors, skipping or ignoring in the OneTimeSetUp for a fixture causes all the test cases in the fixture to get the corresponding result. +7. Failures, errors, skipping or ignoring in the OneTimeSetUp for a fixture causes all the test cases in the fixture to + get the corresponding result. 8. An invalid fixture causes all of its test cases to count as invalid. diff --git a/docs/articles/nunit/technical-notes/usage/Engine-Parallel-Test-Execution.md b/docs/articles/nunit/technical-notes/usage/Engine-Parallel-Test-Execution.md index 53a39ef0c..577fbbdd5 100644 --- a/docs/articles/nunit/technical-notes/usage/Engine-Parallel-Test-Execution.md +++ b/docs/articles/nunit/technical-notes/usage/Engine-Parallel-Test-Execution.md @@ -1,17 +1,28 @@ # Engine Parallel Test Execution -The NUnit test engine is able to offer a certain degree of parallelization by running the tests in each test assembly in a different `Process`. This is a separate facility from [Framework Parallel Test Execution](Framework-Parallel-Test-Execution.md) although the two may be used concurrently. +The NUnit test engine is able to offer a certain degree of parallelization by running the tests in each test assembly in +a different `Process`. This is a separate facility from [Framework Parallel Test +Execution](Framework-Parallel-Test-Execution.md) although the two may be used concurrently. -If tests are already split across multiple assemblies, this is the simplest way to improve performance through parallel execution. By running in separate processes, the tests in each assembly are independent of one another so long as they do not use any common external resources such as files or databases. **Parallel execution is the default behavior** when running multiple assemblies together using the `nunit3-console` runner. +If tests are already split across multiple assemblies, this is the simplest way to improve performance through parallel +execution. By running in separate processes, the tests in each assembly are independent of one another so long as they +do not use any common external resources such as files or databases. **Parallel execution is the default behavior** when +running multiple assemblies together using the `nunit3-console` runner. -Normally, **all** the test processes run simultaneously. If you need to reduce the number of processes allowed to run at one time, you may specify a value for the `--agents` option on the `nunit3-console` command-line. For example, if you are running tests in 10 different processes, a setting of `--agents=3` will allow no more than three of them to execute simultaneously. +Normally, **all** the test processes run simultaneously. If you need to reduce the number of processes allowed to run at +one time, you may specify a value for the `--agents` option on the `nunit3-console` command-line. For example, if you +are running tests in 10 different processes, a setting of `--agents=3` will allow no more than three of them to execute +simultaneously. > [!NOTE] -> This facility does not depend on the test framework used in any way. Test assemblies that use older versions of NUnit may be run in parallel processes just as easily as those using NUnit 3. If extensions are created to support additional frameworks, the NUnit engine will run those assemblies in parallel as well. +> This facility does not depend on the test framework used in any way. Test assemblies that use older versions +> of NUnit may be run in parallel processes just as easily as those using NUnit 3. If extensions are created to support +> additional frameworks, the NUnit engine will run those assemblies in parallel as well. ## Process Model -NUnit 3 uses the `ProcessModel` enumeration to specify how assemblies are split across processes. The `ProcessModel` for a run may specified either on the console command-line or in the NUnit project file. +NUnit 3 uses the `ProcessModel` enumeration to specify how assemblies are split across processes. The `ProcessModel` for +a run may specified either on the console command-line or in the NUnit project file. As in NUnit V2, three values are defined: @@ -19,4 +30,5 @@ As in NUnit V2, three values are defined: * `ProcessModel.Separate` loads and runs all the tests in a single separate process. * `ProcessModel.Multiple` loads and runs each test assembly in a separate process. -In NUnit 3, if `ProcessModel.Multiple` is used, the processes are executed in parallel. This is also the default if the `ProcessModel` is not specified. +In NUnit 3, if `ProcessModel.Multiple` is used, the processes are executed in parallel. This is also the default if the +`ProcessModel` is not specified. diff --git a/docs/articles/nunit/technical-notes/usage/Framework-Parallel-Test-Execution.md b/docs/articles/nunit/technical-notes/usage/Framework-Parallel-Test-Execution.md index af6b68c87..f669a9765 100644 --- a/docs/articles/nunit/technical-notes/usage/Framework-Parallel-Test-Execution.md +++ b/docs/articles/nunit/technical-notes/usage/Framework-Parallel-Test-Execution.md @@ -1,16 +1,24 @@ # Framework Parallel Test Execution -The NUnit 3.0 framework can run tests in parallel within an assembly. This is a completely separate facility from [Engine Parallel Test Execution](Engine-Parallel-Test-Execution.md), although it is possible to use both in the same test run. +The NUnit 3.0 framework can run tests in parallel within an assembly. This is a completely separate facility from +[Engine Parallel Test Execution](Engine-Parallel-Test-Execution.md), although it is possible to use both in the same +test run. -By default, no parallel execution takes place. Attributes are used to indicate which tests may run in parallel and how they relate to other tests. +By default, no parallel execution takes place. Attributes are used to indicate which tests may run in parallel and how +they relate to other tests. ## Platform Support -Parallel execution is supported by the NUnit framework on desktop .NET runtimes and .NET Standard 2.0. It is not supported in the .NET Standard 1.6 build, although the attributes are recognized without error in order to allow use in projects that build against multiple targets. +Parallel execution is supported by the NUnit framework on desktop .NET runtimes and .NET Standard 2.0. It is not +supported in the .NET Standard 1.6 build, although the attributes are recognized without error in order to allow use in +projects that build against multiple targets. ## ParallelizableAttribute -This attribute is used to indicate whether the test and/or its descendants may be run in parallel with other tests. The constructor takes an optional `ParallelScope` enumeration argument (see below), which defaults to `ParallelScope.Self`. The attribute may be used at the assembly, class or method level and the word "test" in the rest of this description refers to the suite or test case that corresponds to the item on which the attribute appears. +This attribute is used to indicate whether the test and/or its descendants may be run in parallel with other tests. The +constructor takes an optional `ParallelScope` enumeration argument (see below), which defaults to `ParallelScope.Self`. +The attribute may be used at the assembly, class or method level and the word "test" in the rest of this description +refers to the suite or test case that corresponds to the item on which the attribute appears. One Named Property is supported: @@ -18,44 +26,69 @@ One Named Property is supported: ## NonParallelizableAttribute -This Attribute is used to indicate that the test as well as its descendants may __not__ be run in parallel with other tests. Although `[NonParallelizable]` is completely equivalent to `[Parallelizable(ParallelScope.None)]`, we recommend that you use the former for clarity. +This Attribute is used to indicate that the test as well as its descendants may __not__ be run in parallel with other +tests. Although `[NonParallelizable]` is completely equivalent to `[Parallelizable(ParallelScope.None)]`, we recommend +that you use the former for clarity. ## ParallelScope Enumeration -This is a `[Flags]` type enumeration used to specify which tests may run in parallel. It applies to the test upon which it appears and any subordinate tests. The following values are available for use: +This is a `[Flags]` type enumeration used to specify which tests may run in parallel. It applies to the test upon which +it appears and any subordinate tests. The following values are available for use: -* `ParallelScope.Self` indicates that the test itself may be run in parallel with other tests. This is the default for the `ParallelizableAttribute` and is the only value permitted on a test method. -* `ParallelScope.Children` indicates that the descendants of the test may be run in parallel with respect to one another. -* `ParallelScope.Fixtures` indicates that test fixtures that are the descendants of the test may be run in parallel with one another.` +* `ParallelScope.Self` indicates that the test itself may be run in parallel with other tests. This is the default for + the `ParallelizableAttribute` and is the only value permitted on a test method. +* `ParallelScope.Children` indicates that the descendants of the test may be run in parallel with respect to one + another. +* `ParallelScope.Fixtures` indicates that test fixtures that are the descendants of the test may be run in parallel with + one another.` > [!NOTE] -> Additional values of the enumerator are used internally. They do not show up in the Intellisense and are not documented here. The value `ParallelScope.None`, which was used before the creation of the `NonParallelizableAttribute` is still accepted for the purpose of backward compatibility. +> Additional values of the enumerator are used internally. They do not show up in the Intellisense and are not +> documented here. The value `ParallelScope.None`, which was used before the creation of the +> `NonParallelizableAttribute` is still accepted for the purpose of backward compatibility. ## Specifying Parallelism at Multiple Test Levels -`[Parallelizable]` or `[NonParallelizable]` may be specified on multiple levels of the tests, with lower-level specifications overriding higher ones to a certain degree. Thus, if the assembly has `[NonParallelizable]` either by use of the attribute or by default, classes with `[Parallelizable]` may be run in parallel as may their children if an appropriate scope is used. +`[Parallelizable]` or `[NonParallelizable]` may be specified on multiple levels of the tests, with lower-level +specifications overriding higher ones to a certain degree. Thus, if the assembly has `[NonParallelizable]` either by use +of the attribute or by default, classes with `[Parallelizable]` may be run in parallel as may their children if an +appropriate scope is used. -It is important to note that a parallel or non-parallel specification only applies at that level where it appears and below. It cannot override the settings on higher-level tests. In this way, parallelism is not absolute but is relative to other tests at the same level in the tree. The following are a few examples of how this works: +It is important to note that a parallel or non-parallel specification only applies at that level where it appears and +below. It cannot override the settings on higher-level tests. In this way, parallelism is not absolute but is relative +to other tests at the same level in the tree. The following are a few examples of how this works: -1. __Non-parallel class with parallel methods:__ The methods only run in parallel with one another, not with the test methods of any other classes. +1. __Non-parallel class with parallel methods:__ The methods only run in parallel with one another, not with the test + methods of any other classes. -2. __Parallel class with non-parallel methods:__ The methods run sequentially, usually on the same thread that ran the class one-time setup, but may actually be running in parallel with other, unrelated methods from other classes. +2. __Parallel class with non-parallel methods:__ The methods run sequentially, usually on the same thread that ran the + class one-time setup, but may actually be running in parallel with other, unrelated methods from other classes. -3. __Non-parallel SetUpFixture with parallel test fixtures:__ The entire group of fixtures runs separately from any fixtures outside the group. Within the group, multiple fixtures run in parallel. +3. __Non-parallel SetUpFixture with parallel test fixtures:__ The entire group of fixtures runs separately from any + fixtures outside the group. Within the group, multiple fixtures run in parallel. -4. __Parallel SetUpFixture with non-parallel test fixtures:__ The group runs in parallel with other fixtures and groups. Within the group, only one fixture at a time may execute. +4. __Parallel SetUpFixture with non-parallel test fixtures:__ The group runs in parallel with other fixtures and groups. + Within the group, only one fixture at a time may execute. -5. __Parallel SetUpFixture with non-parallel test fixtures containing parallel test cases:__ This is just one example of a more complex setup. The fixtures themselves run as described in (4) but the cases within each fixture run in parallel with one another. +5. __Parallel SetUpFixture with non-parallel test fixtures containing parallel test cases:__ This is just one example of + a more complex setup. The fixtures themselves run as described in (4) but the cases within each fixture run in + parallel with one another. Once you understand the principles, you can construct complex hierarchies of parallel and non-parallel tests. ## LevelOfParallelismAttribute -This is an __assembly-level__ attribute, which may be used to specify the level of parallelism, that is, the maximum number of worker threads executing tests in this assembly. It may be overridden using a command-line option in the console runner. If it is not specified, NUnit uses a default value based on the number of processors available or a specified minimum, whichever is greater. +This is an __assembly-level__ attribute, which may be used to specify the level of parallelism, that is, the maximum +number of worker threads executing tests in this assembly. It may be overridden using a command-line option in the +console runner. If it is not specified, NUnit uses a default value based on the number of processors available or a +specified minimum, whichever is greater. ## Parallel Execution Internals -We use multiple queues organized into "shifts". A `WorkShift` consists of one or more queues of work items, which may be active at the same time. As the name suggests, no two shifts are active simultaneously. NUnit runs one `WorkShift` until all available work is complete and then switches to the next shift. When there is no work for any shift, the run is complete. +We use multiple queues organized into "shifts". A `WorkShift` consists of one or more queues of work items, which may be +active at the same time. As the name suggests, no two shifts are active simultaneously. NUnit runs one `WorkShift` until +all available work is complete and then switches to the next shift. When there is no work for any shift, the run is +complete. There are three shifts, listed here with their associated queues... @@ -68,8 +101,11 @@ There are three shifts, listed here with their associated queues... (* Depends on Level of Parallelism) -For efficiency, each queue is created when the first test is added to it. At the time of creation, all workers for that queue are also created and initialized. +For efficiency, each queue is created when the first test is added to it. At the time of creation, all workers for that +queue are also created and initialized. -Whenever a non-parallel fixture begins execution, an entirely new set of queues is created so that the child tests of that fixture may be run without any conflict from other tests that are already in the main set of queues. +Whenever a non-parallel fixture begins execution, an entirely new set of queues is created so that the child tests of +that fixture may be run without any conflict from other tests that are already in the main set of queues. -If the command line specifies zero workers, all use of the dispatcher and its queues is bypassed and tests are run sequentially on a single thread. +If the command line specifies zero workers, all use of the dispatcher and its queues is bypassed and tests are run +sequentially on a single thread. diff --git a/docs/articles/nunit/technical-notes/usage/NUnit-Project-XML-Format.md b/docs/articles/nunit/technical-notes/usage/NUnit-Project-XML-Format.md index 2947639a5..5753d89be 100644 --- a/docs/articles/nunit/technical-notes/usage/NUnit-Project-XML-Format.md +++ b/docs/articles/nunit/technical-notes/usage/NUnit-Project-XML-Format.md @@ -19,26 +19,53 @@ Contains global settings that apply to all configurations in the project. May be * **Containing Element:** [``](#nunitproject) * **Contained Elements:** None * **Attributes:** - * `activeconfig` The name of the config to use if none is specified by the user. Using `nunit-console`, you may override this through the `--config` command-line option. - * `appbase` The application base to use in loading and running tests. Defaults to the location of the .nunit project file. If the path is relative, as it normally is, it is taken as relative to the location of the project file. - * `processModel` Specifies how NUnit should create processes for executing test assemblies. Possible values are: Default, Single (no separate processes are created), Separate (tests are run in a single, separate process) and Multiple (each assembly is run in its own separate process). The default value is Multiple, provided there are multiple assemblies, otherwise Separate. - * `domainUsage` Specifies how NUnit should create AppDomains within each process for running tests. Possible values are: Default, None (no domain is created), Single (a single domain is created) and Multiple (a separate domain is created for each assembly). The default is Multiple if multiple assemblies are run in the same process, Single if only one assembly is run in a process. + * `activeconfig` The name of the config to use if none is specified by the user. Using `nunit-console`, you may + override this through the `--config` command-line option. + * `appbase` The application base to use in loading and running tests. Defaults to the location of the .nunit project + file. If the path is relative, as it normally is, it is taken as relative to the location of the project file. + * `processModel` Specifies how NUnit should create processes for executing test assemblies. Possible values are: + Default, Single (no separate processes are created), Separate (tests are run in a single, separate process) and + Multiple (each assembly is run in its own separate process). The default value is Multiple, provided there are + multiple assemblies, otherwise Separate. + * `domainUsage` Specifies how NUnit should create AppDomains within each process for running tests. Possible values + are: Default, None (no domain is created), Single (a single domain is created) and Multiple (a separate domain is + created for each assembly). The default is Multiple if multiple assemblies are run in the same process, Single if + only one assembly is run in a process. ## `` -Describes a specific configuration of the project. This may map to traditional compiler configs like `Debug` or `Release` or may be used to specify any arbitrary collection of assemblies to be tested together. At least one configuration should be specified or the project will not be usable. +Describes a specific configuration of the project. This may map to traditional compiler configs like `Debug` or +`Release` or may be used to specify any arbitrary collection of assemblies to be tested together. At least one +configuration should be specified or the project will not be usable. * **Containing Element:** [``](#nunitproject) * **Contained Elements:** [``](#assembly) * **Attributes:** * `name` The name of this configuration. (Required) - * `appbase` The application base to use in loading and running tests under this config. Defaults to the appbase specified in the `` element. The path should normally be relative to that global application base or to the location of project file if there is no global appbase. - * `binpath` The probing path used to search for assemblies, consisting of a number of directory paths separated by semicolons. The directory paths should be relative to the application base and must be under it. Specifying this attribute automatically sets the `binpathtype` to 'manual'. - * `binpathtype` Indicates how the probing path is determined. Possible values are: Auto (the probing path is determined from the location of the test assemblies), Manual (the path is specified by the binpath attribute) and None (no probing path is used). It is an error to specify a value other than Manual if the `binpath` attribute is also used. - * `configfile` Specifies the path to a config file to be used when running tests under this configuration. The path is relative to the application base. - * `processModel` Specifies how NUnit should create processes for executing test assemblies under this configuration. Possible values are: Default, Single (no separate processes are created), Separate (tests are run in a single, separate process) and Multiple (each assembly is run in its own separate process). The default is the value specified globally or Multiple if nothing has been specified. - * `domainUsage` Specifies how NUnit should create AppDomains within each process for running tests under this configuration. Possible values are: Default, None (no domain is created), Single (a single domain is created) and Multiple (a separate domain is created for each assembly). The default is the value specified globally, if provided, otherwise Multiple if multiple assemblies are run in the same process, Single if only one assembly is run in a process. - * `runtimeFramework` Specifies a runtime framework to be used in running tests. Abbreviations are the same as those accepted by the nunit-console command-line. If none is specified, tests are run under the target runtime specified when the assembly was compiled. + * `appbase` The application base to use in loading and running tests under this config. Defaults to the appbase + specified in the `` element. The path should normally be relative to that global application base or to + the location of project file if there is no global appbase. + * `binpath` The probing path used to search for assemblies, consisting of a number of directory paths separated by + semicolons. The directory paths should be relative to the application base and must be under it. Specifying this + attribute automatically sets the `binpathtype` to 'manual'. + * `binpathtype` Indicates how the probing path is determined. Possible values are: Auto (the probing path is + determined from the location of the test assemblies), Manual (the path is specified by the binpath attribute) and + None (no probing path is used). It is an error to specify a value other than Manual if the `binpath` attribute is + also used. + * `configfile` Specifies the path to a config file to be used when running tests under this configuration. The path is + relative to the application base. + * `processModel` Specifies how NUnit should create processes for executing test assemblies under this configuration. + Possible values are: Default, Single (no separate processes are created), Separate (tests are run in a single, + separate process) and Multiple (each assembly is run in its own separate process). The default is the value + specified globally or Multiple if nothing has been specified. + * `domainUsage` Specifies how NUnit should create AppDomains within each process for running tests under this + configuration. Possible values are: Default, None (no domain is created), Single (a single domain is created) and + Multiple (a separate domain is created for each assembly). The default is the value specified globally, if provided, + otherwise Multiple if multiple assemblies are run in the same process, Single if only one assembly is run in a + process. + * `runtimeFramework` Specifies a runtime framework to be used in running tests. Abbreviations are the same as those + accepted by the nunit-console command-line. If none is specified, tests are run under the target runtime specified + when the assembly was compiled. ## `` diff --git a/docs/articles/nunit/technical-notes/usage/Parameterized-Tests.md b/docs/articles/nunit/technical-notes/usage/Parameterized-Tests.md index 4e5f9e2f5..ced868e5e 100644 --- a/docs/articles/nunit/technical-notes/usage/Parameterized-Tests.md +++ b/docs/articles/nunit/technical-notes/usage/Parameterized-Tests.md @@ -4,20 +4,15 @@ uid: parameterizedtests # Parameterized Tests -NUnit supports parameterized tests. Test methods -may have parameters and various attributes are available -to indicate what arguments should be supplied by NUnit. - -Multiple sets of arguments cause the creation of multiple -tests. All arguments are created at the point of loading the -tests, so the individual test cases are available for -display and selection in the Gui, if desired. - -Some attributes allow you to specify arguments inline - directly on -the attribute - while others use a separate method, property or field -to hold the arguments. In addition, some attributes identify complete test cases, -including all the necessary arguments, while others only provide data -for a single argument. This gives rise to four groups of attributes, +NUnit supports parameterized tests. Test methods may have parameters and various attributes are available to indicate +what arguments should be supplied by NUnit. + +Multiple sets of arguments cause the creation of multiple tests. All arguments are created at the point of loading the +tests, so the individual test cases are available for display and selection in the Gui, if desired. + +Some attributes allow you to specify arguments inline - directly on the attribute - while others use a separate method, +property or field to hold the arguments. In addition, some attributes identify complete test cases, including all the +necessary arguments, while others only provide data for a single argument. This gives rise to four groups of attributes, as shown in the following table. | | Complete Test Cases | Data for One Argument | @@ -25,10 +20,8 @@ as shown in the following table. | **Inline** | [TestCase Attribute](xref:testcaseattribute) | [Random Attribute](xref:randomattribute), [Range Attribute](xref:rangeattribute), [Values Attribute](xref:valuesattribute) | | **Separate** | [TestCaseSource Attribute](xref:testcasesourceattribute) | [ValueSource Attribute](xref:valuesource) | -In addition, when data is specified for individual arguments, special attributes -may be added to the test method itself in order to tell NUnit how -to go about combining the arguments. Currently, the following attributes -are provided: +In addition, when data is specified for individual arguments, special attributes may be added to the test method itself +in order to tell NUnit how to go about combining the arguments. Currently, the following attributes are provided: * [Combinatorial Attribute](xref:combinatorialattribute) (default) * [Pairwise Attribute](xref:pairwiseattribute) @@ -36,12 +29,15 @@ are provided: ## Order of Execution -The individual test cases are executed in the order in which NUnit discovers them. -This order does **not** necessarily follow the lexical order of the attributes -and will often vary between different compilers or different versions of the CLR. +The individual test cases are executed in the order in which NUnit discovers them. This order does **not** necessarily +follow the lexical order of the attributes and will often vary between different compilers or different versions of the +CLR. The following specific rules for ordering apply: -* If all arguments are specified in a **single TestCaseSource** attribute, the ordering of the cases provided will be maintained. -* If each parameter has a single **Values**, **ValueSource** or **Range** attribute and the **Sequential** combining strategy is used - or there is only one argument - the ordering will be maintained. -* In all other cases, including using multiple **TestCase** attributes or a combination of different types of attributes, the ordering of the test cases is undefined. +* If all arguments are specified in a **single TestCaseSource** attribute, the ordering of the cases provided will be + maintained. +* If each parameter has a single **Values**, **ValueSource** or **Range** attribute and the **Sequential** combining + strategy is used - or there is only one argument - the ordering will be maintained. +* In all other cases, including using multiple **TestCase** attributes or a combination of different types of + attributes, the ordering of the test cases is undefined. diff --git a/docs/articles/nunit/technical-notes/usage/SetUp-and-TearDown.md b/docs/articles/nunit/technical-notes/usage/SetUp-and-TearDown.md index 6be0361a8..3c332e271 100644 --- a/docs/articles/nunit/technical-notes/usage/SetUp-and-TearDown.md +++ b/docs/articles/nunit/technical-notes/usage/SetUp-and-TearDown.md @@ -4,9 +4,12 @@ * [SetUpAttribute](xref:setup-attribute) is now used exclusively for per-test setup. * [TearDownAttribute](xref:teardown-attribute) is now used exclusively for per-test teardown. -* [OneTimeSetUpAttribute](xref:onetimesetup-attribute) is used for one-time setup per test-run. If you run _n_ tests, this event will only occur once. -* [OneTimeTearDownAttribute](xref:onetimeteardown-attribute) is used for one-time teardown per test-run. If you run _n_ tests, this event will only occur once -* [SetUpFixtureAttribute](xref:setupfixture-attribute) continues to be used as at before, but with changed method attributes. +* [OneTimeSetUpAttribute](xref:onetimesetup-attribute) is used for one-time setup per test-run. If you run _n_ tests, + this event will only occur once. +* [OneTimeTearDownAttribute](xref:onetimeteardown-attribute) is used for one-time teardown per test-run. If you run _n_ + tests, this event will only occur once +* [SetUpFixtureAttribute](xref:setupfixture-attribute) continues to be used as at before, but with changed method + attributes. ### Attribute Usage by Fixture Type @@ -23,9 +26,12 @@ Multiple SetUp, OneTimeSetUp, TearDown and OneTimeTearDown methods may exist within a class. -Setup methods (both types) are called on base classes first, then on derived classes. If any setup method throws an exception, no further setups are called. +Setup methods (both types) are called on base classes first, then on derived classes. If any setup method throws an +exception, no further setups are called. -Teardown methods (again, both types) are called on derived classes first, then on the base class. The teardown methods at any level in the inheritance hierarchy will be called only if a setup method **at the same level** was called. The following example is illustrates the difference. +Teardown methods (again, both types) are called on derived classes first, then on the base class. The teardown methods +at any level in the inheritance hierarchy will be called only if a setup method **at the same level** was called. The +following example is illustrates the difference. ```csharp public class BaseClass diff --git a/docs/articles/nunit/technical-notes/usage/Test-Filters.md b/docs/articles/nunit/technical-notes/usage/Test-Filters.md index 4e5bebac9..8811883a8 100644 --- a/docs/articles/nunit/technical-notes/usage/Test-Filters.md +++ b/docs/articles/nunit/technical-notes/usage/Test-Filters.md @@ -5,84 +5,96 @@ uid: testFilters # Test Filters -Test Filters represent a selection of tests to be displayed, run or loaded. When a filter needs to be passed to the framework, it is passed as a string containing an XML fragment. This page describes the elements present in the XML for a filter. +Test Filters represent a selection of tests to be displayed, run or loaded. When a filter needs to be passed to the +framework, it is passed as a string containing an XML fragment. This page describes the elements present in the XML for +a filter. ## `` -This is the required top-level element for any filter. If it contains no other elements, it represents an empty filter. If it contains just one element, that element is used as the filter for all tests. If it contains multiple elements, it works like an `` element. +This is the required top-level element for any filter. If it contains no other elements, it represents an empty filter. +If it contains just one element, that element is used as the filter for all tests. If it contains multiple elements, it +works like an `` element. -Child elements allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``. +Child elements allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, +``, ``. ## `` Represents an AndFilter. All contained filter elements must pass in order for this filter to pass. -Child elements allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``. +Child elements allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, +``, ``. ## `` Represents an OrFilter. At least one contained filter element must pass in order for this filter to pass. -Child elements allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``. +Child elements allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, +``, ``. ## `` Represents a NotFilter. The single contained filter element must fail in order for this filter to pass. -Child elements allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``. +Child elements allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, +``, ``. ## `` -Represents an IdFilter. The text of the element contains a single test id or multiple ids separated by commas. Since test ids are an internal construct, this filter is not useful externally. However, it is used by the NUnit Gui to efficiently select tests from the list of those loaded. +Represents an IdFilter. The text of the element contains a single test id or multiple ids separated by commas. Since +test ids are an internal construct, this filter is not useful externally. However, it is used by the NUnit Gui to +efficiently select tests from the list of those loaded. Child elements allowed: None. ## `` -Represents a selection by test name. The full name of the test is used as its inner text. -If the filter should use a regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. +Represents a selection by test name. The full name of the test is used as its inner text. If the filter should use a +regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. Child elements allowed: None. ## `` -Represents a CategoryFilter. The text of the element contains a single category. -If the filter should use a regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. +Represents a CategoryFilter. The text of the element contains a single category. If the filter should use a regular +expression for matching then the element should contain an attribute named `re` with the value `"1"`. Child elements allowed: None. ## `` -Represents a selection by class name. The fully qualified name of the class is used as its inner text. -If the filter should use a regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. +Represents a selection by class name. The fully qualified name of the class is used as its inner text. If the filter +should use a regular expression for matching then the element should contain an attribute named `re` with the value +`"1"`. Child elements allowed: None. ## `` -Represents a selection by method name. The name of the method is used as its inner text. -If the filter should use a regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. +Represents a selection by method name. The name of the method is used as its inner text. If the filter should use a +regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. Child elements allowed: None. ## `` -Represents a selection by namespace. The fully qualified name of the namespace is used as its inner text. -If the filter should use a regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. +Represents a selection by namespace. The fully qualified name of the namespace is used as its inner text. If the filter +should use a regular expression for matching then the element should contain an attribute named `re` with the value +`"1"`. Child elements allowed: None. ## `` -Represents a PropertyFilter. The element has an attribute `name` which specifies the name of the property. -The text of the element contains the value of the property. -If the filter should use a regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. +Represents a PropertyFilter. The element has an attribute `name` which specifies the name of the property. The text of +the element contains the value of the property. If the filter should use a regular expression for matching then the +element should contain an attribute named `re` with the value `"1"`. Child elements allowed: None. ## `` -Represents a selection by test name. The test name assigned by NUnit is used as its inner text. -If the filter should use a regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. +Represents a selection by test name. The test name assigned by NUnit is used as its inner text. If the filter should use +a regular expression for matching then the element should contain an attribute named `re` with the value `"1"`. Child elements allowed: None. diff --git a/docs/articles/nunit/technical-notes/usage/Test-Result-XML-Format.md b/docs/articles/nunit/technical-notes/usage/Test-Result-XML-Format.md index ba242cc7f..7d819a0f4 100644 --- a/docs/articles/nunit/technical-notes/usage/Test-Result-XML-Format.md +++ b/docs/articles/nunit/technical-notes/usage/Test-Result-XML-Format.md @@ -14,7 +14,8 @@ The required root element for any NUnit 3.0 test result file. * **id** The unique ID of this test. * **testcasecount** The number of test cases contained in this test run. * **result** The basic result of the test. May be Passed, Failed, Inconclusive or Skipped. - * **total** The total number of test cases executed in the run. This may be less than the testcasecount due to filtering of tests. + * **total** The total number of test cases executed in the run. This may be less than the testcasecount due to + filtering of tests. * **passed** The number of test cases that passed. * **failed** The number of test cases that failed. * **inconclusive** The number of test cases that were inconclusive. @@ -36,34 +37,42 @@ Holds a CDATA section containing the text of the command used to run the tests. ## `` -The XML representation of the filter used to execute tests. This element is also used as a fragment in passing the filter to a runner and by the NUnit 3.0 framework and driver. +The XML representation of the filter used to execute tests. This element is also used as a fragment in passing the +filter to a runner and by the NUnit 3.0 framework and driver. * **Containing Elements:** [``](#test-run) -* **Contained Elements:** [``](#or), [``](#and), [``](#not), [``](#id), [``](#test), [``](#class), [``](#method), [``](#cat) +* **Contained Elements:** [``](#or), [``](#and), [``](#not), [``](#id), [``](#test), + [``](#class), [``](#method), [``](#cat) * **Attributes:** None ## `` -Represents a composite filter that contains other filters. At least one of the contained filters must pass in order for this filter to pass. +Represents a composite filter that contains other filters. At least one of the contained filters must pass in order for +this filter to pass. * **Containing Elements:** [``](#filter), [``](#or), [``](#and), [``](#not) -* **Contained Elements:** [``](#or), [``](#and), [``](#not), [``](#id), [``](#test), [``](#class), [``](#method), [``](#cat), [``](#prop) +* **Contained Elements:** [``](#or), [``](#and), [``](#not), [``](#id), [``](#test), + [``](#class), [``](#method), [``](#cat), [``](#prop) * **Attributes:** None ## `` -Represents a composite filter that contains other filters. All of the contained filters must pass in order for this filter to pass. +Represents a composite filter that contains other filters. All of the contained filters must pass in order for this +filter to pass. * **Containing Elements:** [``](#filter), [``](#or), [``](#and), [``](#not) -* **Contained Elements:** [``](#or), [``](#and), [``](#not), [``](#id), [``](#test), [``](#class), [``](#method), [``](#cat), [``](#prop) +* **Contained Elements:** [``](#or), [``](#and), [``](#not), [``](#id), [``](#test), + [``](#class), [``](#method), [``](#cat), [``](#prop) * **Attributes:** None ## `` -Represents a composite filter that contains wraps a single base filters. The base filter must fail in order for this filter to pass. +Represents a composite filter that contains wraps a single base filters. The base filter must fail in order for this +filter to pass. * **Containing Elements:** [``](#filter), [``](#or), [``](#and), [``](#not) -* **Contained Elements:** [``](#or), [``](#and), [``](#not), [``](#id), [``](#test), [``](#class), [``](#method), [``](#cat), [``](#prop) +* **Contained Elements:** [``](#or), [``](#and), [``](#not), [``](#id), [``](#test), + [``](#class), [``](#method), [``](#cat), [``](#prop) * **Attributes:** None ## `` @@ -112,18 +121,31 @@ Represents a filter that examines the test id, which is generated by NUnit. ## `` * **Containing Elements:** [``](#test-run), [``](#test-suite) -* **Contained Elements:** [``](#environment), [``](#settings), [``](#properties), [``](#reason), [``](#failure), [``](#output), [``](#attachments), [``](#test-suite), [``](#test-case) +* **Contained Elements:** [``](#environment), [``](#settings), [``](#properties), + [``](#reason), [``](#failure), [``](#output), [``](#attachments), + [``](#test-suite), [``](#test-case) * **Attributes** - * **type** The type of suite represented by this element. Currently supported types are Project, Assembly, TestSuite, TestFixture, GenericFixture, ParameterizedFixture, SetUpFixture, GenericMethod, ParameterizedMethod, Theory. - * **id** The unique id of this test. Coded as "mmm-nnn" where the part before the hyphen represents the assembly and the part after it represents a test in that assembly. Currently, mmm and nnn are ints, but that is merely an accident of the implementation and should not be relied on. + * **type** The type of suite represented by this element. Currently supported types are Project, Assembly, TestSuite, + TestFixture, GenericFixture, ParameterizedFixture, SetUpFixture, GenericMethod, ParameterizedMethod, Theory. + * **id** The unique id of this test. Coded as "mmm-nnn" where the part before the hyphen represents the assembly and + the part after it represents a test in that assembly. Currently, mmm and nnn are ints, but that is merely an + accident of the implementation and should not be relied on. * **name** The display name of the test as generated by NUnit. * **fullname** The full name of the test as generated by NUnit. - * **classname** The full name of the class (fixture) representing this test. Only present if `type` is equal to "TestFixture". + * **classname** The full name of the class (fixture) representing this test. Only present if `type` is equal to + "TestFixture". * **testcasecount** The number of test cases contained, directly or indirectly, in this suite. - * **runstate** An indicator of whether the suite is runnable. Value may be NotRunnable, Runnable, Explicit, Skipped or Ignored. NotRunnable means there is an error in how the test is expressed in code, for example, the signature may be wrong. Explicit, Skipped and Ignored are set by attributes on the test. + * **runstate** An indicator of whether the suite is runnable. Value may be NotRunnable, Runnable, Explicit, Skipped or + Ignored. NotRunnable means there is an error in how the test is expressed in code, for example, the signature may be + wrong. Explicit, Skipped and Ignored are set by attributes on the test. * **result** The basic result of the test. May be Passed, Failed, Inconclusive or Skipped. - * **label** Additional labeling information about the result. In principle, this may be any string value and is combined with the result to give a more precise reason for failure. Currently, NUnit may use the following labels in combination with the Failure result: Error, Cancelled or Invalid. It may use the following labels in combination with a Skipped result: Ignored or Explicit. Additional values may be added in future releases or supplied by extensions, so code that processes a result file should be prepared to deal with any label or none at all. - * **site** Optional element indicating where a failure occurred. Values are Test, SetUp, TearDown, Parent or Child. Default is Test and the attribute does not normally appear in that case. + * **label** Additional labeling information about the result. In principle, this may be any string value and is + combined with the result to give a more precise reason for failure. Currently, NUnit may use the following labels in + combination with the Failure result: Error, Cancelled or Invalid. It may use the following labels in combination + with a Skipped result: Ignored or Explicit. Additional values may be added in future releases or supplied by + extensions, so code that processes a result file should be prepared to deal with any label or none at all. + * **site** Optional element indicating where a failure occurred. Values are Test, SetUp, TearDown, Parent or Child. + Default is Test and the attribute does not normally appear in that case. * **start-time** The UTC time that the suite started. * **end-time** The UTC time that the suite ended. * **duration** The duration of the suite in seconds, expressed as a real number. @@ -132,7 +154,9 @@ Represents a filter that examines the test id, which is generated by NUnit. * **failed** The number of test cases that failed. * **inconclusive** The number of test cases that were inconclusive. * **skipped** The number of test cases that were skipped. - * **asserts** The number of asserts executed by the suite, including any nested suites or test cases. Since asserts may be executed in OneTimeSetUp and in ActionAttributes, this number can be greater than the total of the asserts for the test cases. + * **asserts** The number of asserts executed by the suite, including any nested suites or test cases. Since asserts + may be executed in OneTimeSetUp and in ActionAttributes, this number can be greater than the total of the asserts + for the test cases. ## `` @@ -155,8 +179,8 @@ Describes the environment in which the tests in a particular assembly are being ## `` -Settings used by the engine for executing an assembly. These are taken from the supplied settings in the -`TestPackage` supplemented by default settings created by the engine itself. +Settings used by the engine for executing an assembly. These are taken from the supplied settings in the `TestPackage` +supplemented by default settings created by the engine itself. * **Containing Elements:** [``](#test-suite) _(Assembly level only)_ * **Contained Elements:** [``](#setting) @@ -175,18 +199,29 @@ A single setting ## `` * **Containing Elements:** [``](#test-suite) -* **Contained Elements:** [``](#properties), [``](#reason), [``](#failure), [``](#output), [``](#attachments) +* **Contained Elements:** [``](#properties), [``](#reason), [``](#failure), + [``](#output), [``](#attachments) * **Attributes** - * `id` The unique id of this test. Coded as "mmm-nnn" where the part before the hyphen represents the assembly and the part after it represents a test in that assembly. Currently, mmm and nnn are ints, but that is merely an accident of the implementation and should not be relied on. - * `name` The display name of the test as generated by NUnit or, in the case of some parameterized tests, specified by the user. + * `id` The unique id of this test. Coded as "mmm-nnn" where the part before the hyphen represents the assembly and the + part after it represents a test in that assembly. Currently, mmm and nnn are ints, but that is merely an accident of + the implementation and should not be relied on. + * `name` The display name of the test as generated by NUnit or, in the case of some parameterized tests, specified by + the user. * `fullname` The full name of the test as generated by NUnit. * `methodname` The name of the method representing the test case. * `classname` The full name of the class in which this test case appears. - * `runstate` An indicator of whether the suite is runnable. Value may be NotRunnable, Runnable, Explicit, Skipped or Ignored. NotRunnable means there is an error in how the test is expressed in code, for example, the signature may be wrong. Explicit, Skipped and Ignored are set by attributes on the test. + * `runstate` An indicator of whether the suite is runnable. Value may be NotRunnable, Runnable, Explicit, Skipped or + Ignored. NotRunnable means there is an error in how the test is expressed in code, for example, the signature may be + wrong. Explicit, Skipped and Ignored are set by attributes on the test. * `seed` The seed used to generate random arguments and other values for this test. * `result` The basic result of the test. May be Passed, Failed, Inconclusive or Skipped. - * `label` Additional labeling information about the result. In principle, this may be any string value and is combined with the result to give a more precise reason for failure. Currently, NUnit may use the following labels in combination with the Failure result: Error, Cancelled or Invalid. It may use the following labels in combination with a Skipped result: Ignored or Explicit. Additional values may be added in future releases or supplied by extensions, so code that processes a result file should be prepared to deal with any label or none at all. - * `site` Optional element indicating where a failure occurred. Values are Test, SetUp, TearDown, Parent or Child. Default is Test and the attribute does not normally appear in that case. + * `label` Additional labeling information about the result. In principle, this may be any string value and is combined + with the result to give a more precise reason for failure. Currently, NUnit may use the following labels in + combination with the Failure result: Error, Cancelled or Invalid. It may use the following labels in combination + with a Skipped result: Ignored or Explicit. Additional values may be added in future releases or supplied by + extensions, so code that processes a result file should be prepared to deal with any label or none at all. + * `site` Optional element indicating where a failure occurred. Values are Test, SetUp, TearDown, Parent or Child. + Default is Test and the attribute does not normally appear in that case. * `start-time` The UTC time that the test started. * `end-time` The UTC time that the test ended. * `duration` The duration of the test in seconds, expressed as a real number. @@ -212,7 +247,9 @@ A single property ## `` -Optional element that may appear on tests or suites that were not executed. The element may also appear on tests that were short circuited using `Assert.Pass`. Contains a message giving the reason for skipping or short circuiting the test. +Optional element that may appear on tests or suites that were not executed. The element may also appear on tests that +were short circuited using `Assert.Pass`. Contains a message giving the reason for skipping or short circuiting the +test. * **Containing Elements:** [``](#test-suite), [``](#test-case) * **Contained Elements:** [``](#message) @@ -220,7 +257,8 @@ Optional element that may appear on tests or suites that were not executed. The ## `` -Optional element that appears on all tests or suites with a result of 'Failed'. Optionally contains the error message and/or a stack trace. +Optional element that appears on all tests or suites with a result of 'Failed'. Optionally contains the error message +and/or a stack trace. * **Containing Elements:** [``](#test-suite), [``](#test-case) * **Contained Elements:** [``](#message), [``](#stack-trace) @@ -257,7 +295,8 @@ Optional element with a CDATA section containing a stack-trace of the location w ## `` -Optional element that appears on tests or suites that produce text output. The output may be intercepted from writes to the console or captured directly when the test writes to the TestContext. It is contained in a CDATA section. +Optional element that appears on tests or suites that produce text output. The output may be intercepted from writes to +the console or captured directly when the test writes to the TestContext. It is contained in a CDATA section. * **Containing Elements:** [``](#test-suite), [``](#test-case) * **Contained Elements:** None diff --git a/docs/articles/nunit/technical-notes/usage/Visual-Studio-Support.md b/docs/articles/nunit/technical-notes/usage/Visual-Studio-Support.md index 9868c0362..092438003 100644 --- a/docs/articles/nunit/technical-notes/usage/Visual-Studio-Support.md +++ b/docs/articles/nunit/technical-notes/usage/Visual-Studio-Support.md @@ -7,50 +7,44 @@ uid: visualstudiosupport > [!WARNING] > This is a draft. The contents may be out of date. -NUnit supports the Visual Studio project and solution format, which are also -used by a number of other IDEs. +NUnit supports the Visual Studio project and solution format, which are also used by a number of other IDEs. ## Running From Within Visual Studio -The most convenient way to do this is to set up a custom tool entry specifying the path to -NUnit as the command. For a VS2003 C# project, you can use $(TargetPath) for the arguments and -$(TargetDir) for the initial directory. +The most convenient way to do this is to set up a custom tool entry specifying the path to NUnit as the command. For a +VS2003 C# project, you can use $(TargetPath) for the arguments and $(TargetDir) for the initial directory. -With Visual Studio VS2005 this becomes a bit harder, because that release changed the -meaning of the 'Target' macros so they now point to the intermediate 'obj' directories rather -than the final output in one of the 'bin' directories. Here are some alternatives that -work in both versions: +With Visual Studio VS2005 this becomes a bit harder, because that release changed the meaning of the 'Target' macros so +they now point to the intermediate 'obj' directories rather than the final output in one of the 'bin' directories. Here +are some alternatives that work in both versions: -* **$(ProjectDir)$(ProjectFileName)** to open the VS Project rather than the assembly. - If you use this approach, be sure to rename your config file accordingly and put it in the same directory as the VS project file. -* **$(ProjectDir)bin/Debug/$(TargetName)$(TargetExt)** to run the assembly directly. - Note that this requires hard-coding part of the path, including the configuration. +* **$(ProjectDir)$(ProjectFileName)** to open the VS Project rather than the assembly. If you use this approach, be sure + to rename your config file accordingly and put it in the same directory as the VS project file. +* **$(ProjectDir)bin/Debug/$(TargetName)$(TargetExt)** to run the assembly directly. Note that this requires hard-coding + part of the path, including the configuration. -If you would like to debug your tests, use the Visual Studio -Debug | Processes… menu item to attach to NUnit after starting it and set breakpoints in -your test code as desired before running the tests. +If you would like to debug your tests, use the Visual Studio Debug | Processes… menu item to attach to NUnit after +starting it and set breakpoints in your test code as desired before running the tests. ## Opening Visual Studio Projects -When Visual Studio support is enabled, the File Open dialog displays the following supported -Visual Studio project types: C#, VB.Net, J# and C++. The project file is read and the -configurations and output assembly locations are identified. Since the project files do not contain -information about the most recently opened configuration, the output assembly for the first -configuration found (usually Debug) is loaded in the GUI. The tree shows the project as the top-level -node with the assembly shown as its descendant. +When Visual Studio support is enabled, the File Open dialog displays the following supported Visual Studio project +types: C#, VB.Net, J# and C++. The project file is read and the configurations and output assembly locations are +identified. Since the project files do not contain information about the most recently opened configuration, the output +assembly for the first configuration found (usually Debug) is loaded in the GUI. The tree shows the project as the +top-level node with the assembly shown as its descendant. -When tests are run for a Visual studio project, they run just as if the output assembly had been -loaded with one exception. The default location for the config file is the directory containing the -project file and its default name is the same as the project file with an extension of .config. -For example, the following command would load the tests in the nunit.tests assembly using the -configuration file nunit.tests.dll.config located in the same directory as the dll. +When tests are run for a Visual studio project, they run just as if the output assembly had been loaded with one +exception. The default location for the config file is the directory containing the project file and its default name is +the same as the project file with an extension of .config. For example, the following command would load the tests in +the nunit.tests assembly using the configuration file nunit.tests.dll.config located in the same directory as the dll. ```cmd nunit.exe nunit.tests.dll ``` -On the other hand, the following command would load the tests using the configuration file -nunit.tests.config located in the same directory as the csproj file. +On the other hand, the following command would load the tests using the configuration file nunit.tests.config located in +the same directory as the csproj file. ```cmd nunit.exe nunit.tests.csproj @@ -60,12 +54,11 @@ The same consideration applies to running tests using the console runner. ## Opening Visual Studio Solutions -When Visual Studio support is enabled, solution files may be opened as well. All the output -assemblies from contained projects of the types supported will be loaded in the tree. In the case -where all contained projects are located in the subdirectories beneath the solution, it will be -possible to load and run tests using this method directly. +When Visual Studio support is enabled, solution files may be opened as well. All the output assemblies from contained +projects of the types supported will be loaded in the tree. In the case where all contained projects are located in the +subdirectories beneath the solution, it will be possible to load and run tests using this method directly. -When a solution contains projects located elsewhere in the file system, it may not be possible to -run the tests - although the solution will generally load without problem. In this case, the Project -Editor should be use to modify and save the NUnit test project so that there is all referenced -assemblies are located in or beneath the application base directory. +When a solution contains projects located elsewhere in the file system, it may not be possible to run the tests - +although the solution will generally load without problem. In this case, the Project Editor should be use to modify and +save the NUnit test project so that there is all referenced assemblies are located in or beneath the application base +directory. diff --git a/docs/articles/nunit/technical-notes/usage/XML-Formats.md b/docs/articles/nunit/technical-notes/usage/XML-Formats.md index a4386a4fa..1a4d82134 100644 --- a/docs/articles/nunit/technical-notes/usage/XML-Formats.md +++ b/docs/articles/nunit/technical-notes/usage/XML-Formats.md @@ -7,29 +7,35 @@ uid: xmlformats > [!WARNING] > This is a draft. The contents may be out of date. -Use of XML in NUnit 2.x is somewhat limited and is only used in external files. NUnit 3.0 uses XML in several of its interfaces for communicating between its three architectural layers. +Use of XML in NUnit 2.x is somewhat limited and is only used in external files. NUnit 3.0 uses XML in several of its +interfaces for communicating between its three architectural layers. -The samples given here represent the current state of the application and are subject to change. Watch this page for new information as development continues. +The samples given here represent the current state of the application and are subject to change. Watch this page for new +information as development continues. ## NUnit Projects -An NUnit project is stored as a file with the extension .nunit and describes one or more test assemblies to be executed, together with certain parameters used in running them. No schema is used for this file. +An NUnit project is stored as a file with the extension .nunit and describes one or more test assemblies to be executed, +together with certain parameters used in running them. No schema is used for this file. * [Sample NUnit Project](https://nunit.org/files/nunit_project_25.txt) -Currently, the format is the same as for NUnit 2.x but it is likely to change as the project proceeds. Note that NUnitLite does not use or recognize NUnit projects, but only assemblies. +Currently, the format is the same as for NUnit 2.x but it is likely to change as the project proceeds. Note that +NUnitLite does not use or recognize NUnit projects, but only assemblies. For details of the file contents, see [NUnit Project XML Format](xref:nunitprojectxmlformat) ## NUnit Settings -The NUnitSettings30.xml file holds default settings for NUnit 3.0. No schema is used for this file. The format is the same as for 2.x but new settings may be added and the names of certain keys are likely to change. +The NUnitSettings30.xml file holds default settings for NUnit 3.0. No schema is used for this file. The format is the +same as for 2.x but new settings may be added and the names of certain keys are likely to change. * [Sample NUnit Settings File](https://nunit.org/files/sample_nunitsettings_file.txt) ## Test Results -The results of an test run are saved in a file with the default name of TestResult.xml. The schema of this file is being modified substantially for NUnit 3.0. +The results of an test run are saved in a file with the default name of TestResult.xml. The schema of this file is being +modified substantially for NUnit 3.0. * [Sample](https://nunit.org/files/testresult_30.txt) * Schema not yet available @@ -38,29 +44,35 @@ For details of the file layout see [Test Result XML Format](Test-Result-XML-Form ## V2 Test Results -Optionally, NUnit 3.0 is able to save results in the NUnit 2.x format for use with CI servers that do not yet understand the new format. +Optionally, NUnit 3.0 is able to save results in the NUnit 2.x format for use with CI servers that do not yet understand +the new format. * [Sample](https://nunit.org/files/testresult_25.txt) * [Schema](https://nunit.org/files/testresult_schema_25.txt) ## Test Representation -When using the -explore option, a list of tests without results is returned. The format used is simply a subset of the test result format, without the result information. +When using the -explore option, a list of tests without results is returned. The format used is simply a subset of the +test result format, without the result information. See [Test Result XML Format](Test-Result-XML-Format.md) for details. ## Test Filters -Information about which tests to run is provided to the framework using a test filter, represented as an XML fragment. See [Test Filters](Test-Filters.md) for details. +Information about which tests to run is provided to the framework using a test filter, represented as an XML fragment. +See [Test Filters](Test-Filters.md) for details. ## Test Packages ## Progress Reports -As a test run progresses, individual test run results are sent as xml fragments from the result file under construction. A runner can, in fact, construct a copy of the result file incrementally using these fragments if desired. +As a test run progresses, individual test run results are sent as xml fragments from the result file under construction. +A runner can, in fact, construct a copy of the result file incrementally using these fragments if desired. ## VisualState -The Gui runner uses a file with the suffix .VisualState.xml to save the current visual state of a project so that it may be restored upon re-opening. This file is private to the Gui but is included here for completeness. The current format is identical to that used in NUnit 2.x. +The Gui runner uses a file with the suffix .VisualState.xml to save the current visual state of a project so that it may +be restored upon re-opening. This file is private to the Gui but is included here for completeness. The current format +is identical to that used in NUnit 2.x. * [Sample Visual State File](https://nunit.org/files/sample_visual_state_25.txt) diff --git a/docs/articles/nunit/writing-tests/AssertionHelper.md b/docs/articles/nunit/writing-tests/AssertionHelper.md index 1f7bb643a..d778b11d7 100644 --- a/docs/articles/nunit/writing-tests/AssertionHelper.md +++ b/docs/articles/nunit/writing-tests/AssertionHelper.md @@ -1,10 +1,10 @@ # Assertion Helper -> AssertionHelper has been deprecated as of NUnit Framework 3.7. The syntax is now maintained and being enhanced as an independent library, [NUnit.StaticExpect](https://github.com/fluffynuts/NUnit.StaticExpect). +> AssertionHelper has been deprecated as of NUnit Framework 3.7. The syntax is now maintained and being enhanced as an +> independent library, [NUnit.StaticExpect](https://github.com/fluffynuts/NUnit.StaticExpect). -Some users prefer a shorter form of assertion than is given by Assert.That. -If you derive your test fixture class from **AssertionHelper**, the -Expect() method may be used instead... +Some users prefer a shorter form of assertion than is given by Assert.That. If you derive your test fixture class from +**AssertionHelper**, the Expect() method may be used instead... ```csharp Expect(bool condition); @@ -21,7 +21,9 @@ Expect(TActual actual, IResolveConstraint constraint, Expect(TestDelegate del, IResolveConstraint constraint); ``` -In addition, **AssertionHelper** allows the derived class to make direct use of many of the syntactic elements that would normally require you to specify the **Is**, **Has** or **Does** class in order to use them. For example, you can write... +In addition, **AssertionHelper** allows the derived class to make direct use of many of the syntactic elements that +would normally require you to specify the **Is**, **Has** or **Does** class in order to use them. For example, you can +write... ```csharp Expect(actual, EqualTo("Hello")); diff --git a/docs/articles/nunit/writing-tests/Assumptions.md b/docs/articles/nunit/writing-tests/Assumptions.md index bcdf7cb89..5a32e15ac 100644 --- a/docs/articles/nunit/writing-tests/Assumptions.md +++ b/docs/articles/nunit/writing-tests/Assumptions.md @@ -1,6 +1,8 @@ # Assumptions -Assumptions are intended to express the state a test must be in to provide a meaningful result. They are functionally similar to assertions, however an unmet assumption will produce an `Inconclusive` test result, as opposed to a `Failure`. +Assumptions are intended to express the state a test must be in to provide a meaningful result. They are functionally +similar to assertions, however an unmet assumption will produce an `Inconclusive` test result, as opposed to a +`Failure`. Assumptions make use of the `Assume` static class. @@ -8,7 +10,10 @@ Assumptions make use of the `Assume` static class. [!code-csharp[AssumptionsTests](~/snippets/Snippets.NUnit/Assumptions.cs#TestThatUsesAssume)] -`Assume.That()` has the same set of overloads as `Assert.That()`. For further details, see the [Constraint Model](xref:constraintmodel) documentation. +`Assume.That()` has the same set of overloads as `Assert.That()`. For further details, see the [Constraint +Model](xref:constraintmodel) documentation. > [!NOTE] -> Failing assumptions indicate that running tests is invalid, while [Multiple Asserts](xref:multipleasserts) allow testing to continue after a failure. For that reason, the two features are incompatible and assumptions may not be used within a [multiple assert](xref:multipleasserts) block. +> Failing assumptions indicate that running tests is invalid, while [Multiple Asserts](xref:multipleasserts) +> allow testing to continue after a failure. For that reason, the two features are incompatible and assumptions may not +> be used within a [multiple assert](xref:multipleasserts) block. diff --git a/docs/articles/nunit/writing-tests/Randomizer-Methods.md b/docs/articles/nunit/writing-tests/Randomizer-Methods.md index a471e01e9..b2c3de470 100644 --- a/docs/articles/nunit/writing-tests/Randomizer-Methods.md +++ b/docs/articles/nunit/writing-tests/Randomizer-Methods.md @@ -4,12 +4,16 @@ uid: randomizermethods # Randomizer Methods -The **Randomizer** object exposed by `TestContext.CurrentContext.Random` extends `System.Random` to provide random data for a wide range of numeric types as well as enums and strings. Each test context has access to its own **Randomizer** which is used to generate random values for the `RandomAttribute` as well as for use by the user calling its methods. +The **Randomizer** object exposed by `TestContext.CurrentContext.Random` extends `System.Random` to provide random data +for a wide range of numeric types as well as enums and strings. Each test context has access to its own **Randomizer** +which is used to generate random values for the `RandomAttribute` as well as for use by the user calling its methods. The benefit of using **Randomizer** rather than `System.Random` directly is twofold: 1. A wide range of types are provided in a uniform manner. -2. Randomizer produces repeatable values for the test run so long as no tests are changed and the same seed is used to initialize the run. A future extension is planned, which would provide repeatability at the individual method level, even if other methods are changed. +2. Randomizer produces repeatable values for the test run so long as no tests are changed and the same seed is used to + initialize the run. A future extension is planned, which would provide repeatability at the individual method level, + even if other methods are changed. ## Int (System.Int32) @@ -167,8 +171,10 @@ Returns the next decimal in the range min to max, excluding max. #### Notes on Decimal Implementation -1. In the current implementation, the scale is always set to zero. That is, the values are all integral, with no decimal places. This may be enhanced in a future release by allowing the user to specify the scale. -2. In the third form, an exception is currently thrown if the range is greater than `decimal.MaxValue`. This can only occur if min is negative and max is positive. +1. In the current implementation, the scale is always set to zero. That is, the values are all integral, with no decimal + places. This may be enhanced in a future release by allowing the user to specify the scale. +2. In the third form, an exception is currently thrown if the range is greater than `decimal.MaxValue`. This can only + occur if min is negative and max is positive. ## Bool (System.Boolean) @@ -178,23 +184,28 @@ Returns a random bool with equal probability of `true` or `false`. ### `NextBool(double probability)` -Returns a random bool with the specified probability of being `true`. Probability argument must be in the range 0.0 to 1.0, inclusive. +Returns a random bool with the specified probability of being `true`. Probability argument must be in the range 0.0 to +1.0, inclusive. ## Enum (System.Enum) ### `NextEnum()` -Returns a random enum value of type T. All the values of the enum are returned with equal probability. Note that this may not be useful in all cases for enums with the `FlagsAttribute` specified. +Returns a random enum value of type T. All the values of the enum are returned with equal probability. Note that this +may not be useful in all cases for enums with the `FlagsAttribute` specified. ### `NextEnum(Type type)` -Returns a random enum value of the type specified as an object, which the caller will normally cast to the specified type. +Returns a random enum value of the type specified as an object, which the caller will normally cast to the specified +type. ## String (System.String) ### `GetString()` -Returns a random string of default length, composed using a default set of characters. In the current implementation, the default length is hard-coded as 25 and the default characters are `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNOPQRSTUVWXYZ0123456789_`. +Returns a random string of default length, composed using a default set of characters. In the current implementation, +the default length is hard-coded as 25 and the default characters are +`abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNOPQRSTUVWXYZ0123456789_`. ### `GetString(int length)` @@ -208,4 +219,5 @@ Returns a random string of the specified length using the characters in the stri ### `NextGuid()` (available in version 3.8) -Generates a version 4 Guid conforming the [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122#section-4.4). Version 4 Guids are made of random data. +Generates a version 4 Guid conforming the [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122#section-4.4). Version 4 +Guids are made of random data. diff --git a/docs/articles/nunit/writing-tests/TestCaseData.md b/docs/articles/nunit/writing-tests/TestCaseData.md index dadf63fb0..7a24adad1 100644 --- a/docs/articles/nunit/writing-tests/TestCaseData.md +++ b/docs/articles/nunit/writing-tests/TestCaseData.md @@ -4,20 +4,23 @@ uid: testcasedata # TestCaseData -The `TestCaseData` class provides extended test case information for a parameterized test, although any object deriving from `TestCaseParameters` may be used. Unlike NUnit 2, you cannot implement `ITestCaseData`, you must derive from `TestCaseParameters`. +The `TestCaseData` class provides extended test case information for a parameterized test, although any object deriving +from `TestCaseParameters` may be used. Unlike NUnit 2, you cannot implement `ITestCaseData`, you must derive from +`TestCaseParameters`. [!code-csharp[TestCaseDataExample](~/snippets/Snippets.NUnit/TestCaseDataExample.cs#TestCaseDataExample)] -This example uses the fluent interface supported by **TestCaseData** -to make the program more readable. +This example uses the fluent interface supported by **TestCaseData** to make the program more readable. -**TestCaseData** supports the following properties -and methods, which may be appended to an instance in any order. +**TestCaseData** supports the following properties and methods, which may be appended to an instance in any order. -* **Explicit()** or **Explicit(string)** causes the test case to be marked explicit, optionally specifying the reason for doing so. +* **Explicit()** or **Explicit(string)** causes the test case to be marked explicit, optionally specifying the reason + for doing so. * **Ignore(string)** causes the test case to be ignored and specifies the reason, which is required. * **Returns** specifies the expected result to be returned from the method, which must have a compatible return type. * **SetCategory(string)** applies a category to the test. * **SetDescription(string)** sets the description property of the test. -* **SetName(string)** provides a name for the test. If not specified, a name is generated based on the method name and the arguments provided. See [Template Based Test Naming](xref:templatebasedtestnaming). -* **SetProperty(string, string)**, **SetProperty(string, int)** and **SetProperty(string, double)** apply a named property and value to the test. +* **SetName(string)** provides a name for the test. If not specified, a name is generated based on the method name and + the arguments provided. See [Template Based Test Naming](xref:templatebasedtestnaming). +* **SetProperty(string, string)**, **SetProperty(string, int)** and **SetProperty(string, double)** apply a named + property and value to the test. diff --git a/docs/articles/nunit/writing-tests/TestContext.md b/docs/articles/nunit/writing-tests/TestContext.md index d0c64b397..1282c5885 100644 --- a/docs/articles/nunit/writing-tests/TestContext.md +++ b/docs/articles/nunit/writing-tests/TestContext.md @@ -4,18 +4,22 @@ uid: testcontext # TestContext -Each NUnit test runs in an execution context, which includes information about the environment as well as the test itself. The `TestContext` class allows tests to access certain information about the execution context. +Each NUnit test runs in an execution context, which includes information about the environment as well as the test +itself. The `TestContext` class allows tests to access certain information about the execution context. > [!NOTE] -> It's important to remember that "test" in NUnit may refer to an individual test cases or a suite such as a `TestFixture`. Within a test method, `SetUp` method or `TearDown` method, the context is that of the individual test case. Within a `OneTimeSetUp` or `OneTimeTearDown` method, the context refers to the fixture as a whole. This can lead to confusion, since most runners display information about fixtures differently from test cases. In fact, some runners may not display information about fixtures at all! +> It's important to remember that "test" in NUnit may refer to an individual test cases or a suite such as a +> `TestFixture`. Within a test method, `SetUp` method or `TearDown` method, the context is that of the individual test +> case. Within a `OneTimeSetUp` or `OneTimeTearDown` method, the context refers to the fixture as a whole. This can lead +> to confusion, since most runners display information about fixtures differently from test cases. In fact, some runners +> may not display information about fixtures at all! ## Static Properties ### CurrentContext -Gets the context of the currently executing test. This context -is created separately for each test before it begins execution. -See below for properties of the current context. +Gets the context of the currently executing test. This context is created separately for each test before it begins +execution. See below for properties of the current context. ### Out @@ -31,7 +35,9 @@ Gets a TextWriter used for sending normal (non-error) output intended for immed ### TestParameters -Test parameters may be supplied to a run in various ways, depending on the runner used. For example, the console runner provides a command-line argument and v3.4 of the NUnit 3 VS Adapter will supports specifying them in a .runsettings file. The static TestParameters property returns an object representing those passed-in parameters. +Test parameters may be supplied to a run in various ways, depending on the runner used. For example, the console runner +provides a command-line argument and v3.4 of the NUnit 3 VS Adapter will supports specifying them in a .runsettings +file. The static TestParameters property returns an object representing those passed-in parameters. The TestParameters object supports the following properties: @@ -43,9 +49,11 @@ The TestParameters object supports the following methods: * `Exists(string name)` - Returns true if a parameter of that name exists. * `Get(string name)`- Returns the same value as the indexer. -* `Get(string name, T defaultValue)` - Returns the value of the parameter converted from a string to type T or the specified default if the parameter doesn't exist. Throws an exception if conversion fails. +* `Get(string name, T defaultValue)` - Returns the value of the parameter converted from a string to type T or the + specified default if the parameter doesn't exist. Throws an exception if conversion fails. -**Note** that all parameter values are strings. You may convert them to other Types using the generic `Get` method listed above or using your own code. An exception may be thrown if the supplied value cannot be converted correctly. +**Note** that all parameter values are strings. You may convert them to other Types using the generic `Get` method +listed above or using your own code. An exception may be thrown if the supplied value cannot be converted correctly. ## Static Methods @@ -98,14 +106,17 @@ Writes text to the current test result, followed by a newline. ### AddFormatter (3.2+) -Adds a formatter for values based on some criterion, such as the Type of the value. The provided formatter will be used when an expected or actual value needs to be displayed as part of a message from a constraint. +Adds a formatter for values based on some criterion, such as the Type of the value. The provided formatter will be used +when an expected or actual value needs to be displayed as part of a message from a constraint. ```csharp AddFormatter(ValueFormatter formatter); AddFormatter(ValueFormatterFactory formatterFactory); ``` -Both `ValueFormatter` and `ValueFormatterFactory` are delegates. `ValueFormatter` takes a single object as an argument and returns its string representation. The `AddFormatter` overload that takes a ValueFormatter is intended for use in most cases that arise. +Both `ValueFormatter` and `ValueFormatterFactory` are delegates. `ValueFormatter` takes a single object as an argument +and returns its string representation. The `AddFormatter` overload that takes a ValueFormatter is intended for use in +most cases that arise. ### AddTestAttachment (3.7+) @@ -115,12 +126,14 @@ Attaches a file, with optional description, to the current test. AddTestAttachment(string filePath, string description = null); ``` -The file will be attached to the test result in the xml report. Test runners, such as the NUnit 3 VS Adapter, may also present the file to the user. +The file will be attached to the test result in the xml report. Test runners, such as the NUnit 3 VS Adapter, may also +present the file to the user. Notes: 1. The file must exist at the time of attachment. -1. File paths will be resolved as fully rooted paths, relative to `TestContext.CurrentContext.WorkDirectory`, which can be set by the user. +1. File paths will be resolved as fully rooted paths, relative to `TestContext.CurrentContext.WorkDirectory`, which can + be set by the user. ## Properties of the CurrentContext @@ -144,14 +157,18 @@ Gets a representation of the test result, with the following properties: * Skipped * Passed * Failed - * **Label** - An optional string value, which can provide sub-categories for each Status. See below for a list of common outcomes supported internally by NUnit. - * **Site** - A `FailureSite` value, indicating the stage of execution in which the test generated its result. Possible values are + * **Label** - An optional string value, which can provide sub-categories for each Status. See below for a list of + common outcomes supported internally by NUnit. + * **Site** - A `FailureSite` value, indicating the stage of execution in which the test generated its result. Possible + values are * Test * SetUp * TearDown * Parent * Child -* **Assertions** - A list of `AssertionResult` values generated up to this point in the test. Please note that **only failed assertions** will be stored in here to limit the size of the result tree and potential impact on performance. Each `AssertionResult` has the following properties: +* **Assertions** - A list of `AssertionResult` values generated up to this point in the test. Please note that **only + failed assertions** will be stored in here to limit the size of the result tree and potential impact on performance. + Each `AssertionResult` has the following properties: * **Status** - An `AssertionStatus` with five possible values: * Inconclusive * Passed @@ -162,12 +179,15 @@ Gets a representation of the test result, with the following properties: * **StackTrace** - A string containing the stack trace associated with the assertion. * **PassCount** - An int representing the number of test cases that passed when running the test and all its children. * **FailCount** - An int representing the number of test cases that failed when running the test and all its children. -* **SkipCount** - An int representing the number of test cases that were skipped when running the test and all its children. -* **InconclusiveCount** - An int representing the number of test cases that were inconclusive when running the test and all its children. +* **SkipCount** - An int representing the number of test cases that were skipped when running the test and all its + children. +* **InconclusiveCount** - An int representing the number of test cases that were inconclusive when running the test and + all its children. * **StackTrace** - A string containing the stack trace associated with an error or failure. * **Message** - A string containing the message associated with a test failure or with not running the test. -Although the outcome of the test may be accessed during setup or test execution, it only has a useful value in the teardown stage. +Although the outcome of the test may be accessed during setup or test execution, it only has a useful value in the +teardown stage. ### Common Outcomes @@ -189,11 +209,15 @@ Gets the full path of the directory containing the current test assembly. ### WorkDirectory -Gets the full path of the directory to be used for output from this test run. The XML result file and any redirected output files are located under this directory. This is normally the directory that was current when execution of -NUnit began but may be changed by use of the **--work** option of nunit-console. +Gets the full path of the directory to be used for output from this test run. The XML result file and any redirected +output files are located under this directory. This is normally the directory that was current when execution of NUnit +began but may be changed by use of the **--work** option of nunit-console. ### Random -Returns a `Randomizer` object, which may be used in the test code to generate random values. These values are repeatable on reruns of the tests so long as (a) the test assembly is not changed and (b) the same seed is used. The initial random seed used in any test run may be found in the XML result file and may be provided to a subsequent run on the command line. +Returns a `Randomizer` object, which may be used in the test code to generate random values. These values are repeatable +on reruns of the tests so long as (a) the test assembly is not changed and (b) the same seed is used. The initial random +seed used in any test run may be found in the XML result file and may be provided to a subsequent run on the command +line. See [Randomizer Methods](Randomizer-Methods.md) for details about each available random data type. diff --git a/docs/articles/nunit/writing-tests/TestFixtureData.md b/docs/articles/nunit/writing-tests/TestFixtureData.md index 1f8be28b1..cb49cfc3e 100644 --- a/docs/articles/nunit/writing-tests/TestFixtureData.md +++ b/docs/articles/nunit/writing-tests/TestFixtureData.md @@ -4,9 +4,11 @@ uid: testfixturedata # TestFixtureData -The `TestFixtureData` class provides specific instance information for a parameterized fixture, although any object deriving from `TestFixtureParameters` may be used. Unlike NUnit 2, you cannot implement `IFixtureData`, you must derive from `TestFixtureParameters`. +The `TestFixtureData` class provides specific instance information for a parameterized fixture, although any object +deriving from `TestFixtureParameters` may be used. Unlike NUnit 2, you cannot implement `IFixtureData`, you must derive +from `TestFixtureParameters`. -The following example varies the example shown under [TestFixture Attribute](xref:testfixtureattribute) by using -a `TestFixtureSourceAttribute` with a data source in a separately defined class. +The following example varies the example shown under [TestFixture Attribute](xref:testfixtureattribute) by using a +`TestFixtureSourceAttribute` with a data source in a separately defined class. [!code-csharp[TestFixtureDataExample](~/snippets/Snippets.NUnit/TestFixtureDataExample.cs#TestFixtureDataExample)] diff --git a/docs/articles/nunit/writing-tests/Warnings.md b/docs/articles/nunit/writing-tests/Warnings.md index 227be73ab..9575a47a0 100644 --- a/docs/articles/nunit/writing-tests/Warnings.md +++ b/docs/articles/nunit/writing-tests/Warnings.md @@ -1,14 +1,21 @@ # Warnings -Sometimes - especially in integration testing - it's desirable to give a warning message but continue execution. Beginning with release 3.6, NUnit supports this with the `Warn` class and the `Assert.Warn` method. +Sometimes - especially in integration testing - it's desirable to give a warning message but continue execution. +Beginning with release 3.6, NUnit supports this with the `Warn` class and the `Assert.Warn` method. ## Syntax [!code-csharp[WarningExamples](~/snippets/Snippets.NUnit/WarningExamples.cs#WarningExamples)] -Each of the above items would fail. The test would continue to execute, however, and the warning messages would only be reported at the end of the test. If the test subsequently fails, the warnings will be reported along with the failure message or - in the case of `Assert.Multiple` - messages. +Each of the above items would fail. The test would continue to execute, however, and the warning messages would only be +reported at the end of the test. If the test subsequently fails, the warnings will be reported along with the failure +message or - in the case of `Assert.Multiple` - messages. -All of the overloads above also have a variant that accepts a function, `Func`, that is used to build the message included with the Exception. +All of the overloads above also have a variant that accepts a function, `Func`, that is used to build the +message included with the Exception. > [!NOTE] -> The framework reports warnings by including information about them in the XML result that is sent to the runner in use. If you are using this facility, make sure the runner you use supports warnings. Generally, the runners released by the NUnit team after the release of the 3.6 framework will have this support. Earlier releases will not. Many third party runners will not know what to do with warnings either. +> The framework reports warnings by including information about them in the XML result that is sent to the +> runner in use. If you are using this facility, make sure the runner you use supports warnings. Generally, the runners +> released by the NUnit team after the release of the 3.6 framework will have this support. Earlier releases will not. +> Many third party runners will not know what to do with warnings either. diff --git a/docs/articles/nunit/writing-tests/assertions/assertion-models/classic.md b/docs/articles/nunit/writing-tests/assertions/assertion-models/classic.md index 51a9f5106..84ed893a2 100644 --- a/docs/articles/nunit/writing-tests/assertions/assertion-models/classic.md +++ b/docs/articles/nunit/writing-tests/assertions/assertion-models/classic.md @@ -58,4 +58,5 @@ Additional assertions are provided by the following classes, which are also in t ## Notes -* The exception-family of classic asserts have not yet been moved to the legacy namespace. They have not yet full equivalents in the constraint model. +* The exception-family of classic asserts have not yet been moved to the legacy namespace. They have not yet full + equivalents in the constraint model. diff --git a/docs/articles/nunit/writing-tests/assertions/assertion-models/constraint.md b/docs/articles/nunit/writing-tests/assertions/assertion-models/constraint.md index 5afb42719..324b271fa 100644 --- a/docs/articles/nunit/writing-tests/assertions/assertion-models/constraint.md +++ b/docs/articles/nunit/writing-tests/assertions/assertion-models/constraint.md @@ -4,10 +4,8 @@ uid: constraintmodel # Constraint Model (Assert.That) -The constraint-based Assert model uses a single method of the Assert class -for all assertions. The logic necessary to carry out each assertion is -embedded in the constraint object passed as the second parameter to that -method. +The constraint-based Assert model uses a single method of the Assert class for all assertions. The logic necessary to +carry out each assertion is embedded in the constraint object passed as the second parameter to that method. Here's a very simple assert using the constraint model: @@ -15,15 +13,15 @@ Here's a very simple assert using the constraint model: Assert.That(myString, Is.EqualTo("Hello")); ``` -The second argument in this assertion uses one of NUnit's **syntax helpers** -to create an **EqualConstraint**. The same assertion could also be made in this form: +The second argument in this assertion uses one of NUnit's **syntax helpers** to create an **EqualConstraint**. The same +assertion could also be made in this form: ```csharp Assert.That(myString, new EqualConstraint("Hello")); ``` -Using this model, all assertions are made using one of the forms of the -`Assert.That()` method, which has a number of overloads... +Using this model, all assertions are made using one of the forms of the `Assert.That()` method, which has a number of +overloads... ```csharp Assert.That(bool condition); @@ -53,16 +51,15 @@ Assert.That(TestDelegate code, IResolveConstraint constraint, Func getExceptionMessage) ``` -The overloads that take a bool work exactly like `ClassicAssert.IsTrue`, except that `ClassicAssert.IsTrue` does not accept a `Func` for the exception message. +The overloads that take a bool work exactly like `ClassicAssert.IsTrue`, except that `ClassicAssert.IsTrue` does not +accept a `Func` for the exception message. -For overloads taking a constraint, the argument must be an object implementing -the **IResolveConstraint** interface, which supports performing a test -on an actual value and generating appropriate messages. This interface -is described in more detail under [Custom Constraints](xref:customconstraints). +For overloads taking a constraint, the argument must be an object implementing the **IResolveConstraint** interface, +which supports performing a test on an actual value and generating appropriate messages. This interface is described in +more detail under [Custom Constraints](xref:customconstraints). -NUnit provides a number of constraint classes similar to the **EqualConstraint** -used in the example above. Generally, these classes may be used directly or -through a syntax helper. The valid forms are described on the pages related to +NUnit provides a number of constraint classes similar to the **EqualConstraint** used in the example above. Generally, +these classes may be used directly or through a syntax helper. The valid forms are described on the pages related to each constraint. ## See also diff --git a/docs/articles/nunit/writing-tests/assertions/assertion-models/special.md b/docs/articles/nunit/writing-tests/assertions/assertion-models/special.md index bcddb310f..9c977f92e 100644 --- a/docs/articles/nunit/writing-tests/assertions/assertion-models/special.md +++ b/docs/articles/nunit/writing-tests/assertions/assertion-models/special.md @@ -1,7 +1,8 @@ # Special Assertions -The special assertions do not check any condition. They are used for special purposes, like unconditional failure or success, ignoring a test, etc. +The special assertions do not check any condition. They are used for special purposes, like unconditional failure or +success, ignoring a test, etc. * [Assert.Pass](../special-assertions/Assert.Pass.md) * [Assert.Fail](../special-assertions/Assert.Fail.md) diff --git a/docs/articles/nunit/writing-tests/assertions/assertions.md b/docs/articles/nunit/writing-tests/assertions/assertions.md index 575967770..a9f3ef472 100644 --- a/docs/articles/nunit/writing-tests/assertions/assertions.md +++ b/docs/articles/nunit/writing-tests/assertions/assertions.md @@ -4,49 +4,50 @@ uid: assertions # Assertions -Assertions are central to unit testing in any of the xUnit frameworks, and NUnit -is no exception. NUnit provides a rich set of assertions as static methods of -the Assert class. +Assertions are central to unit testing in any of the xUnit frameworks, and NUnit is no exception. NUnit provides a rich +set of assertions as static methods of the Assert class. -If an assertion fails, the method call does not return and an error is reported. -If a test contains multiple assertions, any that follow the one that failed -will not be executed. For this reason, it's usually best to try for one -assertion per test. +If an assertion fails, the method call does not return and an error is reported. If a test contains multiple assertions, +any that follow the one that failed will not be executed. For this reason, it's usually best to try for one assertion +per test. -Each method may be called without a message, with a simple text message or with -a message with interpolated arguments (aka interpolated string). +Each method may be called without a message, with a simple text message or with a message with interpolated arguments +(aka interpolated string). ## Two Models -In NUnit 3.0 and higher, assertions are written primarily using the `Assert.That` method, -which takes [constraint objects](xref:constraints) as an argument. We call this -the [Constraint Model](xref:constraintmodel) of assertions. +In NUnit 3.0 and higher, assertions are written primarily using the `Assert.That` method, which takes [constraint +objects](xref:constraints) as an argument. We call this the [Constraint Model](xref:constraintmodel) of assertions. -In earlier versions of NUnit, a separate method of the Assert class was used -for each different assertion. This [Classic Model](xref:classicmodel) is still supported but -since no new features have been added to it for some time, the constraint-based -model must be used in order to have full access to NUnit's capabilities. +In earlier versions of NUnit, a separate method of the Assert class was used for each different assertion. This [Classic +Model](xref:classicmodel) is still supported but since no new features have been added to it for some time, the +constraint-based model must be used in order to have full access to NUnit's capabilities. For example, the following code must use the constraint model. There is no real classic equivalent. [!code-csharp[ConstraintWithoutClassicEquivalent](~/snippets/Snippets.NUnit/ClassicVsConstraintAssertions.cs#ConstraintWithoutClassicEquivalent)] -Where equivalents do exist, the two approaches will always give the same result, -because the methods of the classic approach have all been implemented internally -using constraints. For example... +Where equivalents do exist, the two approaches will always give the same result, because the methods of the classic +approach have all been implemented internally using constraints. For example... [!code-csharp[ClassicAndConstraintsAreEquivalent](~/snippets/Snippets.NUnit/ClassicVsConstraintAssertions.cs#ClassicAndConstraintsAreEquivalent)] ### Some notes on the Classic/Legacy asserts -The classic/legacy asserts, like `ClassicAssert.AreEqual`, have now been moved into its own project (namespace), and will later be released as a separate package. They are now in the namespace `NUnit.Framework.Legacy`, and the `Assert` have been renamed to `ClassicAssert`. +The classic/legacy asserts, like `ClassicAssert.AreEqual`, have now been moved into its own project (namespace), and +will later be released as a separate package. They are now in the namespace `NUnit.Framework.Legacy`, and the `Assert` +have been renamed to `ClassicAssert`. -If you're upgrading from NUnit 3.X to NUnit 4, you need to add a using for `NUnit.Framework.Legacy` to your test classes, and rename all classic asserts from `Assert` to `ClassicAssert`. +If you're upgrading from NUnit 3.X to NUnit 4, you need to add a using for `NUnit.Framework.Legacy` to your test +classes, and rename all classic asserts from `Assert` to `ClassicAssert`. -You *can* freely mix the constraint model assertions and the classic asserts in the same test class, but we don't recommend it. +You *can* freely mix the constraint model assertions and the classic asserts in the same test class, but we don't +recommend it. All assertions in the `ClassicAssert` class are rerouting to use the constraint model. -As shown in the example in [Towards NUnit 4](xref:towardsnunit4), error message have been enhanced so that you see the Assert expression. This also works for the ClassicAsserts, but what you will see there is the equivalent constraint expression. +As shown in the example in [Towards NUnit 4](xref:towardsnunit4), error message have been enhanced so that you see the +Assert expression. This also works for the ClassicAsserts, but what you will see there is the equivalent constraint +expression. ![Classic-Assert-Fails](../../../../images/nunit-classic-asserts-fails.png) diff --git a/docs/articles/nunit/writing-tests/assertions/classic-assertions/Assert.IsEmpty.md b/docs/articles/nunit/writing-tests/assertions/classic-assertions/Assert.IsEmpty.md index 56c20d8f4..a9347834c 100644 --- a/docs/articles/nunit/writing-tests/assertions/classic-assertions/Assert.IsEmpty.md +++ b/docs/articles/nunit/writing-tests/assertions/classic-assertions/Assert.IsEmpty.md @@ -1,8 +1,7 @@ # ClassicAssert.IsEmpty -**ClassicAssert.IsEmpty** may be used to test either a string or a collection or IEnumerable. -When used with a string, it succeeds if the string is the empty string. -When used with a collection, it succeeds if the collection is empty. +**ClassicAssert.IsEmpty** may be used to test either a string or a collection or IEnumerable. When used with a string, +it succeeds if the string is the empty string. When used with a collection, it succeeds if the collection is empty. ```csharp ClassicAssert.IsEmpty(string aString); @@ -14,7 +13,8 @@ ClassicAssert.IsEmpty(IEnumerable collection, string message, ``` > [!NOTE] -> When used with an IEnumerable that is not also an ICollection, **ClassicAssert.IsEmpty** attempts to enumerate the contents. It should not be used in cases where this results in an unwanted side effect. +> When used with an IEnumerable that is not also an ICollection, **ClassicAssert.IsEmpty** attempts to enumerate +> the contents. It should not be used in cases where this results in an unwanted side effect. ## See Also diff --git a/docs/articles/nunit/writing-tests/assertions/classic-assertions/Assert.IsNotEmpty.md b/docs/articles/nunit/writing-tests/assertions/classic-assertions/Assert.IsNotEmpty.md index ee1257793..d0c5a5237 100644 --- a/docs/articles/nunit/writing-tests/assertions/classic-assertions/Assert.IsNotEmpty.md +++ b/docs/articles/nunit/writing-tests/assertions/classic-assertions/Assert.IsNotEmpty.md @@ -1,8 +1,8 @@ # ClassicAssert.IsNotEmpty -**ClassicAssert.IsNotEmpty** may be used to test either a string or a collection or IEnumerable. -When used with a string, it succeeds if the string is not the empty string. -When used with a collection, it succeeds if the collection is not empty. +**ClassicAssert.IsNotEmpty** may be used to test either a string or a collection or IEnumerable. When used with a +string, it succeeds if the string is not the empty string. When used with a collection, it succeeds if the collection is +not empty. ```csharp ClassicAssert.IsNotEmpty(string aString); @@ -14,7 +14,8 @@ ClassicAssert.IsNotEmpty(IEnumerable collection, string message, ``` > [!NOTE] -> When used with an IEnumerable that is not also an ICollection, **ClassicAssert.IsEmpty** attempts to enumerate the contents. It should not be used in cases where this results in an unwanted side effect. +> When used with an IEnumerable that is not also an ICollection, **ClassicAssert.IsEmpty** attempts to enumerate +> the contents. It should not be used in cases where this results in an unwanted side effect. ## See Also diff --git a/docs/articles/nunit/writing-tests/assertions/classic-assertions/Collection-Assert.md b/docs/articles/nunit/writing-tests/assertions/classic-assertions/Collection-Assert.md index 5ee1e7021..92fcb172c 100644 --- a/docs/articles/nunit/writing-tests/assertions/classic-assertions/Collection-Assert.md +++ b/docs/articles/nunit/writing-tests/assertions/classic-assertions/Collection-Assert.md @@ -1,10 +1,10 @@ # CollectionAssert -The CollectionAssert class provides a number of methods that are useful when examining collections and their contents or for comparing two collections. These methods may be used with any object implementing `IEnumerable`. +The CollectionAssert class provides a number of methods that are useful when examining collections and their contents or +for comparing two collections. These methods may be used with any object implementing `IEnumerable`. -The **AreEqual** overloads succeed if the corresponding elements of the two -collections are equal. **AreEquivalent** tests whether the collection contents -are equal, but without regard to order. In both cases, elements are compared using +The **AreEqual** overloads succeed if the corresponding elements of the two collections are equal. **AreEquivalent** +tests whether the collection contents are equal, but without regard to order. In both cases, elements are compared using NUnit's default equality comparison. ```csharp diff --git a/docs/articles/nunit/writing-tests/assertions/multiple-asserts.md b/docs/articles/nunit/writing-tests/assertions/multiple-asserts.md index dc8a940d7..10d9be31c 100644 --- a/docs/articles/nunit/writing-tests/assertions/multiple-asserts.md +++ b/docs/articles/nunit/writing-tests/assertions/multiple-asserts.md @@ -4,7 +4,9 @@ uid: multipleasserts # Multiple Asserts -Usually, once an assertion fails, we want the test to terminate. But sometimes, it's desirable to continue and accumulate any additional failures so they may all be fixed at once. This is particularly useful for testing things like object initialization and UI appearance as well as certain kinds of integration testing. +Usually, once an assertion fails, we want the test to terminate. But sometimes, it's desirable to continue and +accumulate any additional failures so they may all be fixed at once. This is particularly useful for testing things like +object initialization and UI appearance as well as certain kinds of integration testing. ## Syntax / Example @@ -18,7 +20,9 @@ In that case, we could write a test with multiple assertions, such as: [!code-csharp[MultipleAssertsTests](~/snippets/Snippets.NUnit/MultipleAsserts.cs#MultipleAssertsTests)] -Functionally, this results in NUnit storing any failures encountered in the block and reporting all of them together upon exit from the block. If both asserts failed, then both would be reported. The test itself would terminate at the end of the block if any failures were encountered, but would continue otherwise. +Functionally, this results in NUnit storing any failures encountered in the block and reporting all of them together +upon exit from the block. If both asserts failed, then both would be reported. The test itself would terminate at the +end of the block if any failures were encountered, but would continue otherwise. ## Notes @@ -28,9 +32,13 @@ Functionally, this results in NUnit storing any failures encountered in the bloc 3. If the code in the block calls a method, that method may also contain multiple assert blocks. -4. The test will be terminated immediately if any exception is thrown that is not handled. An unexpected exception is often an indication that the test itself is in error, so it must be terminated. If the exception occurs after one or more assertion failures have been recorded, those failures will be reported along with the terminating exception itself. +4. The test will be terminated immediately if any exception is thrown that is not handled. An unexpected exception is + often an indication that the test itself is in error, so it must be terminated. If the exception occurs after one or + more assertion failures have been recorded, those failures will be reported along with the terminating exception + itself. -5. Assert.Fail is handled just as any other assert failure. The message and stack trace are recorded but the test continues to execute until the end of the block. +5. Assert.Fail is handled just as any other assert failure. The message and stack trace are recorded but the test + continues to execute until the end of the block. 6. An error is reported if any of the following are used inside a multiple assert block: * Assert.Pass @@ -38,15 +46,19 @@ Functionally, this results in NUnit storing any failures encountered in the bloc * Assert.Inconclusive * Assume.That -7. Use of Warnings (Assert.Warn, Warn.If, Warn.Unless) is permitted inside a multiple assert block. Warnings are reported normally along with any failures that occur inside the block. +7. Use of Warnings (Assert.Warn, Warn.If, Warn.Unless) is permitted inside a multiple assert block. Warnings are + reported normally along with any failures that occur inside the block. ### Runner Support -Multiple assertion failures per test are stored in the representation of the test result using new XML elements, which are not recognized by older runners. The following runners are known to support display of the new elements: +Multiple assertion failures per test are stored in the representation of the test result using new XML elements, which +are not recognized by older runners. The following runners are known to support display of the new elements: * NUnit 3 Visual Studio Adapter 3.7++ (Used by Visual Studio and `dotnet test`) * NUnit Console Runner 3.6++ #### Compatibility -Older runners generally display a single failure message and stack trace for each test. For compatibility purposes, the framework creates a single message that lists all the failures. The stack trace in such a case will indicate the end of the assert multiple block. +Older runners generally display a single failure message and stack trace for each test. For compatibility purposes, the +framework creates a single message that lists all the failures. The stack trace in such a case will indicate the end of +the assert multiple block. diff --git a/docs/articles/nunit/writing-tests/attributes.md b/docs/articles/nunit/writing-tests/attributes.md index deb214730..595d31d3c 100644 --- a/docs/articles/nunit/writing-tests/attributes.md +++ b/docs/articles/nunit/writing-tests/attributes.md @@ -1,6 +1,8 @@ # Attributes -NUnit uses custom attributes to identify tests. All NUnit attributes are contained in the NUnit.Framework namespace. Each source file that contains tests must include a using statement for that namespace and the project must reference the framework assembly, `nunit.framework.dll`. +NUnit uses custom attributes to identify tests. All NUnit attributes are contained in the NUnit.Framework namespace. +Each source file that contains tests must include a using statement for that namespace and the project must reference +the framework assembly, `nunit.framework.dll`. This table lists all the attributes supported by NUnit. diff --git a/docs/articles/nunit/writing-tests/attributes/apartment.md b/docs/articles/nunit/writing-tests/attributes/apartment.md index 83e6df3bc..8fa098e7d 100644 --- a/docs/articles/nunit/writing-tests/attributes/apartment.md +++ b/docs/articles/nunit/writing-tests/attributes/apartment.md @@ -4,19 +4,17 @@ uid: apartment-attribute # Apartment -The `ApartmentAttribute` is used on a test method, class or assembly -to specify that the tests should be run in a particular [apartment](https://learn.microsoft.com/en-us/windows/win32/com/processes--threads--and-apartments), either +The `ApartmentAttribute` is used on a test method, class or assembly to specify that the tests should be run in a +particular [apartment](https://learn.microsoft.com/en-us/windows/win32/com/processes--threads--and-apartments), either the STA or the MTA. -When running tests in parallel, the test is simply scheduled to execute -from a queue that uses the apartment specified. When the parallel feature -is not in use, it causes creation of a new thread if the parent test is -not already running in the correct apartment. +When running tests in parallel, the test is simply scheduled to execute from a queue that uses the apartment specified. +When the parallel feature is not in use, it causes creation of a new thread if the parent test is not already running in +the correct apartment. When this attribute is not specified, tests run in the MTA. -This attribute replaces the RequiresMTA and RequiresSTA attributes, which -are now considered obsolete. +This attribute replaces the RequiresMTA and RequiresSTA attributes, which are now considered obsolete. ## Assembly Level Examples diff --git a/docs/articles/nunit/writing-tests/attributes/author.md b/docs/articles/nunit/writing-tests/attributes/author.md index 040a7b88c..b84ef2d9d 100644 --- a/docs/articles/nunit/writing-tests/attributes/author.md +++ b/docs/articles/nunit/writing-tests/attributes/author.md @@ -4,12 +4,14 @@ uid: author-attribute # Author -The **Author** Attribute adds information about the author of the tests. It can be applied to test fixtures and to tests. +The **Author** Attribute adds information about the author of the tests. It can be applied to test fixtures and to +tests. -The constructor takes the name of the test author and optionally the author's email address. Author can also be specified on -a TestFixture or Test attribute. +The constructor takes the name of the test author and optionally the author's email address. Author can also be +specified on a TestFixture or Test attribute. [!code-csharp[AuthorAttributeExample](~/snippets/Snippets.NUnit/Attributes/AuthorAttributeExamples.cs#AuthorAttributeExample)] > [!NOTE] -> From NUnit version 3.7, you can have multiple Author attributes per fixture or test. Before version 3.7 you could only have one Author attribute per fixture or test. +> From NUnit version 3.7, you can have multiple Author attributes per fixture or test. Before version 3.7 you +> could only have one Author attribute per fixture or test. diff --git a/docs/articles/nunit/writing-tests/attributes/cancelafter.md b/docs/articles/nunit/writing-tests/attributes/cancelafter.md index 43e8d58bb..a4248b932 100644 --- a/docs/articles/nunit/writing-tests/attributes/cancelafter.md +++ b/docs/articles/nunit/writing-tests/attributes/cancelafter.md @@ -1,23 +1,35 @@ # CancelAfter -Normally, NUnit simply runs tests and waits for them to terminate -- the test is allowed to run indefinitely. For certain kinds of tests, however, it may be desirable to specify a timeout value. +Normally, NUnit simply runs tests and waits for them to terminate -- the test is allowed to run indefinitely. For +certain kinds of tests, however, it may be desirable to specify a timeout value. -For .NET Core and later, [`Thread.Abort`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.thread.abort?view=net-7.0) as used by the [`TimeoutAttribue`](./timeout.md) can no longer be used, and there is therefore no way to interrupt an endless loop. +For .NET Core and later, +[`Thread.Abort`](https://learn.microsoft.com/en-us/dotnet/api/system.threading.thread.abort?view=net-7.0) as used by the +[`TimeoutAttribue`](./timeout.md) can no longer be used, and there is therefore no way to interrupt an endless loop. -For all tests, one could use the `--blame-hang(-timeout)` options of [`dotnet test`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test#options). However, this will stop any further execution of the remaining tests. +For all tests, one could use the `--blame-hang(-timeout)` options of [`dotnet +test`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test#options). However, this will stop any further +execution of the remaining tests. -To still be able to cancel tests, one has to move to cooperative cancellation. See [Cancellation in Managed Threads](https://learn.microsoft.com/en-us/dotnet/standard/threading/cancellation-in-managed-threads) using a [`CancellationToken``](https://learn.microsoft.com/en-us/dotnet/api/system.threading.cancellationtoken?view=net-7.0). +To still be able to cancel tests, one has to move to cooperative cancellation. See [Cancellation in Managed +Threads](https://learn.microsoft.com/en-us/dotnet/standard/threading/cancellation-in-managed-threads) using a +[`CancellationToken``](https://learn.microsoft.com/en-us/dotnet/api/system.threading.cancellationtoken?view=net-7.0). -The `CancelAfterAttribute` is used to specify a timeout value in milliseconds for a test case. -If the test case runs longer than the time specified, the supplied `CancellationToken` is set to canceled. -It is however up to the test code to check this token, either directly or indirectly. +The `CancelAfterAttribute` is used to specify a timeout value in milliseconds for a test case. If the test case runs +longer than the time specified, the supplied `CancellationToken` is set to canceled. It is however up to the test code +to check this token, either directly or indirectly. -The specified timeout value covers the test setup and teardown as well as the test method itself. Before and after actions may also be included, depending on where they were specified. Since the timeout may occur during any of these execution phases, no guarantees can be made as to what will be run and any of these phases of execution may be incomplete. If only used on a test, once a test has timed out, its teardown methods are executed. +The specified timeout value covers the test setup and teardown as well as the test method itself. Before and after +actions may also be included, depending on where they were specified. Since the timeout may occur during any of these +execution phases, no guarantees can be made as to what will be run and any of these phases of execution may be +incomplete. If only used on a test, once a test has timed out, its teardown methods are executed. -The attribute may also be specified on a fixture, in which case it indicates the default timeout for any subordinate test cases. When using the console runner, it is also possible to specify a default timeout on the command-line. +The attribute may also be specified on a fixture, in which case it indicates the default timeout for any subordinate +test cases. When using the console runner, it is also possible to specify a default timeout on the command-line. -When used on test methods, NUnit automatically adds an extra argument to your method containing the NUnit `CancellationToken`. -If you want to check for cancellation in `SetUp` methods, you can use `TestContext.CurrentContext.CancellationToken` +When used on test methods, NUnit automatically adds an extra argument to your method containing the NUnit +`CancellationToken`. If you want to check for cancellation in `SetUp` methods, you can use +`TestContext.CurrentContext.CancellationToken` ## Example diff --git a/docs/articles/nunit/writing-tests/attributes/category.md b/docs/articles/nunit/writing-tests/attributes/category.md index 5398f8a72..6d00a7cb3 100644 --- a/docs/articles/nunit/writing-tests/attributes/category.md +++ b/docs/articles/nunit/writing-tests/attributes/category.md @@ -1,14 +1,13 @@ # Category -The Category attribute provides an alternative to suites for dealing with groups -of tests. Either individual test cases or fixtures may be identified as -belonging to a particular category. Some runners, including the Console Runner, -allow specifying categories to be included in or excluded from the run. -When categories are used, only the tests in the selected categories will be -run. Those tests in categories that are not selected are not reported at all. +The Category attribute provides an alternative to suites for dealing with groups of tests. Either individual test cases +or fixtures may be identified as belonging to a particular category. Some runners, including the Console Runner, allow +specifying categories to be included in or excluded from the run. When categories are used, only the tests in the +selected categories will be run. Those tests in categories that are not selected are not reported at all. > [!WARNING] -> While the C# syntax allows you to place a Category attribute on a SetUpFixture class, the attribute is ignored by NUnit and has no effect in current releases. +> While the C# syntax allows you to place a Category attribute on a SetUpFixture class, the attribute is +> ignored by NUnit and has no effect in current releases. ## Test Fixture Syntax @@ -47,13 +46,11 @@ namespace NUnit.Tests ### Custom Category Attributes -Custom attributes that derive from **CategoryAttribute** will be recognized -by NUnit. The default protected constructor of CategoryAttribute -sets the category name to the name of your class. +Custom attributes that derive from **CategoryAttribute** will be recognized by NUnit. The default protected constructor +of CategoryAttribute sets the category name to the name of your class. -Here's an example that creates a category of Critical tests. It works -just like any other category, but has a simpler syntax. A test reporting -system might make use of the attribute to provide special reports. +Here's an example that creates a category of Critical tests. It works just like any other category, but has a simpler +syntax. A test reporting system might make use of the attribute to provide special reports. ```csharp [AttributeUsage(AttributeTargets.Method, AllowMultiple=false)] diff --git a/docs/articles/nunit/writing-tests/attributes/culture.md b/docs/articles/nunit/writing-tests/attributes/culture.md index 4128db2d6..a99deb4ee 100644 --- a/docs/articles/nunit/writing-tests/attributes/culture.md +++ b/docs/articles/nunit/writing-tests/attributes/culture.md @@ -1,10 +1,14 @@ # Culture -The Culture attribute is used to specify cultures for which a test or fixture should be run. It does not affect the culture setting, but merely uses it to determine whether to run the test. If you wish to change the culture when running a test, use the SetCulture attribute instead. +The Culture attribute is used to specify cultures for which a test or fixture should be run. It does not affect the +culture setting, but merely uses it to determine whether to run the test. If you wish to change the culture when running +a test, use the SetCulture attribute instead. -If the specified culture requirements for a test are not met it is skipped. In the gui, the tree node for the test remains gray and the status bar color is not affected. +If the specified culture requirements for a test are not met it is skipped. In the gui, the tree node for the test +remains gray and the status bar color is not affected. -One use of the Culture attribute is to provide alternative tests under different cultures. You may specify either specific cultures, like "en-GB" or neutral cultures like "de". +One use of the Culture attribute is to provide alternative tests under different cultures. You may specify either +specific cultures, like "en-GB" or neutral cultures like "de". ## Test Fixture Syntax diff --git a/docs/articles/nunit/writing-tests/attributes/description.md b/docs/articles/nunit/writing-tests/attributes/description.md index 4df0842e9..a6736cea1 100644 --- a/docs/articles/nunit/writing-tests/attributes/description.md +++ b/docs/articles/nunit/writing-tests/attributes/description.md @@ -1,7 +1,7 @@ # Description -The Description attribute is used to apply descriptive text to a Test, -TestFixture or Assembly. The text appears in the XML output file. +The Description attribute is used to apply descriptive text to a Test, TestFixture or Assembly. The text appears in the +XML output file. ## Example @@ -24,4 +24,5 @@ namespace NUnit.Tests ``` > [!NOTE] -> The Test and TestFixture attributes continue to support an optional Description property. The Description attribute should be used for new applications. If both are used, the Description attribute takes precedence. +> The Test and TestFixture attributes continue to support an optional Description property. The Description +> attribute should be used for new applications. If both are used, the Description attribute takes precedence. diff --git a/docs/articles/nunit/writing-tests/attributes/explicit.md b/docs/articles/nunit/writing-tests/attributes/explicit.md index 8bfe429bf..5c433eeb8 100644 --- a/docs/articles/nunit/writing-tests/attributes/explicit.md +++ b/docs/articles/nunit/writing-tests/attributes/explicit.md @@ -1,27 +1,24 @@ # Explicit -The Explicit attribute causes a test or test fixture to be skipped unless it is -explicitly selected for running. The test or fixture will be run if it is -selected by name or if it is included by use of a filter. A **not** -filter, which excludes certain tests, is not treated as an explicit selection -and never causes an explicit test to be run. All other filters are considered -to explicitly select the tests that they match. See examples below. - -An optional string argument may be used to give the reason for marking -the test Explicit. - -If a test or fixture with the Explicit attribute is encountered in the course of -running tests, it is skipped unless it has been specifically selected by one -of the above means. The test does not affect the overall result of the test run. +The Explicit attribute causes a test or test fixture to be skipped unless it is explicitly selected for running. The +test or fixture will be run if it is selected by name or if it is included by use of a filter. A **not** filter, which +excludes certain tests, is not treated as an explicit selection and never causes an explicit test to be run. All other +filters are considered to explicitly select the tests that they match. See examples below. + +An optional string argument may be used to give the reason for marking the test Explicit. + +If a test or fixture with the Explicit attribute is encountered in the course of running tests, it is skipped unless it +has been specifically selected by one of the above means. The test does not affect the overall result of the test run. Explicit tests are displayed in the gui as skipped. > [!WARNING] -> While the C# syntax allows you to place an Explicit attribute on a SetUpFixture class, the attribute is ignored by NUnit and has no effect in current releases. +> While the C# syntax allows you to place an Explicit attribute on a SetUpFixture class, the attribute is +> ignored by NUnit and has no effect in current releases. ## Examples of Use -Using the console command-line to select tests, the following options will include any -explicit tests that fall under the selection. +Using the console command-line to select tests, the following options will include any explicit tests that fall under +the selection. ```none --test=My.Namespace.Fixture.Method diff --git a/docs/articles/nunit/writing-tests/attributes/fixturelifecycle.md b/docs/articles/nunit/writing-tests/attributes/fixturelifecycle.md index 7c8b49fa2..6bfeb05b3 100644 --- a/docs/articles/nunit/writing-tests/attributes/fixturelifecycle.md +++ b/docs/articles/nunit/writing-tests/attributes/fixturelifecycle.md @@ -6,15 +6,21 @@ uid: fixturelifecycleattribute Added in **NUnit 3.13** -The `FixtureLifeCycleAttribute` is used to indicate that an instance for a test fixture or all test fixtures in an assembly should be constructed for each test within the fixture or assembly. +The `FixtureLifeCycleAttribute` is used to indicate that an instance for a test fixture or all test fixtures in an +assembly should be constructed for each test within the fixture or assembly. -This attribute may be applied to a test fixture (class) or to a test assembly. It is useful in combination with the [Parallelizable Attribute](parallelizable.md) so that a new instance of a test fixture is constructed for every test within the test fixture. This allows tests to run in isolation without sharing instance fields and properties during parallel test runs. This make running parallel tests easier because it is easier to make your tests thread safe. +This attribute may be applied to a test fixture (class) or to a test assembly. It is useful in combination with the +[Parallelizable Attribute](parallelizable.md) so that a new instance of a test fixture is constructed for every test +within the test fixture. This allows tests to run in isolation without sharing instance fields and properties during +parallel test runs. This make running parallel tests easier because it is easier to make your tests thread safe. -This attribute can be applied to classes or to the entire test assembly. If applied to an assembly, it may be overridden at the class level. +This attribute can be applied to classes or to the entire test assembly. If applied to an assembly, it may be overridden +at the class level. ## LifeCycle Enumeration -The constructor of `FixtureLifeCycleAttribute` takes a `LifeCycle` attribute to indicate if a single instance of a test fixture should be created for all tests or if a new instance should be created for each test. +The constructor of `FixtureLifeCycleAttribute` takes a `LifeCycle` attribute to indicate if a single instance of a test +fixture should be created for all tests or if a new instance should be created for each test. Value | Meaning -------|--------- @@ -23,11 +29,16 @@ The constructor of `FixtureLifeCycleAttribute` takes a `LifeCycle` attribute to ## Notes -* When using `LifeCycle.InstancePerTestCase`, the [`OneTimeSetUp`](xref:onetimesetup-attribute) and [`OneTimeTearDown`](xref:onetimeteardown-attribute) methods must be static, and each are only called once. This is required so that the setup or teardown methods do not access instance fields or properties that are reset for every test. +* When using `LifeCycle.InstancePerTestCase`, the [`OneTimeSetUp`](xref:onetimesetup-attribute) and + [`OneTimeTearDown`](xref:onetimeteardown-attribute) methods must be static, and each are only called once. This is + required so that the setup or teardown methods do not access instance fields or properties that are reset for every + test. -* When using `LifeCycle.InstancePerTestCase`, a class's constructor will be called before every test is executed and `IDisposable` test fixtures will be disposed after the test is finished. +* When using `LifeCycle.InstancePerTestCase`, a class's constructor will be called before every test is executed and + `IDisposable` test fixtures will be disposed after the test is finished. -* [`SetUp`](xref:setup-attribute) and [`TearDown`](xref:teardown-attribute) methods are called before and after every test. +* [`SetUp`](xref:setup-attribute) and [`TearDown`](xref:teardown-attribute) methods are called before and after every + test. * The `Order` attribute is respected. diff --git a/docs/articles/nunit/writing-tests/attributes/ignore.md b/docs/articles/nunit/writing-tests/attributes/ignore.md index effd84b5f..1ffba635e 100644 --- a/docs/articles/nunit/writing-tests/attributes/ignore.md +++ b/docs/articles/nunit/writing-tests/attributes/ignore.md @@ -1,11 +1,12 @@ # Ignore -**IgnoreAttribute** is used to indicate that a test should not be executed for -some reason. Note that with NUnit 3, the reason must be specified. Ignored -tests are displayed by the runners as warnings in order to provide a reminder -that the test needs to be corrected or otherwise changed and re-instated. +**IgnoreAttribute** is used to indicate that a test should not be executed for some reason. Note that with NUnit 3, the +reason must be specified. Ignored tests are displayed by the runners as warnings in order to provide a reminder that the +test needs to be corrected or otherwise changed and re-instated. -Note that the **IgnoreAttribute** is attached to a method. If you have multiple test cases using the same method, adding it will ignore all the cases. To ignore individual test cases see [Ignoring Individual Test Cases](#ignoring-individual-test-cases) below. +Note that the **IgnoreAttribute** is attached to a method. If you have multiple test cases using the same method, adding +it will ignore all the cases. To ignore individual test cases see [Ignoring Individual Test +Cases](#ignoring-individual-test-cases) below. ## Test Fixture Syntax @@ -45,9 +46,8 @@ namespace NUnit.Tests ## Ignore Until -The `Until` named parameter allows you to ignore a test for a specific period of time, -after which the test will run normally. The until date must be a string -that can be parsed to a date. +The `Until` named parameter allows you to ignore a test for a specific period of time, after which the test will run +normally. The until date must be a string that can be parsed to a date. ```csharp [TestFixture] @@ -59,13 +59,13 @@ public class MyTests } ``` -In the above example, it's assumed that the test would fail if run. With the -IgnoreAttribute, it will give a warning until the specified date. After that -time, it will run normally and either pass or fail. +In the above example, it's assumed that the test would fail if run. With the IgnoreAttribute, it will give a warning +until the specified date. After that time, it will run normally and either pass or fail. ## Ignoring Individual Test Cases -The **IgnoreAttribute** causes all the test cases using the method on which it is placed to be ignored. Ignoring individual test cases is possible, depending on how they are specified. +The **IgnoreAttribute** causes all the test cases using the method on which it is placed to be ignored. Ignoring +individual test cases is possible, depending on how they are specified. Attribute | How to ignore a case --------------------|------------------------------------------------------------------ diff --git a/docs/articles/nunit/writing-tests/attributes/levelofparallelism.md b/docs/articles/nunit/writing-tests/attributes/levelofparallelism.md index a374545e8..824bb585c 100644 --- a/docs/articles/nunit/writing-tests/attributes/levelofparallelism.md +++ b/docs/articles/nunit/writing-tests/attributes/levelofparallelism.md @@ -1,11 +1,11 @@ # LevelOfParallelism -This is an _assembly-level_ attribute, which may be used to specify the level of -parallelism, that is, the maximum number of worker threads executing tests in the assembly. -It may be overridden using a command-line option in the console runner. +This is an _assembly-level_ attribute, which may be used to specify the level of parallelism, that is, the maximum +number of worker threads executing tests in the assembly. It may be overridden using a command-line option in the +console runner. -This attribute is optional. If it is not specified, NUnit uses the processor count or 2, -whichever is greater. For example, on a four processor machine the default value is 4. +This attribute is optional. If it is not specified, NUnit uses the processor count or 2, whichever is greater. For +example, on a four processor machine the default value is 4. ## Example @@ -17,7 +17,9 @@ The following code, which might be placed in AssemblyInfo.cs, sets the level of ## Platform Support -Parallel execution is supported by the NUnit framework on desktop .NET runtimes. It is not supported in our Portable or .NET Standard builds at this time, although the attributes are recognized without error in order to allow use in projects that build against multiple targets. +Parallel execution is supported by the NUnit framework on desktop .NET runtimes. It is not supported in our Portable or +.NET Standard builds at this time, although the attributes are recognized without error in order to allow use in +projects that build against multiple targets. ## See Also diff --git a/docs/articles/nunit/writing-tests/attributes/nonparallelizable.md b/docs/articles/nunit/writing-tests/attributes/nonparallelizable.md index d28f5b226..d319c63a1 100644 --- a/docs/articles/nunit/writing-tests/attributes/nonparallelizable.md +++ b/docs/articles/nunit/writing-tests/attributes/nonparallelizable.md @@ -1,14 +1,20 @@ # NonParallelizable -This attribute is used to indicate that the test on which it appears may not be run in parallel with any other tests. The attribute takes no arguments and may be used at the assembly, class or method level. +This attribute is used to indicate that the test on which it appears may not be run in parallel with any other tests. +The attribute takes no arguments and may be used at the assembly, class or method level. -When used at the assembly level, its only effect is that execution begins on the non-parallel queue. Test suites, fixtures and test cases will continue to run on the same thread unless a fixture or method is marked with the [Parallelizable Attribute](parallelizable.md). +When used at the assembly level, its only effect is that execution begins on the non-parallel queue. Test suites, +fixtures and test cases will continue to run on the same thread unless a fixture or method is marked with the +[Parallelizable Attribute](parallelizable.md). -When used on a test fixture or method, that test will be queued on the non-parallel queue and will not run while other tests marked as Parallelizable are being run. +When used on a test fixture or method, that test will be queued on the non-parallel queue and will not run while other +tests marked as Parallelizable are being run. ## Platform Support -Parallel execution is not supported by all builds of the NUnit Framework, although the attributes are recognized without error in order to allow use in projects that build against multiple targets. Currently, only the .NET Standard 1.6 build does not support parallelization. +Parallel execution is not supported by all builds of the NUnit Framework, although the attributes are recognized without +error in order to allow use in projects that build against multiple targets. Currently, only the .NET Standard 1.6 build +does not support parallelization. ## See Also diff --git a/docs/articles/nunit/writing-tests/attributes/onetimesetup.md b/docs/articles/nunit/writing-tests/attributes/onetimesetup.md index e82f08f4c..f60d2b68e 100644 --- a/docs/articles/nunit/writing-tests/attributes/onetimesetup.md +++ b/docs/articles/nunit/writing-tests/attributes/onetimesetup.md @@ -4,16 +4,15 @@ uid: onetimesetup-attribute # OneTimeSetUp -This attribute is to identify methods that are called once prior to executing any of the tests -in a fixture. It may appear on methods of a TestFixture or a SetUpFixture. +This attribute is to identify methods that are called once prior to executing any of the tests in a fixture. It may +appear on methods of a TestFixture or a SetUpFixture. -OneTimeSetUp methods may be either static or -instance methods and you may define more than one of them in a fixture. -Normally, multiple OneTimeSetUp methods are only defined at different levels -of an inheritance hierarchy, as explained below. +OneTimeSetUp methods may be either static or instance methods and you may define more than one of them in a fixture. +Normally, multiple OneTimeSetUp methods are only defined at different levels of an inheritance hierarchy, as explained +below. -If a OneTimeSetUp method fails or throws an exception, none of the tests -in the fixture are executed and a failure or error is reported. +If a OneTimeSetUp method fails or throws an exception, none of the tests in the fixture are executed and a failure or +error is reported. ## Example @@ -43,28 +42,38 @@ namespace NUnit.Tests ### Inheritance -The OneTimeSetUp attribute is inherited from any base class. Therefore, if a base -class has defined a OneTimeSetUp method, that method will be called -before any methods in the derived class. +The OneTimeSetUp attribute is inherited from any base class. Therefore, if a base class has defined a OneTimeSetUp +method, that method will be called before any methods in the derived class. -You may define a OneTimeSetUp method -in the base class and another in the derived class. NUnit will call base -class OneTimeSetUp methods before those in the derived classes. +You may define a OneTimeSetUp method in the base class and another in the derived class. NUnit will call base class +OneTimeSetUp methods before those in the derived classes. > [!WARNING] -> If a base class OneTimeSetUp method is overridden in the derived class, NUnit will not call the base class OneTimeSetUp method; NUnit does not anticipate usage that includes hiding the base method. Note that you may have a different name for each method; as long as both have the `[OneTimeSetUp]` attribute present, each will be called in the correct order. +> If a base class OneTimeSetUp method is overridden in the derived class, NUnit will not call the base class +> OneTimeSetUp method; NUnit does not anticipate usage that includes hiding the base method. Note that you may have a +> different name for each method; as long as both have the `[OneTimeSetUp]` attribute present, each will be called in +> the correct order. ## Notes -* Although it is possible to define multiple [`OneTimeSetUp`](xref:onetimesetup-attribute) methods in the same class, you should rarely do so. Unlike methods defined in separate classes in the inheritance hierarchy, the order in which they are executed is not guaranteed. +* Although it is possible to define multiple [`OneTimeSetUp`](xref:onetimesetup-attribute) methods in the same class, + you should rarely do so. Unlike methods defined in separate classes in the inheritance hierarchy, the order in which + they are executed is not guaranteed. * [`OneTimeSetUp`](xref:onetimesetup-attribute) methods may be async if running under .NET 4.0 or higher. -* [`OneTimeSetUp`](xref:onetimesetup-attribute) methods run in the context of the [`TestFixture`](xref:testfixtureattribute) or [`SetUpFixture`](xref:setupfixture-attribute), which is separate from the context of any individual test cases. It's important to keep this in mind when using [`TestContext`](xref:testcontext) methods and properties within the method. +* [`OneTimeSetUp`](xref:onetimesetup-attribute) methods run in the context of the + [`TestFixture`](xref:testfixtureattribute) or [`SetUpFixture`](xref:setupfixture-attribute), which is separate from + the context of any individual test cases. It's important to keep this in mind when using + [`TestContext`](xref:testcontext) methods and properties within the method. -* When using [`FixtureLifeCycle`](xref:fixturelifecycleattribute) with `LifeCycle.InstancePerTestCase`, the [`OneTimeSetUp`](xref:onetimesetup-attribute) method must be static and is only called once. This is required so that the setup method does not access instance fields or properties that are reset for every test. +* When using [`FixtureLifeCycle`](xref:fixturelifecycleattribute) with `LifeCycle.InstancePerTestCase`, the + [`OneTimeSetUp`](xref:onetimesetup-attribute) method must be static and is only called once. This is required so that + the setup method does not access instance fields or properties that are reset for every test. -* When set on a base class the method is invoked for each fixture that inherits from this base class and its invoked for the base class too if its not abstract. Use [`SetUpFixture`](xref:setupfixture-attribute) if this only needs to be run once or put the code in a static constructor. +* When set on a base class the method is invoked for each fixture that inherits from this base class and its invoked for + the base class too if its not abstract. Use [`SetUpFixture`](xref:setupfixture-attribute) if this only needs to be run + once or put the code in a static constructor. ## See Also diff --git a/docs/articles/nunit/writing-tests/attributes/onetimeteardown.md b/docs/articles/nunit/writing-tests/attributes/onetimeteardown.md index 255711821..d221f7f5f 100644 --- a/docs/articles/nunit/writing-tests/attributes/onetimeteardown.md +++ b/docs/articles/nunit/writing-tests/attributes/onetimeteardown.md @@ -4,13 +4,12 @@ uid: onetimeteardown-attribute # OneTimeTearDown -This attribute is to identify methods that are called once after executing all the tests -in a fixture. It may appear on methods of a TestFixture or a SetUpFixture. +This attribute is to identify methods that are called once after executing all the tests in a fixture. It may appear on +methods of a TestFixture or a SetUpFixture. -OneTimeTearDown methods may be either static or -instance methods and you may define more than one of them in a fixture. -Normally, multiple OneTimeTearDown methods are only defined at different levels -of an inheritance hierarchy, as explained below. +OneTimeTearDown methods may be either static or instance methods and you may define more than one of them in a fixture. +Normally, multiple OneTimeTearDown methods are only defined at different levels of an inheritance hierarchy, as +explained below. ## Example @@ -40,26 +39,33 @@ namespace NUnit.Tests ## Inheritance -The OneTimeTearDown attribute is inherited from any base class. Therefore, if a base -class has defined a OneTimeTearDown method, that method will be called -after any test methods in the derived class. +The OneTimeTearDown attribute is inherited from any base class. Therefore, if a base class has defined a OneTimeTearDown +method, that method will be called after any test methods in the derived class. -You may define a OneTimeTearDown method -in the base class and another in the derived class. NUnit will call base -class OneTimeTearDown methods after those in the derived classes. +You may define a OneTimeTearDown method in the base class and another in the derived class. NUnit will call base class +OneTimeTearDown methods after those in the derived classes. > [!WARNING] -> If a base class OneTimeTearDown method is overridden in the derived class, NUnit will not call the base class OneTimeTearDown method; NUnit does not anticipate usage that includes hiding the base method. Note that you may have a different name for each method; as long as both have the `[OneTimeTearDown]` attribute present, each will be called in the correct order. +> If a base class OneTimeTearDown method is overridden in the derived class, NUnit will not call the base +> class OneTimeTearDown method; NUnit does not anticipate usage that includes hiding the base method. Note that you may +> have a different name for each method; as long as both have the `[OneTimeTearDown]` attribute present, each will be +> called in the correct order. ## Notes -* Although it is possible to define multiple `OneTimeTearDown` methods in the same class, you should rarely do so. Unlike methods defined in separate classes in the inheritance hierarchy, the order in which they are executed is not guaranteed. +* Although it is possible to define multiple `OneTimeTearDown` methods in the same class, you should rarely do so. + Unlike methods defined in separate classes in the inheritance hierarchy, the order in which they are executed is not + guaranteed. * `OneTimeTearDown` methods may be async if running under .NET 4.0 or higher. -* `OneTimeTearDown` methods run in the context of the [`TestFixture`](xref:testfixtureattribute) or [`SetUpFixture`](xref:setupfixture-attribute), which is separate from the context of any individual test cases. It's important to keep this in mind when using [`TestContext`](xref:testcontext) methods and properties within the method. +* `OneTimeTearDown` methods run in the context of the [`TestFixture`](xref:testfixtureattribute) or + [`SetUpFixture`](xref:setupfixture-attribute), which is separate from the context of any individual test cases. It's + important to keep this in mind when using [`TestContext`](xref:testcontext) methods and properties within the method. -* When using [`FixtureLifeCycle`](xref:fixturelifecycleattribute) with `LifeCycle.InstancePerTestCase`, the `OneTimeTearDown` method must be static and is only called once. This is required so that the teardown method does not access instance fields or properties that are reset for every test. +* When using [`FixtureLifeCycle`](xref:fixturelifecycleattribute) with `LifeCycle.InstancePerTestCase`, the + `OneTimeTearDown` method must be static and is only called once. This is required so that the teardown method does not + access instance fields or properties that are reset for every test. ## See Also diff --git a/docs/articles/nunit/writing-tests/attributes/order.md b/docs/articles/nunit/writing-tests/attributes/order.md index 8ba581769..259d8c052 100644 --- a/docs/articles/nunit/writing-tests/attributes/order.md +++ b/docs/articles/nunit/writing-tests/attributes/order.md @@ -1,6 +1,8 @@ # Order -The **OrderAttribute** may be placed on a test method or fixture to specify the order in which tests are run within the fixture or other suite in which they are contained. Ordering is given by the required `order` argument to the attribute, an `int`. +The **OrderAttribute** may be placed on a test method or fixture to specify the order in which tests are run within the +fixture or other suite in which they are contained. Ordering is given by the required `order` argument to the attribute, +an `int`. ## Example @@ -27,8 +29,11 @@ public class MyFixture ## Notes -1. As stated, ordering is local to the test that contains the ordered tests. For test cases (methods) ordering applies within the containing fixture. For fixtures it applies within the containing namespace. There is no facility in NUnit to order tests globally. +1. As stated, ordering is local to the test that contains the ordered tests. For test cases (methods) ordering applies + within the containing fixture. For fixtures it applies within the containing namespace. There is no facility in NUnit + to order tests globally. 2. Tests with an `OrderAttribute` argument are started before any tests without the attribute. 3. Ordered tests are started in ascending order of the `order` argument. 4. Among tests with the same `order` value or without the attribute, execution order is indeterminate. -5. Tests do not wait for prior tests to finish. If multiple threads are in use, a test may be started while some earlier tests are still being run. +5. Tests do not wait for prior tests to finish. If multiple threads are in use, a test may be started while some earlier + tests are still being run. diff --git a/docs/articles/nunit/writing-tests/attributes/parallelizable.md b/docs/articles/nunit/writing-tests/attributes/parallelizable.md index cf10adadb..1a41de906 100644 --- a/docs/articles/nunit/writing-tests/attributes/parallelizable.md +++ b/docs/articles/nunit/writing-tests/attributes/parallelizable.md @@ -6,14 +6,22 @@ uid: parallelizableattribute Added in **NUnit 3.7** -The `ParallelizableAttribute` is used to indicate that a test and/or its descendants may be run in parallel with other tests. By default, no parallel execution takes place. +The `ParallelizableAttribute` is used to indicate that a test and/or its descendants may be run in parallel with other +tests. By default, no parallel execution takes place. -When used without an argument, `Parallelizable` causes the test fixture or method on which it is placed to be queued for execution in parallel with other parallelizable tests. It may be used at the assembly, class or method level. +When used without an argument, `Parallelizable` causes the test fixture or method on which it is placed to be queued for +execution in parallel with other parallelizable tests. It may be used at the assembly, class or method level. > [!WARNING] -> When tests are run in parallel, you are responsible for the thread safety of your tests. Tests that run at the same time and modify instance fields or properties without locks will cause unexpected behavior as they would in any multi-threaded program. If you are using fields or properties between parallel tests consider using the [`FixtureLifeCycleAttribute`](xref:fixturelifecycleattribute) to construct a new instance of a test fixture (class) for each test that is run. +> When tests are run in parallel, you are responsible for the thread safety of your tests. Tests that run at +> the same time and modify instance fields or properties without locks will cause unexpected behavior as they would in +> any multi-threaded program. If you are using fields or properties between parallel tests consider using the +> [`FixtureLifeCycleAttribute`](xref:fixturelifecycleattribute) to construct a new instance of a test fixture (class) +> for each test that is run. -The constructor takes an optional `ParallelScope` enumeration argument (see below), which indicates whether the attribute applies to the item itself, to its descendants or both. It defaults to `ParallelScope.Self`. The Scope may also be specified using the constructor argument `scope:`, for example; +The constructor takes an optional `ParallelScope` enumeration argument (see below), which indicates whether the +attribute applies to the item itself, to its descendants or both. It defaults to `ParallelScope.Self`. The Scope may +also be specified using the constructor argument `scope:`, for example; ```csharp [Parallelizable(scope: ParallelScope.All)] @@ -21,7 +29,8 @@ The constructor takes an optional `ParallelScope` enumeration argument (see belo ## ParallelScope Enumeration -This is a **[Flags]** enumeration used to specify which tests may run in parallel. It applies to the test upon which it appears and any subordinate tests. The following values are available to users: +This is a **[Flags]** enumeration used to specify which tests may run in parallel. It applies to the test upon which it +appears and any subordinate tests. The following values are available to users: Value | Meaning | Valid On -------|---------|--------- @@ -32,11 +41,14 @@ This is a **[Flags]** enumeration used to specify which tests may run in paralle ## Notes -* Some values are invalid on certain elements, although they will compile. NUnit will report any tests so marked as invalid and will produce an error message. +* Some values are invalid on certain elements, although they will compile. NUnit will report any tests so marked as + invalid and will produce an error message. -* The `ParallelScope` enum has additional values, which are used internally but are not visible to users through Intellisense. +* The `ParallelScope` enum has additional values, which are used internally but are not visible to users through + Intellisense. -* The `ParallelizableAttribute` may be specified on multiple levels of the tests. Settings at a higher level may affect lower level tests, unless those lower-level tests override the inherited settings. +* The `ParallelizableAttribute` may be specified on multiple levels of the tests. Settings at a higher level may affect + lower level tests, unless those lower-level tests override the inherited settings. ## See Also diff --git a/docs/articles/nunit/writing-tests/attributes/platform.md b/docs/articles/nunit/writing-tests/attributes/platform.md index 1c03a30b0..8c20b575e 100644 --- a/docs/articles/nunit/writing-tests/attributes/platform.md +++ b/docs/articles/nunit/writing-tests/attributes/platform.md @@ -1,17 +1,14 @@ # Platform -The Platform attribute is used to specify platforms for which a test or fixture -should be run. Platforms are specified using case-insensitive string values -and may be either included or excluded from the run by use of the Include or -Exclude properties respectively. Platforms to be included may alternatively -be specified as an argument to the PlatformAttribute constructor. In either -case, multiple comma-separated values may be specified. - -If a test or fixture with the Platform attribute does not satisfy the specified -platform requirements it is skipped. The test does not affect the outcome of -the run at all: it is not considered as ignored and is not even counted in -the total number of tests. _[Ed.: Check this.]_ In the gui, the tree node for the test remains -gray and the status bar color is not affected. +The Platform attribute is used to specify platforms for which a test or fixture should be run. Platforms are specified +using case-insensitive string values and may be either included or excluded from the run by use of the Include or +Exclude properties respectively. Platforms to be included may alternatively be specified as an argument to the +PlatformAttribute constructor. In either case, multiple comma-separated values may be specified. + +If a test or fixture with the Platform attribute does not satisfy the specified platform requirements it is skipped. The +test does not affect the outcome of the run at all: it is not considered as ignored and is not even counted in the total +number of tests. _[Ed.: Check this.]_ In the gui, the tree node for the test remains gray and the status bar color is +not affected. ## Test Fixture Syntax @@ -50,8 +47,7 @@ namespace NUnit.Tests ## Platform Specifiers -The following values are recognized as platform specifiers. -They may be expressed in upper, lower or mixed case. +The following values are recognized as platform specifiers. They may be expressed in upper, lower or mixed case. ### Operating System @@ -86,7 +82,9 @@ They may be expressed in upper, lower or mixed case. * MacOsX * XBox -A list of supported platform identifiers can also be obtained from the constant string `PlatformHelper.OSPlatforms` of the NUnit assembly you use. Note that this is for informational purposes only, because the `PlatformHelper` is considered an internal type and shall not be used in production. +A list of supported platform identifiers can also be obtained from the constant string `PlatformHelper.OSPlatforms` of +the NUnit assembly you use. Note that this is for informational purposes only, because the `PlatformHelper` is +considered an internal type and shall not be used in production. ### Architecture diff --git a/docs/articles/nunit/writing-tests/attributes/random.md b/docs/articles/nunit/writing-tests/attributes/random.md index 70ef334dd..dce5cfb10 100644 --- a/docs/articles/nunit/writing-tests/attributes/random.md +++ b/docs/articles/nunit/writing-tests/attributes/random.md @@ -4,16 +4,12 @@ uid: randomattribute # Random -The **RandomAttribute** is used to specify a set of random values to be provided -for an individual numeric parameter, or `Guid` of a parameterized test method. Since -NUnit combines the data provided for each parameter into a set of -test cases, data must be provided for all parameters if it is -provided for any of them. +The **RandomAttribute** is used to specify a set of random values to be provided for an individual numeric parameter, or +`Guid` of a parameterized test method. Since NUnit combines the data provided for each parameter into a set of test +cases, data must be provided for all parameters if it is provided for any of them. -By default, NUnit creates test cases from all possible combinations -of the datapoints provided on parameters - the combinatorial approach. -This default may be modified by use of specific attributes on the -test method itself. +By default, NUnit creates test cases from all possible combinations of the datapoints provided on parameters - the +combinatorial approach. This default may be modified by use of specific attributes on the test method itself. RandomAttribute supports the following constructors: @@ -31,23 +27,27 @@ public Random(double min, double max, int count); public Random(float min, float max, int count); ``` -In the first form, without minimum and maximum values, the attribute automatically generates values of the appropriate numeric Type or `Guid` for the argument provided, using the `Randomizer` object associated with the current context. See [Randomizer Methods](xref:randomizermethods) for details. +In the first form, without minimum and maximum values, the attribute automatically generates values of the appropriate +numeric Type or `Guid` for the argument provided, using the `Randomizer` object associated with the current context. See +[Randomizer Methods](xref:randomizermethods) for details. -In general, the forms that specify a minimum and maximum should be used on arguments of the same type. However, the following exceptions are supported: +In general, the forms that specify a minimum and maximum should be used on arguments of the same type. However, the +following exceptions are supported: * You may use an int range on arguments of type short, ushort, byte, sbyte and decimal. * You may use a double range on arguments of type decimal. -Note that there is no constructor taking decimal values for min and max. This is because .NET does not support use of decimal in an attribute constructor. +Note that there is no constructor taking decimal values for min and max. This is because .NET does not support use of +decimal in an attribute constructor. > [!NOTE] > `Guid` support for `RandomAttribute` is available from version 4.0 onwards. ## Example -The following test will be executed fifteen times, three times -for each value of x, each combined with 5 random doubles from -1.0 to +1.0. +The following test will be executed fifteen times, three times for each value of x, each combined with 5 random doubles +from -1.0 to +1.0. ```csharp [Test] diff --git a/docs/articles/nunit/writing-tests/attributes/requiresthread.md b/docs/articles/nunit/writing-tests/attributes/requiresthread.md index 9a6edd2d7..73f524002 100644 --- a/docs/articles/nunit/writing-tests/attributes/requiresthread.md +++ b/docs/articles/nunit/writing-tests/attributes/requiresthread.md @@ -1,11 +1,11 @@ # RequiresThread -The **RequiresThreadAttribute** is used to indicate that a test method, -class or assembly should be run on a separate thread. Optionally, the -desired apartment for the thread may be specified in the constructor. +The **RequiresThreadAttribute** is used to indicate that a test method, class or assembly should be run on a separate +thread. Optionally, the desired apartment for the thread may be specified in the constructor. > [!NOTE] -> This attribute, used with or without an ApartmentState argument will **always** result in creation of a new thread. To create a thread **only** if the current ApartmentState is not appropriate, use the **ApartmentAttribute**. +> This attribute, used with or without an ApartmentState argument will **always** result in creation of a new +> thread. To create a thread **only** if the current ApartmentState is not appropriate, use the **ApartmentAttribute**. ## Examples diff --git a/docs/articles/nunit/writing-tests/attributes/retry.md b/docs/articles/nunit/writing-tests/attributes/retry.md index 790254743..a50f2c94a 100644 --- a/docs/articles/nunit/writing-tests/attributes/retry.md +++ b/docs/articles/nunit/writing-tests/attributes/retry.md @@ -4,6 +4,10 @@ RetryAttribute is used on a test method to specify that it should be rerun if it Notes: -1. The argument you specify is the total number of attempts and __not__ the number of retries after an initial failure. So `[Retry(1)]` does nothing and should not be used. -2. It is not currently possible to use `RetryAttribute` on a `TestFixture` or any other type of test suite. Only single tests may be repeated. -3. If a test has an unexpected exception, an error result is returned and it is not retried. Only assertion failures can trigger a retry. To convert an unexpected exception into an assertion failure, see the [ThrowsConstraint](xref:throwsconstraint). +1. The argument you specify is the total number of attempts and __not__ the number of retries after an initial failure. + So `[Retry(1)]` does nothing and should not be used. +2. It is not currently possible to use `RetryAttribute` on a `TestFixture` or any other type of test suite. Only single + tests may be repeated. +3. If a test has an unexpected exception, an error result is returned and it is not retried. Only assertion failures can + trigger a retry. To convert an unexpected exception into an assertion failure, see the + [ThrowsConstraint](xref:throwsconstraint). diff --git a/docs/articles/nunit/writing-tests/attributes/sequential.md b/docs/articles/nunit/writing-tests/attributes/sequential.md index 6ed5b136a..1bbc5146c 100644 --- a/docs/articles/nunit/writing-tests/attributes/sequential.md +++ b/docs/articles/nunit/writing-tests/attributes/sequential.md @@ -4,14 +4,13 @@ uid: sequentialattribute # Sequential -The **SequentialAttribute** is used on a test to specify that NUnit should -generate test cases by selecting individual data items provided -for the parameters of the test, without generating additional -combinations. +The **SequentialAttribute** is used on a test to specify that NUnit should generate test cases by selecting individual +data items provided for the parameters of the test, without generating additional combinations. > [!NOTE] -> If parameter data is provided by multiple attributes, the order in which NUnit uses the data items is not guaranteed. However, -it can be expected to remain constant for a given runtime and operating system. For best results with **SequentialAttribute** use only one data attribute on each parameter. +> If parameter data is provided by multiple attributes, the order in which NUnit uses the data items is not +> guaranteed. However, it can be expected to remain constant for a given runtime and operating system. For best results +with **SequentialAttribute** use only one data attribute on each parameter. ## Example diff --git a/docs/articles/nunit/writing-tests/attributes/setup.md b/docs/articles/nunit/writing-tests/attributes/setup.md index 06482f596..4dc6eacfc 100644 --- a/docs/articles/nunit/writing-tests/attributes/setup.md +++ b/docs/articles/nunit/writing-tests/attributes/setup.md @@ -4,16 +4,13 @@ uid: setup-attribute # SetUp -This attribute is used inside a [TestFixture](xref:testfixtureattribute) -to provide a common set of functions that are performed just before each test method is called. +This attribute is used inside a [TestFixture](xref:testfixtureattribute) to provide a common set of functions that are +performed just before each test method is called. -SetUp methods may be either static or -instance methods and you may define more than one of them in a fixture. -Normally, multiple SetUp methods are only defined at different levels -of an inheritance hierarchy, as explained below. +SetUp methods may be either static or instance methods and you may define more than one of them in a fixture. Normally, +multiple SetUp methods are only defined at different levels of an inheritance hierarchy, as explained below. -If a SetUp method fails or throws an exception, the test is not executed -and a failure or error is reported. +If a SetUp method fails or throws an exception, the test is not executed and a failure or error is reported. ## Example @@ -40,23 +37,21 @@ namespace NUnit.Tests ## Inheritance -The SetUp attribute is inherited from any base class. Therefore, if a base -class has defined a SetUp method, that method will be called -before each test method in the derived class. +The SetUp attribute is inherited from any base class. Therefore, if a base class has defined a SetUp method, that method +will be called before each test method in the derived class. -You may define a SetUp method -in the base class and another in the derived class. NUnit will call base -class SetUp methods before those in the derived classes. +You may define a SetUp method in the base class and another in the derived class. NUnit will call base class SetUp +methods before those in the derived classes. > [!WARNING] -> If a base class SetUp method is overridden in the derived class, NUnit will not call the base class SetUp method; NUnit does not anticipate usage that includes hiding the base method. Note that you may have a different name for each method; as long as both have the `[SetUp]` attribute present, each will be called in the correct order. +> If a base class SetUp method is overridden in the derived class, NUnit will not call the base class SetUp +> method; NUnit does not anticipate usage that includes hiding the base method. Note that you may have a different name +> for each method; as long as both have the `[SetUp]` attribute present, each will be called in the correct order. ## Notes -1. Although it is possible to define multiple SetUp methods - in the same class, you should rarely do so. Unlike methods defined in - separate classes in the inheritance hierarchy, the order in which they - are executed is not guaranteed. +1. Although it is possible to define multiple SetUp methods in the same class, you should rarely do so. Unlike methods + defined in separate classes in the inheritance hierarchy, the order in which they are executed is not guaranteed. 2. You may specify an async method (`async` keyword in c#) if necessary, when running under .NET 4.0 or higher. diff --git a/docs/articles/nunit/writing-tests/attributes/singlethreaded.md b/docs/articles/nunit/writing-tests/attributes/singlethreaded.md index cac64b9f3..a2d25247b 100644 --- a/docs/articles/nunit/writing-tests/attributes/singlethreaded.md +++ b/docs/articles/nunit/writing-tests/attributes/singlethreaded.md @@ -1,5 +1,6 @@ # SingleThreaded -`SingleThreadedAttribute` is used on a TestFixture and indicates that the OneTimeSetUp, OneTimeTearDown and all the child tests must run on the same thread. +`SingleThreadedAttribute` is used on a TestFixture and indicates that the OneTimeSetUp, OneTimeTearDown and all the +child tests must run on the same thread. When using this attribute, any `ParallelScope` setting is ignored. diff --git a/docs/articles/nunit/writing-tests/attributes/teardown.md b/docs/articles/nunit/writing-tests/attributes/teardown.md index 7f0169acd..47fd269d3 100644 --- a/docs/articles/nunit/writing-tests/attributes/teardown.md +++ b/docs/articles/nunit/writing-tests/attributes/teardown.md @@ -4,11 +4,15 @@ uid: teardown-attribute # TearDown -This attribute is used inside a [TestFixture](xref:testfixtureattribute) to provide a common set of functions that are performed after each test method. +This attribute is used inside a [TestFixture](xref:testfixtureattribute) to provide a common set of functions that are +performed after each test method. -TearDown methods may be either static or instance methods and you may define more than one of them in a fixture. Normally, multiple TearDown methods are only defined at different levels of an inheritance hierarchy, as explained below. +TearDown methods may be either static or instance methods and you may define more than one of them in a fixture. +Normally, multiple TearDown methods are only defined at different levels of an inheritance hierarchy, as explained +below. -So long as any SetUp method runs without error, the TearDown method is guaranteed to run. For example, it is not guaranteed to run if a SetUp method fails or throws an exception. +So long as any SetUp method runs without error, the TearDown method is guaranteed to run. For example, it is not +guaranteed to run if a SetUp method fails or throws an exception. ## Example @@ -35,23 +39,23 @@ namespace NUnit.Tests ## Inheritance -The TearDown attribute is inherited from any base class. Therefore, if a base -class has defined a TearDown method, that method will be called -after each test method in the derived class. +The TearDown attribute is inherited from any base class. Therefore, if a base class has defined a TearDown method, that +method will be called after each test method in the derived class. -You may define a TearDown method -in the base class and another in the derived class. NUnit will call base -class TearDown methods after those in the derived classes. +You may define a TearDown method in the base class and another in the derived class. NUnit will call base class TearDown +methods after those in the derived classes. > [!WARNING] -> If a base class TearDown method is overridden in the derived class, NUnit will not call the base class TearDown method; NUnit does not anticipate usage that includes hiding the base method. Note that you may have a different name for each method; as long as both have the `[TearDown]` attribute present, each will be called in the correct order. +> If a base class TearDown method is overridden in the derived class, NUnit will not call the base class +> TearDown method; NUnit does not anticipate usage that includes hiding the base method. Note that you may have a +> different name for each method; as long as both have the `[TearDown]` attribute present, each will be called in the +> correct order. ## Notes -1. Although it is possible to define multiple TearDown methods - in the same class, you should rarely do so. Unlike methods defined in - separate classes in the inheritance hierarchy, the order in which they - are executed is not guaranteed. +1. Although it is possible to define multiple TearDown methods in the same class, you should rarely do so. Unlike + methods defined in separate classes in the inheritance hierarchy, the order in which they are executed is not + guaranteed. 2. TearDown methods may be async if running under .NET 4.0 or higher. diff --git a/docs/articles/nunit/writing-tests/attributes/test.md b/docs/articles/nunit/writing-tests/attributes/test.md index d6b6edfdc..52eca6efc 100644 --- a/docs/articles/nunit/writing-tests/attributes/test.md +++ b/docs/articles/nunit/writing-tests/attributes/test.md @@ -1,25 +1,22 @@ # Test -The `Test` attribute is one way of marking a method inside a TestFixture class -as a test. It is normally used for simple (non-parameterized) tests but may -also be applied to parameterized tests without causing any extra test cases -to be generated. See [Parameterized Tests](xref:parameterizedtests) for more info. +The `Test` attribute is one way of marking a method inside a TestFixture class as a test. It is normally used for simple +(non-parameterized) tests but may also be applied to parameterized tests without causing any extra test cases to be +generated. See [Parameterized Tests](xref:parameterizedtests) for more info. The test method may be either an instance or a static method. -Test methods targeting .Net 4.0 or higher may be marked as **async** and NUnit will wait for the method to complete before recording the result and moving on to the next test. Async -test methods must return `Task` if no value is returned, -or `Task` if a value of type T is returned. +Test methods targeting .Net 4.0 or higher may be marked as **async** and NUnit will wait for the method to complete +before recording the result and moving on to the next test. Async test methods must return `Task` if no value is +returned, or `Task` if a value of type T is returned. -If the programmer marks a test method that does not have the correct signature -it will be considered as not runnable. +If the programmer marks a test method that does not have the correct signature it will be considered as not runnable. -If the test method returns a value, you must pass in the `ExpectedResult` -named parameter to the Test attribute. This expected return value will be -checked for equality with the return value of the test method. +If the test method returns a value, you must pass in the `ExpectedResult` named parameter to the Test attribute. This +expected return value will be checked for equality with the return value of the test method. -The test `Description` may be specified as a named parameter. This is exactly equivalent -to using the `DescriptionAttribute` on the test. +The test `Description` may be specified as a named parameter. This is exactly equivalent to using the +`DescriptionAttribute` on the test. ## Examples diff --git a/docs/articles/nunit/writing-tests/attributes/testcase.md b/docs/articles/nunit/writing-tests/attributes/testcase.md index 825eb9713..78d4cafc0 100644 --- a/docs/articles/nunit/writing-tests/attributes/testcase.md +++ b/docs/articles/nunit/writing-tests/attributes/testcase.md @@ -4,27 +4,25 @@ uid: testcaseattribute # TestCase -`TestCaseAttribute` serves the dual purpose of marking a method with -parameters as a test method and providing inline data to be used when -invoking that method. Here is an example of a test being run three -times, with three different sets of data: +`TestCaseAttribute` serves the dual purpose of marking a method with parameters as a test method and providing inline +data to be used when invoking that method. Here is an example of a test being run three times, with three different sets +of data: [!code-csharp[BasicTestCase](~/snippets/Snippets.NUnit/Attributes/TestCaseAttributeExamples.cs#BasicTestCase)] > [!NOTE] -> Because arguments to .NET attributes are limited in terms of the Types that may be used, NUnit will make some attempt to convert the supplied values using `Convert.ChangeType()` before supplying it to the test. +> Because arguments to .NET attributes are limited in terms of the Types that may be used, NUnit will make some +> attempt to convert the supplied values using `Convert.ChangeType()` before supplying it to the test. -**TestCaseAttribute** may appear one or more times on a test method, -which may also carry other attributes providing test data. -The method may optionally be marked with the [Test Attribute](test.md) as well. +**TestCaseAttribute** may appear one or more times on a test method, which may also carry other attributes providing +test data. The method may optionally be marked with the [Test Attribute](test.md) as well. -By using the named parameter `ExpectedResult` this test set may be simplified -further: +By using the named parameter `ExpectedResult` this test set may be simplified further: [!code-csharp[TestCaseWithExpectedResult](~/snippets/Snippets.NUnit/Attributes/TestCaseAttributeExamples.cs#TestCaseWithExpectedResult)] -In the above example, NUnit checks that the return -value of the method is equal to the expected result provided on the attribute. +In the above example, NUnit checks that the return value of the method is equal to the expected result provided on the +attribute. TestCaseAttribute supports a number of additional named parameters: @@ -38,15 +36,15 @@ TestCaseAttribute supports a number of additional named parameters: * **IgnoreReason** causes this test case to be ignored and specifies the reason. * **IncludePlatform** specifies a comma-delimited list of platforms on which the test should run. * **Reason** specifies the reason for not running this test case. Use in conjunction with **Explicit**. -* **TestName** provides a name for the test. If not specified, a name is generated based on the method name and the arguments provided. See [Template Based Test Naming](xref:templatebasedtestnaming). +* **TestName** provides a name for the test. If not specified, a name is generated based on the method name and the + arguments provided. See [Template Based Test Naming](xref:templatebasedtestnaming). * **TestOf** specifies the Type that this test is testing ## Order of Execution -Individual test cases are executed in the order in which NUnit discovers them. -This order does **not** necessarily follow the lexical order of the attributes -and will often vary between different compilers or different versions of the CLR. +Individual test cases are executed in the order in which NUnit discovers them. This order does **not** necessarily +follow the lexical order of the attributes and will often vary between different compilers or different versions of the +CLR. -As a result, when **TestCaseAttribute** appears multiple times on a method -or when other data-providing attributes are used in combination with -**TestCaseAttribute**, the order of the test cases is undefined. +As a result, when **TestCaseAttribute** appears multiple times on a method or when other data-providing attributes are +used in combination with **TestCaseAttribute**, the order of the test cases is undefined. diff --git a/docs/articles/nunit/writing-tests/attributes/testcasesource.md b/docs/articles/nunit/writing-tests/attributes/testcasesource.md index 35532d60b..dac2e5214 100644 --- a/docs/articles/nunit/writing-tests/attributes/testcasesource.md +++ b/docs/articles/nunit/writing-tests/attributes/testcasesource.md @@ -4,35 +4,39 @@ uid: testcasesourceattribute # TestCaseSource -`TestCaseSourceAttribute` is used on a parameterized test method to -identify the source from which the required arguments will be provided. -The attribute additionally identifies the method as a test method. -The data is kept separate from the test itself and may be used by multiple -test methods. See [Parameterized Tests](xref:parameterizedtests) for a general introduction to -tests with arguments. +`TestCaseSourceAttribute` is used on a parameterized test method to identify the source from which the required +arguments will be provided. The attribute additionally identifies the method as a test method. The data is kept separate +from the test itself and may be used by multiple test methods. See [Parameterized Tests](xref:parameterizedtests) for a +general introduction to tests with arguments. ## Usage -Consider a test of the divide operation, taking three arguments: the numerator, the denominator and the expected result. We can specify the test and its data using one of the forms of **TestCaseSourceAttribute**: +Consider a test of the divide operation, taking three arguments: the numerator, the denominator and the expected result. +We can specify the test and its data using one of the forms of **TestCaseSourceAttribute**: ### Form 1 - `[TestCaseSource(string sourceName)]` > [!NOTE] -> We use [the `nameof` operator](https://docs.microsoft.com/dotnet/csharp/language-reference/operators/nameof) to avoid introducing [magic strings](https://wikipedia.org/wiki/Magic_string) into code, which offers better resilience when refactoring. While `nameof` is recommended, you could also use the string "DivideCases" to achieve the same outcome. +> We use [the `nameof` operator](https://docs.microsoft.com/dotnet/csharp/language-reference/operators/nameof) +> to avoid introducing [magic strings](https://wikipedia.org/wiki/Magic_string) into code, which offers better +> resilience when refactoring. While `nameof` is recommended, you could also use the string "DivideCases" to achieve the +> same outcome. [!code-csharp[BasicTestCaseSource](~/snippets/Snippets.NUnit/TestCaseSourceExamples.cs#BasicTestCaseSource)] -The single attribute argument in this form is a string representing the name of the source used -to provide test cases. It has the following characteristics: +The single attribute argument in this form is a string representing the name of the source used to provide test cases. +It has the following characteristics: * It may be a field, property or method in the test class. * It **must** be static. This is a change from NUnit 2.x. -* It must return an `IEnumerable` or a type that implements `IEnumerable`. For fields an array is generally used. For properties and methods, you may return an array or implement your own iterator. -* The individual items returned by the enumerator must be compatible - with the signature of the method on which the attribute appears. - See the **Test Case Construction** section below for details. +* It must return an `IEnumerable` or a type that implements `IEnumerable`. For fields an array is generally used. For + properties and methods, you may return an array or implement your own iterator. +* The individual items returned by the enumerator must be compatible with the signature of the method on which the + attribute appears. See the **Test Case Construction** section below for details. -Sometimes we would like to parameterize the source, e.g. if we use the same source for multiple tests, to this end it is possible to pass parameters to the source, if the source is a method. The parameters are specified as an array of parameters that are passed to the source method. +Sometimes we would like to parameterize the source, e.g. if we use the same source for multiple tests, to this end it is +possible to pass parameters to the source, if the source is a method. The parameters are specified as an array of +parameters that are passed to the source method. [!code-csharp[ParameterizedSource](~/snippets/Snippets.NUnit/TestCaseSourceExamples.cs#ParameterizedSource)] @@ -40,18 +44,17 @@ Sometimes we would like to parameterize the source, e.g. if we use the same sour [!code-csharp[ClassMethodAsTestCaseSource](~/snippets/Snippets.NUnit/TestCaseSourceExamples.cs#ClassMethodAsTestCaseSource)] -The first argument of the attribute in this form is a Type representing the class that will provide -the test cases. +The first argument of the attribute in this form is a Type representing the class that will provide the test cases. -The second argument is a string representing the name of the source used -to provide test cases. It has the following characteristics: +The second argument is a string representing the name of the source used to provide test cases. It has the following +characteristics: * It may be a field, property or method in the test class. * It **must** be static. This is a change from NUnit 2.x. -* It must return an `IEnumerable` or a type that implements `IEnumerable`. For fields an array is generally used. For properties and methods, you may return an array or implement your own iterator. -* The individual items returned by the enumerator must be compatible - with the signature of the method on which the attribute appears. - See the **Test Case Construction** section below for details. +* It must return an `IEnumerable` or a type that implements `IEnumerable`. For fields an array is generally used. For + properties and methods, you may return an array or implement your own iterator. +* The individual items returned by the enumerator must be compatible with the signature of the method on which the + attribute appears. See the **Test Case Construction** section below for details. Similar to Form 1 it is possible to pass parameters to the source, if the source is a method. @@ -59,16 +62,17 @@ Similar to Form 1 it is possible to pass parameters to the source, if the source [!code-csharp[ClassWithoutMethodAsTestCaseSource](~/snippets/Snippets.NUnit/TestCaseSourceExamples.cs#ClassWithoutMethodAsTestCaseSource)] -The Type argument in this form represents the class that provides test cases. -It must have a default constructor and implement `IEnumerable`. The enumerator -should return test case data compatible with the signature of the test on which the attribute appears. -See the **Test Case Construction** section below for details. +The Type argument in this form represents the class that provides test cases. It must have a default constructor and +implement `IEnumerable`. The enumerator should return test case data compatible with the signature of the test on which +the attribute appears. See the **Test Case Construction** section below for details. Note that it is not possible to pass parameters to the source, even if the source is a method. ## Sources with expected result using TestCaseData -As of NUnit 3.12, it is possible to use a typed source with an expected result. This is done by using the `TestCaseSource` attribute on a method that returns a `TestCaseData` object. The `TestCaseData` object can be constructed with the expected result as a parameter. +As of NUnit 3.12, it is possible to use a typed source with an expected result. This is done by using the +`TestCaseSource` attribute on a method that returns a `TestCaseData` object. The `TestCaseData` object can be +constructed with the expected result as a parameter. [!code-csharp[TypedSourceWithExpectedResult](~/snippets/Snippets.NUnit/TestCaseDataExample.cs#TestCaseDataExample)] @@ -76,15 +80,18 @@ See [TestCaseData](xref:testcasedata) for more information on the `TestCaseData` ## Examples using TestCaseSource with Typed data and expected results -It may seem from the examples above that TestCaseSource can only be used with simple data types or the base Object type. This is not the case. -TestCaseSource can be used with typed data and also including expected results, also without using TestCaseData. +It may seem from the examples above that TestCaseSource can only be used with simple data types or the base Object type. +This is not the case. TestCaseSource can be used with typed data and also including expected results, also without using +TestCaseData. -In the example below the test method takes a single argument of a an anonymous tuple type with `Person` and an expected value of type `bool`. It can of course be any type, if that makes sense for the test. -The TestCaseSource method returns an `IEnumerable<>` of the anonymous tuple type. +In the example below the test method takes a single argument of a an anonymous tuple type with `Person` and an expected +value of type `bool`. It can of course be any type, if that makes sense for the test. The TestCaseSource method returns +an `IEnumerable<>` of the anonymous tuple type. [!code-csharp[TypedValuesWithExpectedAsAnonymousTuple](~/snippets/Snippets.NUnit/TestCaseSourceExamples.cs#TypedValuesWithExpectedAsAnonymousTuple)] -It is also possible to use a generic wrapper (or any custom wrapper) for the testcase data and the expected result, as shown in the example below. +It is also possible to use a generic wrapper (or any custom wrapper) for the testcase data and the expected result, as +shown in the example below. [!code-csharp[TypedValuesWithExpectedInWrapperClass](~/snippets/Snippets.NUnit/TestCaseSourceExamples.cs#TypedValuesWithExpectedInWrapperClass)] @@ -96,56 +103,46 @@ TestCaseSourceAttribute supports one named parameter: ## Test Case Construction -In constructing tests, NUnit uses each item returned by -the enumerator as follows: +In constructing tests, NUnit uses each item returned by the enumerator as follows: -* If it is an object derived from the `TestCaseParameters` class, - its properties are used to provide the test case. NUnit provides - the [TestCaseData](xref:testcasedata) type for this purpose. -* If the test has a single argument and the returned value matches the type of - that argument it is used directly. This can eliminate a bit of extra typing by the programmer, - as in this example: +* If it is an object derived from the `TestCaseParameters` class, its properties are used to provide the test case. + NUnit provides the [TestCaseData](xref:testcasedata) type for this purpose. +* If the test has a single argument and the returned value matches the type of that argument it is used directly. This + can eliminate a bit of extra typing by the programmer, as in this example: [!code-csharp[SingleArgumentMatchingValueShorthand](~/snippets/Snippets.NUnit/TestCaseSourceExamples.cs#SingleArgumentMatchingValueShorthand)] -* If it is an `object[]`, its members are used to provide - the arguments for the method. This is the approach taken in +* If it is an `object[]`, its members are used to provide the arguments for the method. This is the approach taken in the three first examples above. -* If it is an array of some other type, NUnit can use it provided - that the arguments to the method are all of that type. For example, - the above examples could be modified to make the three nested arrays - of type `int[]`. -* If anything else is returned, it is used directly as the sole - argument to the method. Because every returned value is used, - NUnit is able to give an error message in cases where the method - requires a different number of arguments or - an argument of a different type. +* If it is an array of some other type, NUnit can use it provided that the arguments to the method are all of that type. + For example, the above examples could be modified to make the three nested arrays of type `int[]`. +* If anything else is returned, it is used directly as the sole argument to the method. Because every returned value is + used, NUnit is able to give an error message in cases where the method requires a different number of arguments or an + argument of a different type. ## Notes -1. It is recommended that the SourceType not be the same as the test fixture class. It may be a nested class, however, and probably should be if the data is only used within that fixture. -2. A generic `IEnumerable` and `IEnumerator` may be used but NUnit will actually deal with the underlying `IEnumerator` in the current release. -3. The GetEnumerator method may use yield statements or simply return the enumerator for an array or other collection held by the class. +1. It is recommended that the SourceType not be the same as the test fixture class. It may be a nested class, however, + and probably should be if the data is only used within that fixture. +2. A generic `IEnumerable` and `IEnumerator` may be used but NUnit will actually deal with the underlying `IEnumerator` + in the current release. +3. The GetEnumerator method may use yield statements or simply return the enumerator for an array or other collection + held by the class. ### Order of Execution -Individual test cases are executed in the order in which NUnit discovers them. This order does **not** -follow the lexical order of the attributes and will often vary between different -compilers or different versions of the CLR. +Individual test cases are executed in the order in which NUnit discovers them. This order does **not** follow the +lexical order of the attributes and will often vary between different compilers or different versions of the CLR. -As a result, when **TestCaseSourceAttribute** appears multiple times on a -method or when other data-providing attributes are used in combination with -**TestCaseSourceAttribute**, the order of the test cases is undefined. +As a result, when **TestCaseSourceAttribute** appears multiple times on a method or when other data-providing attributes +are used in combination with **TestCaseSourceAttribute**, the order of the test cases is undefined. -However, when a single **TestCaseSourceAttribute** is used by itself, -the order of the tests follows exactly the order in which the test cases -are returned from the source. +However, when a single **TestCaseSourceAttribute** is used by itself, the order of the tests follows exactly the order +in which the test cases are returned from the source. ### Object Construction -NUnit locates the test cases at the time the tests are loaded. It creates -instances of each class used with the third form of the attribute and builds a list of -tests to be executed. Each data source class is only created once at this -time and is destroyed after all tests are loaded. By design, no communication is -possible between the load and execution phases except through the tests that -are created. +NUnit locates the test cases at the time the tests are loaded. It creates instances of each class used with the third +form of the attribute and builds a list of tests to be executed. Each data source class is only created once at this +time and is destroyed after all tests are loaded. By design, no communication is possible between the load and execution +phases except through the tests that are created. diff --git a/docs/articles/nunit/writing-tests/attributes/testfixture.md b/docs/articles/nunit/writing-tests/attributes/testfixture.md index fabd2147b..ba5ea34ed 100644 --- a/docs/articles/nunit/writing-tests/attributes/testfixture.md +++ b/docs/articles/nunit/writing-tests/attributes/testfixture.md @@ -6,26 +6,24 @@ uid: testfixtureattribute This is the attribute that marks a class that contains tests and, optionally, setup or teardown methods. -Most restrictions on a class that is used as a test fixture have now been -eliminated. A test fixture class: +Most restrictions on a class that is used as a test fixture have now been eliminated. A test fixture class: * May be public, protected, private or internal. * May be a static class. * May be generic, so long as any type parameters are provided or can be inferred from the actual arguments. -* May not be abstract - although the attribute may be applied to an abstract class intended to serve as a base class for test fixtures. +* May not be abstract - although the attribute may be applied to an abstract class intended to serve as a base class for + test fixtures. * If no arguments are provided with the TestFixtureAttribute, the class must have a default constructor. * If arguments are provided, they must match one of the constructors. -If any of these restrictions are violated, the class is not runnable -as a test and will display as an error. +If any of these restrictions are violated, the class is not runnable as a test and will display as an error. -It is advisable that the constructor not have any side effects, -since NUnit may construct the object multiple times in the course of a session. +It is advisable that the constructor not have any side effects, since NUnit may construct the object multiple times in +the course of a session. -Beginning with NUnit 2.5, the **TestFixture** attribute is optional -for non-parameterized, non-generic fixtures. So long as the class contains -at least one method marked with the **Test**, **TestCase** or -**TestCaseSource** attribute, it will be treated as a test fixture. +Beginning with NUnit 2.5, the **TestFixture** attribute is optional for non-parameterized, non-generic fixtures. So long +as the class contains at least one method marked with the **Test**, **TestCase** or **TestCaseSource** attribute, it +will be treated as a test fixture. ## Example @@ -45,25 +43,20 @@ namespace NUnit.Tests ## Inheritance -The **TestFixtureAttribute** may be applied to a base class and is -inherited by any derived classes. This includes any abstract base class, -so the well-known Abstract Fixture pattern may be implemented if desired. +The **TestFixtureAttribute** may be applied to a base class and is inherited by any derived classes. This includes any +abstract base class, so the well-known Abstract Fixture pattern may be implemented if desired. -In order to facilitate use of generic and/or parameterized classes, -where the derived class may require a different number of arguments (or -type arguments) from the base class, superfluous **TestFixture** -attributes are ignored, using the following rules: +In order to facilitate use of generic and/or parameterized classes, where the derived class may require a different +number of arguments (or type arguments) from the base class, superfluous **TestFixture** attributes are ignored, using +the following rules: -1. If all TestFixture attributes provide constructor or type arguments, - then all of them are used. -2. If some of the attributes provide arguments and others do not, then - only those with arguments are used and those without arguments are ignored. -3. If none of the attributes provide arguments, one of them is selected - for use by NUnit. It is not possible to predict which will be used, so - this situation should generally be avoided. +1. If all TestFixture attributes provide constructor or type arguments, then all of them are used. +2. If some of the attributes provide arguments and others do not, then only those with arguments are used and those + without arguments are ignored. +3. If none of the attributes provide arguments, one of them is selected for use by NUnit. It is not possible to predict + which will be used, so this situation should generally be avoided. -This permits code like the following, which would cause an error if the -attribute on the base class were not ignored. +This permits code like the following, which would cause an error if the attribute on the base class were not ignored. ```csharp [TestFixture] @@ -81,66 +74,53 @@ public class DerivedFixture : AbstractFixtureBase ## Parameterized Test Fixtures -Test fixtures may take constructor arguments. -Argument values are specified as arguments to the **TestFixture** -attribute. NUnit will construct a separate instance of the fixture -for each set of arguments. +Test fixtures may take constructor arguments. Argument values are specified as arguments to the **TestFixture** +attribute. NUnit will construct a separate instance of the fixture for each set of arguments. -Individual fixture instances in a set of parameterized fixtures may be ignored. -Set the **Ignore** named parameter of the reason for ignoring the instance. +Individual fixture instances in a set of parameterized fixtures may be ignored. Set the **Ignore** named parameter of +the reason for ignoring the instance. -Individual fixture instances may be given categories as well. Set the **Category** -named parameter of the attribute to the name of the category or to a comma-separated -list of categories. +Individual fixture instances may be given categories as well. Set the **Category** named parameter of the attribute to +the name of the category or to a comma-separated list of categories. ### Example -The following test fixture would be instantiated by NUnit three times, -passing in each set of arguments to the appropriate constructor. Note -that there are three different constructors, matching the data types -provided as arguments. +The following test fixture would be instantiated by NUnit three times, passing in each set of arguments to the +appropriate constructor. Note that there are three different constructors, matching the data types provided as +arguments. [!code-csharp[MultipleParameterizedTestFixtures](~/snippets/Snippets.NUnit/Attributes/TestFixtureAttributeExamples.cs#MultipleParameterizedTestFixtures)] ## Generic Test Fixtures -You may also use a generic class as a test fixture. -In order for NUnit to instantiate the fixture, you must either specify the -types to be used as arguments to **TestFixtureAttribute** or use the -named parameter **TypeArgs=** to specify them. NUnit will construct a -separate instance of the fixture for each **TestFixtureAttribute** -you provide. +You may also use a generic class as a test fixture. In order for NUnit to instantiate the fixture, you must either +specify the types to be used as arguments to **TestFixtureAttribute** or use the named parameter **TypeArgs=** to +specify them. NUnit will construct a separate instance of the fixture for each **TestFixtureAttribute** you provide. ### Example -The following test fixture would be instantiated by NUnit twice, -once using an `ArrayList` and once using a `List`. +The following test fixture would be instantiated by NUnit twice, once using an `ArrayList` and once using a `List`. [!code-csharp[GenericTestFixtures](~/snippets/Snippets.NUnit/Attributes/TestFixtureAttributeExamples.cs#GenericTestFixtures)] ### Generic Test Fixtures with Parameters -If a Generic fixture, uses constructor arguments, there are three -approaches to telling NUnit which arguments are type parameters -and which are normal constructor parameters. +If a Generic fixture, uses constructor arguments, there are three approaches to telling NUnit which arguments are type +parameters and which are normal constructor parameters. -* Specify both sets of parameters as arguments to the **TestFixtureAttribute**. - Leading **System.Type** arguments are used as type parameters, while - any remaining arguments are used to construct the instance. In the - following example, this leads to some obvious duplication... +* Specify both sets of parameters as arguments to the **TestFixtureAttribute**. Leading **System.Type** arguments are + used as type parameters, while any remaining arguments are used to construct the instance. In the following example, + this leads to some obvious duplication... [!code-csharp[GenericTestFixtureWithParameters](~/snippets/Snippets.NUnit/Attributes/TestFixtureAttributeExamples.cs#GenericTestFixtureWithParameters)] -* Specify normal parameters as arguments to **TestFixtureAttribute** - and use the named parameter **TypeArgs=** to specify the type - arguments. Again, for this example, the type info is duplicated, but - it is at least more cleanly separated from the normal arguments... +* Specify normal parameters as arguments to **TestFixtureAttribute** and use the named parameter **TypeArgs=** to + specify the type arguments. Again, for this example, the type info is duplicated, but it is at least more cleanly + separated from the normal arguments... [!code-csharp[SpecifyTypeArgsSeparately](~/snippets/Snippets.NUnit/Attributes/TestFixtureAttributeExamples.cs#SpecifyTypeArgsSeparately)] -* In some cases, when the constructor makes use of all the type parameters - NUnit may simply be able to deduce them from the arguments provided. - That's the case here and the following is the preferred way to - write this example... +* In some cases, when the constructor makes use of all the type parameters NUnit may simply be able to deduce them from + the arguments provided. That's the case here and the following is the preferred way to write this example... [!code-csharp[DeducedTypesFromArguments](~/snippets/Snippets.NUnit/Attributes/TestFixtureAttributeExamples.cs#DeducedTypesFromArguments)] diff --git a/docs/articles/nunit/writing-tests/attributes/testfixturesource.md b/docs/articles/nunit/writing-tests/attributes/testfixturesource.md index 8d5f5db7f..162ed74a5 100644 --- a/docs/articles/nunit/writing-tests/attributes/testfixturesource.md +++ b/docs/articles/nunit/writing-tests/attributes/testfixturesource.md @@ -1,14 +1,13 @@ # TestFixtureSource -`TestFixtureSourceAttribute` is used on a parameterized fixture to -identify the source from which the required constructor arguments will be provided. -The data is kept separate from the fixture itself and may be used by multiple -fixtures. See [Parameterized Tests](xref:parameterizedtests) for a general introduction to -tests with arguments. +`TestFixtureSourceAttribute` is used on a parameterized fixture to identify the source from which the required +constructor arguments will be provided. The data is kept separate from the fixture itself and may be used by multiple +fixtures. See [Parameterized Tests](xref:parameterizedtests) for a general introduction to tests with arguments. ## Usage -Consider a test fixture class taking two parameters in its constructor, a string and an int. We can specify the test and its data using one of the forms of **TestFixtureSourceAttribute**: +Consider a test fixture class taking two parameters in its constructor, a string and an int. We can specify the test and +its data using one of the forms of **TestFixtureSourceAttribute**: ### Form 1 - [TestFixtureSource(string sourceName)] @@ -27,13 +26,15 @@ public class MyTestClass } ``` -The single attribute argument in this form is a string representing the name of the source used -to provide arguments for constructing the `TestFixture`. It has the following characteristics: +The single attribute argument in this form is a string representing the name of the source used to provide arguments for +constructing the `TestFixture`. It has the following characteristics: * It may be a field, property or method in the test class. * It **must** be static. -* It must return an `IEnumerable` or a type that implements `IEnumerable`. For fields an array is generally used. For properties and methods, you may return an array or implement your own iterator. -* The individual items returned by the enumerator must either be object arrays or derive from the `TestFixtureParameters` class. Arguments must be consistent with the fixture constructor. +* It must return an `IEnumerable` or a type that implements `IEnumerable`. For fields an array is generally used. For + properties and methods, you may return an array or implement your own iterator. +* The individual items returned by the enumerator must either be object arrays or derive from the + `TestFixtureParameters` class. Arguments must be consistent with the fixture constructor. ### Form 2 - [TestFixtureSource(Type sourceType, string sourceName)] @@ -55,16 +56,18 @@ class AnotherClass } ``` -The first argument of the attribute in this form is a Type representing the class that will provide -the test fixture data. +The first argument of the attribute in this form is a Type representing the class that will provide the test fixture +data. -The second argument is a string representing the name of the source used -to provide test fixtures. It has the following characteristics: +The second argument is a string representing the name of the source used to provide test fixtures. It has the following +characteristics: * It may be a field, property or method in the test class. * It **must** be static. -* It must return an `IEnumerable` or a type that implements `IEnumerable`. For fields an array is generally used. For properties and methods, you may return an array or implement your own iterator. -* The individual items returned by the enumerator must either be object arrays or derive from the `TestFixtureParameters` class. Arguments must be consistent with the fixture constructor. +* It must return an `IEnumerable` or a type that implements `IEnumerable`. For fields an array is generally used. For + properties and methods, you may return an array or implement your own iterator. +* The individual items returned by the enumerator must either be object arrays or derive from the + `TestFixtureParameters` class. Arguments must be consistent with the fixture constructor. ### Form 3 - [TestFixtureSource(Type sourceType)] @@ -87,10 +90,11 @@ class FixtureArgs: IEnumerable } ``` -The Type argument in this form represents the class that provides test cases. -It must have a default constructor and implement `IEnumerable`. +The Type argument in this form represents the class that provides test cases. It must have a default constructor and +implement `IEnumerable`. -The individual items returned by the enumerator must either be object arrays or derive from the `TestFixtureParameters` class. Arguments must be consistent with the fixture constructor. +The individual items returned by the enumerator must either be object arrays or derive from the `TestFixtureParameters` +class. Arguments must be consistent with the fixture constructor. ## Named Parameters @@ -100,14 +104,18 @@ The individual items returned by the enumerator must either be object arrays or ## Test Case Construction -In constructing tests, NUnit uses each item returned by -the enumerator as follows: +In constructing tests, NUnit uses each item returned by the enumerator as follows: -* If it is an object deriving from `TestFixtureParameters`, its properties are used to provide the test case. NUnit provides the [TestFixtureData](xref:testfixturedata) class for this purpose. -* If it is an `object[]`, its members are used to provide the arguments for the method. This is the approach taken in the examples above. +* If it is an object deriving from `TestFixtureParameters`, its properties are used to provide the test case. NUnit + provides the [TestFixtureData](xref:testfixturedata) class for this purpose. +* If it is an `object[]`, its members are used to provide the arguments for the method. This is the approach taken in + the examples above. ## Notes -1. It is recommended that the SourceType not be the same as the test fixture class. It may be a nested class, however, and probably should be if the data is only used within that fixture. -2. A generic `IEnumerable` and `IEnumerator` may be used but NUnit will actually deal with the underlying `IEnumerator` in the current release. -3. The GetEnumerator method may use yield statements or simply return the enumerator for an array or other collection held by the class. +1. It is recommended that the SourceType not be the same as the test fixture class. It may be a nested class, however, + and probably should be if the data is only used within that fixture. +2. A generic `IEnumerable` and `IEnumerator` may be used but NUnit will actually deal with the underlying `IEnumerator` + in the current release. +3. The GetEnumerator method may use yield statements or simply return the enumerator for an array or other collection + held by the class. diff --git a/docs/articles/nunit/writing-tests/attributes/theory.md b/docs/articles/nunit/writing-tests/attributes/theory.md index 007487e84..09028b323 100644 --- a/docs/articles/nunit/writing-tests/attributes/theory.md +++ b/docs/articles/nunit/writing-tests/attributes/theory.md @@ -4,77 +4,63 @@ uid: theoryattribute # Theory -A Theory is a special type of test, used to verify a general -statement about the system under development. Normal tests are -_example-based_. That is, the developer supplies one or -more examples of inputs and expected outputs either within the -code of the test or - in the case of [Parameterized Tests](xref:parameterizedtests) - -as arguments to the test method. A theory, on the other hand, -makes a general statement that all of its assertions will pass -for all arguments satisfying certain assumptions. - -Theories are implemented in NUnit as non-generic -methods within a **TestFixture**, which are annotated -with the **TheoryAttribute**. Theory methods must always have arguments and therefore appears quite similar to [Parameterized Tests](xref:parameterizedtests) -at first glance. However, a Theory incorporates additional data sources for its arguments and allows special processing for assumptions -about that data. The key difference, though, is that theories +A Theory is a special type of test, used to verify a general statement about the system under development. Normal tests +are _example-based_. That is, the developer supplies one or more examples of inputs and expected outputs either within +the code of the test or - in the case of [Parameterized Tests](xref:parameterizedtests) - as arguments to the test +method. A theory, on the other hand, makes a general statement that all of its assertions will pass for all arguments +satisfying certain assumptions. + +Theories are implemented in NUnit as non-generic methods within a **TestFixture**, which are annotated with the +**TheoryAttribute**. Theory methods must always have arguments and therefore appears quite similar to [Parameterized +Tests](xref:parameterizedtests) at first glance. However, a Theory incorporates additional data sources for its +arguments and allows special processing for assumptions about that data. The key difference, though, is that theories make general statements and are more than just a set of examples. ## Data for Theories -The primary source of data for a **Theory** is the -[Datapoint Attribute](datapoint.md) or [DatapointSource Attribute](datapointsource.md). -NUnit will use any class members of the required types, which are annotated -with one of these attributes, to provide data for each parameter -of the Theory. NUnit assembles the values for individual arguments +The primary source of data for a **Theory** is the [Datapoint Attribute](datapoint.md) or [DatapointSource +Attribute](datapointsource.md). NUnit will use any class members of the required types, which are annotated with one of +these attributes, to provide data for each parameter of the Theory. NUnit assembles the values for individual arguments combinatorially to provide test cases for the theory. -In addition to the Datapoint and Datapoints attributes, it -is possible to use any of the approaches for supplying data -that are recognized on normal parameterized tests. We suggest -that this capability not be overused, since it runs counter -to the distinction between a test based on examples and a -theory. However, it may be useful in order to guarantee that -a specific test case is included. +In addition to the Datapoint and Datapoints attributes, it is possible to use any of the approaches for supplying data +that are recognized on normal parameterized tests. We suggest that this capability not be overused, since it runs +counter to the distinction between a test based on examples and a theory. However, it may be useful in order to +guarantee that a specific test case is included. -For **boolean** and **enum** arguments, NUnit can supply the -data without any action by the user. All possible values are supplied -to the argument. This feature is disabled if the user supplies any -values for the argument. +For **boolean** and **enum** arguments, NUnit can supply the data without any action by the user. All possible values +are supplied to the argument. This feature is disabled if the user supplies any values for the argument. > [!NOTE] -> Because NUnit searches for datapoints based on the type of the argument, generic methods may not currently be used as theories. This limitation may be removed in a future release. See below for a workaround using a generic fixture. +> Because NUnit searches for datapoints based on the type of the argument, generic methods may not currently be +> used as theories. This limitation may be removed in a future release. See below for a workaround using a generic +> fixture. ## Assumptions -The theory itself is responsible for ensuring that all data supplied -meets its assumptions. It does this by use of the -**Assume.That(...)** construct, which works just like -**Assert.That(...)** but does not cause a failure. If -the assumption is not satisfied for a particular test case, that case -returns an Inconclusive result, rather than a Success or Failure. +The theory itself is responsible for ensuring that all data supplied meets its assumptions. It does this by use of the +**Assume.That(...)** construct, which works just like **Assert.That(...)** but does not cause a failure. If the +assumption is not satisfied for a particular test case, that case returns an Inconclusive result, rather than a Success +or Failure. -The overall result of executing a Theory over a set of test cases is -determined as follows: +The overall result of executing a Theory over a set of test cases is determined as follows: * If the assumptions are violated for **all** test cases, then the Theory itself is marked as a failure. * If any Assertion fails, the Theory itself fails. -* If at least **some** cases pass the stated assumptions, and there are **no** assertion failures or exceptions, then the Theory passes. +* If at least **some** cases pass the stated assumptions, and there are **no** assertion failures or exceptions, then + the Theory passes. -Since the user does not generally care about inconclusive cases under -a theory, they are not normally displayed in the Gui. For situations -where they are needed - such as debugging - the context menu for the -theory provides an option to display them. +Since the user does not generally care about inconclusive cases under a theory, they are not normally displayed in the +Gui. For situations where they are needed - such as debugging - the context menu for the theory provides an option to +display them. ## Example -In the following example, the Theory SquareRootDefinition -verifies that the implementation of square root satisfies -the following definition: +In the following example, the Theory SquareRootDefinition verifies that the implementation of square root satisfies the +following definition: -> Given a non-negative number, the square root of that number -> is always non-negative and, when multiplied by itself, gives -> the original number. +> Given a non-negative number, the square root of that number is always non-negative and, when multiplied by itself, +> gives the original number. ```csharp public class SqrtTests @@ -97,10 +83,9 @@ public class SqrtTests ## Theories in Generic Fixtures -In a generic fixture with Type parameter `T` individual methods using `T` as -a parameter type or not generic, since `T` has been resolved to an actual -Type in instantiating the fixture instance. You may use such methods as -theories and any data of the appropriate type will be used. +In a generic fixture with Type parameter `T` individual methods using `T` as a parameter type or not generic, since `T` +has been resolved to an actual Type in instantiating the fixture instance. You may use such methods as theories and any +data of the appropriate type will be used. ```csharp [TestFixture(typeof(int))] diff --git a/docs/articles/nunit/writing-tests/attributes/timeout.md b/docs/articles/nunit/writing-tests/attributes/timeout.md index 1aa3bc282..6df9d6ee9 100644 --- a/docs/articles/nunit/writing-tests/attributes/timeout.md +++ b/docs/articles/nunit/writing-tests/attributes/timeout.md @@ -3,16 +3,21 @@ > [!NOTE] > From version 3.12 this is also available in the .NET Standard 2.0 builds of the framework. -Normally, NUnit simply runs tests and waits for them to terminate -- the test is allowed to run indefinitely. For certain kinds of tests, however, it may be desirable to specify a timeout value. +Normally, NUnit simply runs tests and waits for them to terminate -- the test is allowed to run indefinitely. For +certain kinds of tests, however, it may be desirable to specify a timeout value. -The **TimeoutAttribute** is used to specify a timeout value in milliseconds -for a test case. If the test case runs longer than the time specified it -is immediately cancelled and reported as a failure, with a message indicating that the timeout was exceeded. +The **TimeoutAttribute** is used to specify a timeout value in milliseconds for a test case. If the test case runs +longer than the time specified it is immediately cancelled and reported as a failure, with a message indicating that the +timeout was exceeded. -The specified timeout value covers the test setup and teardown as well as the test method itself. Before and after actions may also be included, depending on where they were specified. Since the timeout may occur during any of these execution phases, no guarantees can be made as to what will be run and any of these phases of execution may be incomplete. If only used on a test, once a test has timed out, its teardown methods are executed. +The specified timeout value covers the test setup and teardown as well as the test method itself. Before and after +actions may also be included, depending on where they were specified. Since the timeout may occur during any of these +execution phases, no guarantees can be made as to what will be run and any of these phases of execution may be +incomplete. If only used on a test, once a test has timed out, its teardown methods are executed. -The attribute may also be specified on a fixture or assembly, in which -case it indicates the default timeout for any subordinate test cases. When using the console runner, it is also possible to specify a default timeout on the command-line. +The attribute may also be specified on a fixture or assembly, in which case it indicates the default timeout for any +subordinate test cases. When using the console runner, it is also possible to specify a default timeout on the +command-line. ## Example diff --git a/docs/articles/nunit/writing-tests/attributes/valuesource.md b/docs/articles/nunit/writing-tests/attributes/valuesource.md index c9ece2ce4..a457e2305 100644 --- a/docs/articles/nunit/writing-tests/attributes/valuesource.md +++ b/docs/articles/nunit/writing-tests/attributes/valuesource.md @@ -4,52 +4,45 @@ uid: valuesource # ValueSource -**ValueSourceAttribute** is used on individual parameters of a test method to -identify a named source for the argument values to be supplied. The attribute has two public constructors. +**ValueSourceAttribute** is used on individual parameters of a test method to identify a named source for the argument +values to be supplied. The attribute has two public constructors. ```csharp ValueSourceAttribute(Type sourceType, string sourceName); ValueSourceAttribute(string sourceName); ``` -If **sourceType** is specified, it represents the class that provides -the data. +If **sourceType** is specified, it represents the class that provides the data. -If **sourceType** is not specified, the class containing the test -method is used. +If **sourceType** is not specified, the class containing the test method is used. -The **sourceName**, represents the name of the source that will provide the arguments. It should have the following characteristics: +The **sourceName**, represents the name of the source that will provide the arguments. It should have the following +characteristics: * It may be a field, a non-indexed property or a method taking no arguments. * It must be a static member. * It must return an IEnumerable or a type that implements IEnumerable. -* The individual items returned from the enumerator must be compatible with the type of the parameter on which the attribute appears. +* The individual items returned from the enumerator must be compatible with the type of the parameter on which the + attribute appears. ## Order of Execution -Individual test cases are executed in the order in which NUnit discovers them. -This order does **not** follow the lexical order of the attributes and will -often vary between different compilers or different versions of the CLR. +Individual test cases are executed in the order in which NUnit discovers them. This order does **not** follow the +lexical order of the attributes and will often vary between different compilers or different versions of the CLR. -As a result, when **ValueSourceAttribute** appears multiple times on a -parameter or when other data-providing attributes are used in combination with -**ValueSourceAttribute**, the order of the arguments is undefined. +As a result, when **ValueSourceAttribute** appears multiple times on a parameter or when other data-providing attributes +are used in combination with **ValueSourceAttribute**, the order of the arguments is undefined. -However, when a single **ValueSourceAttribute** is used by itself, -the order of the arguments follows exactly the order in which the data -is returned from the source. +However, when a single **ValueSourceAttribute** is used by itself, the order of the arguments follows exactly the order +in which the data is returned from the source. ## Note on Object Construction -NUnit locates the test cases at the time the tests are loaded, creates -instances of each class with non-static sources and builds a list of -tests to be executed. Each source object is only created once at this -time and is destroyed after all tests are loaded. - -If the data source is in the test fixture itself, the object is created -using the appropriate constructor for the fixture parameters provided on -the **TestFixtureAttribute**, or -the default constructor if no parameters were specified. Since this object -is destroyed before the tests are run, no communication is possible between -these two phases - or between different runs - except through the parameters -themselves. +NUnit locates the test cases at the time the tests are loaded, creates instances of each class with non-static sources +and builds a list of tests to be executed. Each source object is only created once at this time and is destroyed after +all tests are loaded. + +If the data source is in the test fixture itself, the object is created using the appropriate constructor for the +fixture parameters provided on the **TestFixtureAttribute**, or the default constructor if no parameters were specified. +Since this object is destroyed before the tests are run, no communication is possible between these two phases - or +between different runs - except through the parameters themselves. diff --git a/docs/articles/nunit/writing-tests/constraints/AllItemsConstraint.md b/docs/articles/nunit/writing-tests/constraints/AllItemsConstraint.md index a92741380..b58ab3e8b 100644 --- a/docs/articles/nunit/writing-tests/constraints/AllItemsConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/AllItemsConstraint.md @@ -1,6 +1,7 @@ # AllItems Constraint -`AllItemsConstraint` applies a constraint to each item in an `IEnumerable`, succeeding only if all of them succeed. An exception is thrown if the actual value passed does not implement `IEnumerable`. +`AllItemsConstraint` applies a constraint to each item in an `IEnumerable`, succeeding only if all of them succeed. An +exception is thrown if the actual value passed does not implement `IEnumerable`. ## Constructor diff --git a/docs/articles/nunit/writing-tests/constraints/AndConstraint.md b/docs/articles/nunit/writing-tests/constraints/AndConstraint.md index 62ae91b0b..49ff82492 100644 --- a/docs/articles/nunit/writing-tests/constraints/AndConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/AndConstraint.md @@ -22,7 +22,10 @@ Assert.That(2.3, Is.GreaterThan(2.0).And.LessThan(3.0)); ## Evaluation Order and Precedence -Note that the constraint evaluates the sub-constraints left to right, meaning that `Assert.That(i, Is.Not.Null.And.GreaterThan(9));` where `i` is a nullable `int` will work for `10`, but fail for `null` with the message `Expected: not null and greater than 9. But was: null`. `Assert.That(i, Is.GreaterThan(9).And.Not.Null);` will also succeed for `10`, but throw an exception for `null`, as `null` cannot be compared to `9`. +Note that the constraint evaluates the sub-constraints left to right, meaning that `Assert.That(i, +Is.Not.Null.And.GreaterThan(9));` where `i` is a nullable `int` will work for `10`, but fail for `null` with the message +`Expected: not null and greater than 9. But was: null`. `Assert.That(i, Is.GreaterThan(9).And.Not.Null);` will also +succeed for `10`, but throw an exception for `null`, as `null` cannot be compared to `9`. The **OrConstraint** has precedence over the **AndConstraint**. diff --git a/docs/articles/nunit/writing-tests/constraints/AnyOfConstraint.md b/docs/articles/nunit/writing-tests/constraints/AnyOfConstraint.md index 9dad641d0..e0369aa77 100644 --- a/docs/articles/nunit/writing-tests/constraints/AnyOfConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/AnyOfConstraint.md @@ -3,7 +3,8 @@ `AnyOfConstraint` is used to determine whether a value is equal to any of the expected values. > [!NOTE] -> Values provided must be as parameters to the method, not as e.g. a separate array. If you are instead looking to see if a collection contains a value, see the [CollectionContains Constraint](xref:collectioncontainsconstraint). +> Values provided must be as parameters to the method, not as e.g. a separate array. If you are instead looking +> to see if a collection contains a value, see the [CollectionContains Constraint](xref:collectioncontainsconstraint). ## Constructor diff --git a/docs/articles/nunit/writing-tests/constraints/BinarySerializableConstraint.md b/docs/articles/nunit/writing-tests/constraints/BinarySerializableConstraint.md index ada2dd52c..66825abb0 100644 --- a/docs/articles/nunit/writing-tests/constraints/BinarySerializableConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/BinarySerializableConstraint.md @@ -25,4 +25,8 @@ Assert.That(someObject, Is.BinarySerializable)); * [XmlSerializableConstraint](XmlSerializableConstraint.md) > [!WARNING] -> Binary Serialization is no longer supported in .NET 8 due to security concerns. From NUnit 4.x onward, this constraint is not available. More information can be found in these Microsoft Learn articles [on BinaryFormatter's removal](https://learn.microsoft.com/en-us/dotnet/core/compatibility/serialization/8.0/binaryformatter-disabled) and [on the BinaryFormatter security guide](https://learn.microsoft.com/en-au/dotnet/standard/serialization/binaryformatter-security-guide) +> Binary Serialization is no longer supported in .NET 8 due to security concerns. From NUnit 4.x onward, this +> constraint is not available. More information can be found in these Microsoft Learn articles [on BinaryFormatter's +> removal](https://learn.microsoft.com/en-us/dotnet/core/compatibility/serialization/8.0/binaryformatter-disabled) and +> [on the BinaryFormatter security +> guide](https://learn.microsoft.com/en-au/dotnet/standard/serialization/binaryformatter-security-guide) diff --git a/docs/articles/nunit/writing-tests/constraints/CollectionContainsConstraint.md b/docs/articles/nunit/writing-tests/constraints/CollectionContainsConstraint.md index f0cca00a2..ce898b0d6 100644 --- a/docs/articles/nunit/writing-tests/constraints/CollectionContainsConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/CollectionContainsConstraint.md @@ -4,7 +4,8 @@ uid: collectioncontainsconstraint # CollectionContains Constraint -`CollectionContainsConstraint` tests that an `IEnumerable` contains an object. If the actual value passed does not implement `IEnumerable`, an exception is thrown. +`CollectionContainsConstraint` tests that an `IEnumerable` contains an object. If the actual value passed does not +implement `IEnumerable`, an exception is thrown. ## Constructor @@ -42,4 +43,7 @@ Assert.That(iarray, Does.Contain(3)); ## Note -`Has.Member()`, `Contains.Item()` and `Does.Contain()` work the same as `Has.Some.EqualTo()`. The last statement generates a [SomeItemsConstraint](SomeItemsConstraint.md) based on an [EqualConstraint](EqualConstraint.md) and offers additional options such as ignoring case or specifying a tolerance. The syntax on this page may be viewed as a shortcut for specifying simpler cases. +`Has.Member()`, `Contains.Item()` and `Does.Contain()` work the same as `Has.Some.EqualTo()`. The last statement +generates a [SomeItemsConstraint](SomeItemsConstraint.md) based on an [EqualConstraint](EqualConstraint.md) and offers +additional options such as ignoring case or specifying a tolerance. The syntax on this page may be viewed as a shortcut +for specifying simpler cases. diff --git a/docs/articles/nunit/writing-tests/constraints/CollectionOrderedConstraint.md b/docs/articles/nunit/writing-tests/constraints/CollectionOrderedConstraint.md index 2793ed222..0fbf510a6 100644 --- a/docs/articles/nunit/writing-tests/constraints/CollectionOrderedConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/CollectionOrderedConstraint.md @@ -1,6 +1,7 @@ # CollectionOrdered Constraint -`CollectionOrderedConstraint` tests that an `IEnumerable` is ordered. If the actual value passed does not implement `IEnumerable`, an exception is thrown. +`CollectionOrderedConstraint` tests that an `IEnumerable` is ordered. If the actual value passed does not implement +`IEnumerable`, an exception is thrown. The constraint supports both simple and property-based ordering (Ordered.By). @@ -30,7 +31,8 @@ By default, the order is expected to be ascending. ## Property-Based Ordering -Property-based ordering uses one or more properties that are common to every item in the enumeration. It is used when one or more instances of the `By` modifier appears in the ordering expression. +Property-based ordering uses one or more properties that are common to every item in the enumeration. It is used when +one or more instances of the `By` modifier appears in the ordering expression. ```csharp string[] sarray = new string[] ("a", "aa", "aaa"); @@ -54,7 +56,8 @@ The following Modifiers are supported: ## Ordering on Multiple Properties -An ordering expression may use multiple `By` modifiers, each referring to a different property. The following examples assume a collection of items with properties named A and B. +An ordering expression may use multiple `By` modifiers, each referring to a different property. The following examples +assume a collection of items with properties named A and B. ```csharp Assert.That(collection, Is.Ordered.By("A").Then.By("B")); @@ -66,5 +69,7 @@ Assert.That(collection, Is.Ordered.Ascending.By("A").Descending.By("B")); // Ill ## Notes -1. The `Then` modifier divides the expression into ordering steps. Each step may optionally contain one `Ascending` or `Descending` modifier and one `Using` modifier. -2. If `Then` is not used, each new `By` modifier marks the beginning of a step. The last example statement is illegal because the first group contains both Ascending and Descending. Use of `Then` is recommended for clarity. +1. The `Then` modifier divides the expression into ordering steps. Each step may optionally contain one `Ascending` or + `Descending` modifier and one `Using` modifier. +2. If `Then` is not used, each new `By` modifier marks the beginning of a step. The last example statement is illegal + because the first group contains both Ascending and Descending. Use of `Then` is recommended for clarity. diff --git a/docs/articles/nunit/writing-tests/constraints/CollectionSubsetConstraint.md b/docs/articles/nunit/writing-tests/constraints/CollectionSubsetConstraint.md index 48d070890..c234e42d7 100644 --- a/docs/articles/nunit/writing-tests/constraints/CollectionSubsetConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/CollectionSubsetConstraint.md @@ -1,6 +1,7 @@ # CollectionSubset Constraint -`CollectionSubsetConstraint` tests that one `IEnumerable` is a subset of another. If the actual value passed does not implement `IEnumerable`, an exception is thrown. +`CollectionSubsetConstraint` tests that one `IEnumerable` is a subset of another. If the actual value passed does not +implement `IEnumerable`, an exception is thrown. ## Constructor diff --git a/docs/articles/nunit/writing-tests/constraints/CollectionSupersetConstraint.md b/docs/articles/nunit/writing-tests/constraints/CollectionSupersetConstraint.md index 3e5c7a586..97162adb5 100644 --- a/docs/articles/nunit/writing-tests/constraints/CollectionSupersetConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/CollectionSupersetConstraint.md @@ -1,6 +1,7 @@ # CollectionSuperset Constraint -`CollectionSupersetConstraint` tests that one `IEnumerable` is a superset of another. If the actual value passed does not implement `IEnumerable`, an exception is thrown. +`CollectionSupersetConstraint` tests that one `IEnumerable` is a superset of another. If the actual value passed does +not implement `IEnumerable`, an exception is thrown. ## Constructor diff --git a/docs/articles/nunit/writing-tests/constraints/EmptyCollectionConstraint.md b/docs/articles/nunit/writing-tests/constraints/EmptyCollectionConstraint.md index 64c10aff6..6814d7636 100644 --- a/docs/articles/nunit/writing-tests/constraints/EmptyCollectionConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/EmptyCollectionConstraint.md @@ -1,6 +1,7 @@ # EmptyCollection Constraint -The **EmptyCollectionConstraint** tests if a Collection or other `IEnumerable` is empty. An `ArgumentException` is thrown if the actual value is not an `IEnumerable` or is null. +The **EmptyCollectionConstraint** tests if a Collection or other `IEnumerable` is empty. An `ArgumentException` is +thrown if the actual value is not an `IEnumerable` or is null. ## Constructor @@ -22,4 +23,5 @@ Assert.That(new int[] { 1, 2, 3 }, Is.Not.Empty); ``` > [!NOTE] -> `Is.Empty` actually creates an `EmptyConstraint`. Subsequently applying it to an `IEnumerable` or `ICollection` causes an `EmptyCollectionConstraint` to be created. +> `Is.Empty` actually creates an `EmptyConstraint`. Subsequently applying it to an `IEnumerable` or +> `ICollection` causes an `EmptyCollectionConstraint` to be created. diff --git a/docs/articles/nunit/writing-tests/constraints/EmptyConstraint.md b/docs/articles/nunit/writing-tests/constraints/EmptyConstraint.md index 88a50fa23..82ea5c24f 100644 --- a/docs/articles/nunit/writing-tests/constraints/EmptyConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/EmptyConstraint.md @@ -25,7 +25,7 @@ Assert.That(new List(), Is.Empty); ## Notes * **EmptyConstraint** creates and uses either an [EmptyStringConstraint](EmptyStringConstraint.md), - [EmptyDirectoryConstraint](EmptyDirectoryConstraint.md) or [EmptyCollectionConstraint](EmptyCollectionConstraint.md) depending on the argument tested. -* A `DirectoryInfo` argument is required in order to test for an empty directory. - To test whether a string represents a directory path, you must first construct - a `DirectoryInfo`. + [EmptyDirectoryConstraint](EmptyDirectoryConstraint.md) or [EmptyCollectionConstraint](EmptyCollectionConstraint.md) + depending on the argument tested. +* A `DirectoryInfo` argument is required in order to test for an empty directory. To test whether a string represents a + directory path, you must first construct a `DirectoryInfo`. diff --git a/docs/articles/nunit/writing-tests/constraints/EmptyDirectoryConstraint.md b/docs/articles/nunit/writing-tests/constraints/EmptyDirectoryConstraint.md index 2aa17ce94..9df9b1828 100644 --- a/docs/articles/nunit/writing-tests/constraints/EmptyDirectoryConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/EmptyDirectoryConstraint.md @@ -22,4 +22,5 @@ Assert.That(new DirectoryInfo(actual), Is.Not.Empty); ``` > [!NOTE] -> `Is.Empty` actually creates an `EmptyConstraint`. Subsequently applying it to a `DirectoryInfo` causes an `EmptyDirectoryConstraint` to be created. +> `Is.Empty` actually creates an `EmptyConstraint`. Subsequently applying it to a `DirectoryInfo` causes an +> `EmptyDirectoryConstraint` to be created. diff --git a/docs/articles/nunit/writing-tests/constraints/EmptyStringConstraint.md b/docs/articles/nunit/writing-tests/constraints/EmptyStringConstraint.md index 25ce96c80..8fc5bc39d 100644 --- a/docs/articles/nunit/writing-tests/constraints/EmptyStringConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/EmptyStringConstraint.md @@ -22,4 +22,5 @@ Assert.That("A String", Is.Not.Empty); ``` > [!NOTE] -> `Is.Empty` actually creates an `EmptyConstraint`. Subsequently applying it to a `string` causes an `EmptyStringConstraint` to be created. +> `Is.Empty` actually creates an `EmptyConstraint`. Subsequently applying it to a `string` causes an +> `EmptyStringConstraint` to be created. diff --git a/docs/articles/nunit/writing-tests/constraints/EqualConstraint.md b/docs/articles/nunit/writing-tests/constraints/EqualConstraint.md index 276b2ce65..5e2f22200 100644 --- a/docs/articles/nunit/writing-tests/constraints/EqualConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/EqualConstraint.md @@ -4,8 +4,7 @@ uid: equalconstraint # Equal Constraint -An EqualConstraint is used to test whether an actual value -is equal to the expected value supplied in its constructor, +An EqualConstraint is used to test whether an actual value is equal to the expected value supplied in its constructor, optionally within a specified tolerance. ## Constructor @@ -46,11 +45,9 @@ Is.Zero // Equivalent to Is.EqualTo(0) ## Comparing Numerics -Numerics are compared based on their values. Different types -may be compared successfully if their values are equal. +Numerics are compared based on their values. Different types may be compared successfully if their values are equal. -Using the **Within** modifier, numerics may be tested -for equality within a fixed or percent tolerance. +Using the **Within** modifier, numerics may be tested for equality within a fixed or percent tolerance. ```csharp Assert.That(2 + 2, Is.EqualTo(4.0)); @@ -64,15 +61,12 @@ Assert.That(5.5, Is.EqualTo(5).Within(1.5).Percent); ## Comparing Floating Point Values -Values of type float and double are normally compared using a tolerance -specified by the **Within** modifier. The special values PositiveInfinity, -NegativeInfinity and NaN compare -as equal to themselves. +Values of type float and double are normally compared using a tolerance specified by the **Within** modifier. The +special values PositiveInfinity, NegativeInfinity and NaN compare as equal to themselves. -Floating-point values may be compared using a tolerance -in "Units in the Last Place" or ULPs. For certain types of numerical work, -this is safer than a fixed tolerance because it automatically compensates -for the added inaccuracy of larger numbers. +Floating-point values may be compared using a tolerance in "Units in the Last Place" or ULPs. For certain types of +numerical work, this is safer than a fixed tolerance because it automatically compensates for the added inaccuracy of +larger numbers. ```csharp Assert.That(2.1 + 1.2, Is.EqualTo(3.3).Within(.0005)); @@ -84,9 +78,8 @@ Assert.That(20000000000000004.0, Is.EqualTo(20000000000000000.0).Within(1).Ulps) ## Comparing Strings -String comparisons normally respect case. The `IgnoreCase` modifier -causes the comparison to be case-insensitive. It may also be used when -comparing arrays or collections of strings. +String comparisons normally respect case. The `IgnoreCase` modifier causes the comparison to be case-insensitive. It may +also be used when comparing arrays or collections of strings. ```csharp Assert.That("Hello!", Is.Not.EqualTo("HELLO!")); @@ -98,14 +91,12 @@ string[] actual = new string[] { "HELLO", "world" }; ## Comparing DateTimes and TimeSpans -**DateTimes** and **TimeSpans** may be compared either with or without -a tolerance. A tolerance is specified using **Within** with either a -**TimeSpan** as an argument or with a numeric value followed by a one of -the time conversion modifiers: **Days**, **Hours**, **Minutes**, -**Seconds**, **Milliseconds** or **Ticks**. +**DateTimes** and **TimeSpans** may be compared either with or without a tolerance. A tolerance is specified using +**Within** with either a **TimeSpan** as an argument or with a numeric value followed by a one of the time conversion +modifiers: **Days**, **Hours**, **Minutes**, **Seconds**, **Milliseconds** or **Ticks**. -When comparing **DateTimeOffsets** you can use the optional **WithSameOffset** -modifier to check the offset along with the date and time. +When comparing **DateTimeOffsets** you can use the optional **WithSameOffset** modifier to check the offset along with +the date and time. ```csharp DateTime now = DateTime.Now; @@ -118,23 +109,19 @@ Assert.That(later, Is.EqualTo(now).Within(3).Hours); ## Comparing Arrays, Collections and IEnumerables -Since version 2.2, NUnit has been able to compare two single-dimensioned arrays. -Beginning with version 2.4, multi-dimensioned arrays, nested arrays (arrays of arrays) -and collections may be compared. With version 2.5, any IEnumerable is supported. -Two arrays, collections or IEnumerables are considered equal if they have the -same dimensions and if each of the corresponding elements is equal. +Since version 2.2, NUnit has been able to compare two single-dimensioned arrays. Beginning with version 2.4, +multi-dimensioned arrays, nested arrays (arrays of arrays) and collections may be compared. With version 2.5, any +IEnumerable is supported. Two arrays, collections or IEnumerables are considered equal if they have the same dimensions +and if each of the corresponding elements is equal. -If you want to treat two arrays of different shapes as simple collections -for purposes of comparison, use the **AsCollection** modifier, which causes -the comparison to be made element by element, without regard for the rank or -dimensions of the array. Note that jagged arrays (arrays of arrays) do not -have a single underlying collection. The modifier would be applied -to each array separately, which has no effect in most cases. +If you want to treat two arrays of different shapes as simple collections for purposes of comparison, use the +**AsCollection** modifier, which causes the comparison to be made element by element, without regard for the rank or +dimensions of the array. Note that jagged arrays (arrays of arrays) do not have a single underlying collection. The +modifier would be applied to each array separately, which has no effect in most cases. -The `AsCollection` modifier is also useful on classes implementing both `IEnumerable` -and `IEquatable`. Without the modifier, the `IEquatable` implementation is used to -test equality. With the modifier specified, `IEquatable` is ignored and the contents -of the enumeration are compared one by one. +The `AsCollection` modifier is also useful on classes implementing both `IEnumerable` and `IEquatable`. Without the +modifier, the `IEquatable` implementation is used to test equality. With the modifier specified, `IEquatable` is ignored +and the contents of the enumeration are compared one by one. ```csharp int[] i3 = new int[] { 1, 2, 3 }; @@ -156,14 +143,12 @@ Two dictionaries are considered equal if 1. The list of keys is the same - without regard to ordering. 2. The values associated with each key are equal. -You can use this capability to compare any two objects implementing -**IDictionary**. Generic and non-generic dictionaries (Hashtables) -may be successfully compared. +You can use this capability to compare any two objects implementing **IDictionary**. Generic and non-generic +dictionaries (Hashtables) may be successfully compared. ## Comparing DirectoryInfo -Two DirectoryInfo objects are considered equal if -both have the same path, creation time and last access time. +Two DirectoryInfo objects are considered equal if both have the same path, creation time and last access time. ```csharp Assert.That(new DirectoryInfo(actual), Is.EqualTo(expected)); @@ -171,24 +156,19 @@ Assert.That(new DirectoryInfo(actual), Is.EqualTo(expected)); ## User-Specified Comparers -If the default NUnit or .NET behavior for testing equality doesn't -meet your needs, you can supply a comparer of your own through the -`Using` modifier. When used with `EqualConstraint`, you -may supply an `IEqualityComparer`, `IEqualityComparer`, -`IComparer`, `IComparer` or `Comparison` -as the argument to `Using`. +If the default NUnit or .NET behavior for testing equality doesn't meet your needs, you can supply a comparer of your +own through the `Using` modifier. When used with `EqualConstraint`, you may supply an `IEqualityComparer`, +`IEqualityComparer`, `IComparer`, `IComparer` or `Comparison` as the argument to `Using`. ```csharp Assert.That(myObj1, Is.EqualTo(myObj2).Using(myComparer)); ``` -Prior to NUnit 2.6, only one comparer could be used. If multiple -comparers were specified, all but one was ignored. Beginning with NUnit 2.6, -multiple generic comparers for different types may be specified. NUnit -will use the appropriate comparer for any two types being compared. As a result, -it is now possible to provide a comparer for an array, a collection type or -a dictionary. The user-provided comparer will be used directly, bypassing the -default NUnit logic for array, collection or dictionary equality. +Prior to NUnit 2.6, only one comparer could be used. If multiple comparers were specified, all but one was ignored. +Beginning with NUnit 2.6, multiple generic comparers for different types may be specified. NUnit will use the +appropriate comparer for any two types being compared. As a result, it is now possible to provide a comparer for an +array, a collection type or a dictionary. The user-provided comparer will be used directly, bypassing the default NUnit +logic for array, collection or dictionary equality. ```csharp class ListOfIntComparer : IEqualityComparer> @@ -205,14 +185,31 @@ Assert.That(list1, Is.EqualTo(list2).Using(myComparer)); ## Notes -1. When checking the equality of user-defined classes, NUnit first examines each class to determine whether it implements `IEquatable` (unless the `AsCollection` modifier is used). If either object implements the interface for the type of the other object, then that implementation is used in making the comparison. If neither class implements the appropriate interface, NUnit makes use of the `Equals` override on the expected object. If you neglect to either implement `IEquatable` or to override `Equals`, you can expect failures comparing non-identical objects. In particular, overriding `operator ==` without overriding `Equals` or implementing the interface has no effect. -2. The **Within** modifier was originally designed for use with floating point values only. Beginning with NUnit 2.4, comparisons of **DateTime** values may use a **TimeSpan** as a tolerance. Beginning with NUnit 2.4.2, non-float numeric comparisons may also specify a tolerance. -3. Float and double comparisons for which no tolerance is specified use a default value, which can be specified with **DefaultFloatingPointToleranceAttribute**. If this is not in place, a tolerance of 0.0d is used. (Prior to NUnit 3.7, default tolerance was instead set via `GlobalSettings.DefaultFloatingPointTolerance`.) -4. Prior to NUnit 2.2.3, comparison of two NaN values would always fail, as specified by IEEE floating point standards. The new behavior, was introduced after some discussion because it seems more useful in tests. To avoid confusion, consider using **Is.NaN** where appropriate. -5. When an equality test between two strings fails, the relevant portion of both strings is displayed in the error message, clipping the strings to fit the length of the line as needed. Beginning with 2.4.4, this behavior may be modified by use of the **NoClip** modifier on the constraint. In addition, the maximum line length may be modified for all tests by setting the value of **TextMessageWriter.MaximumLineLength** in the appropriate level of setup. -6. When used with arrays, collections or dictionaries, EqualConstraint operates recursively. Any modifiers are saved and used as they apply to individual items. -7. A user-specified comparer will not be called by **EqualConstraint** if either or both arguments are null. If both are null, the Constraint succeeds. If only one is null, it fails. -8. NUnit has special semantics for comparing **Streams** and **DirectoryInfos**. For a **Stream**, the contents are compared. For a **DirectoryInfo**, the first-level directory contents are compared. +1. When checking the equality of user-defined classes, NUnit first examines each class to determine whether it + implements `IEquatable` (unless the `AsCollection` modifier is used). If either object implements the interface + for the type of the other object, then that implementation is used in making the comparison. If neither class + implements the appropriate interface, NUnit makes use of the `Equals` override on the expected object. If you neglect + to either implement `IEquatable` or to override `Equals`, you can expect failures comparing non-identical objects. + In particular, overriding `operator ==` without overriding `Equals` or implementing the interface has no effect. +2. The **Within** modifier was originally designed for use with floating point values only. Beginning with NUnit 2.4, + comparisons of **DateTime** values may use a **TimeSpan** as a tolerance. Beginning with NUnit 2.4.2, non-float + numeric comparisons may also specify a tolerance. +3. Float and double comparisons for which no tolerance is specified use a default value, which can be specified with + **DefaultFloatingPointToleranceAttribute**. If this is not in place, a tolerance of 0.0d is used. (Prior to NUnit + 3.7, default tolerance was instead set via `GlobalSettings.DefaultFloatingPointTolerance`.) +4. Prior to NUnit 2.2.3, comparison of two NaN values would always fail, as specified by IEEE floating point standards. + The new behavior, was introduced after some discussion because it seems more useful in tests. To avoid confusion, + consider using **Is.NaN** where appropriate. +5. When an equality test between two strings fails, the relevant portion of both strings is displayed in the error + message, clipping the strings to fit the length of the line as needed. Beginning with 2.4.4, this behavior may be + modified by use of the **NoClip** modifier on the constraint. In addition, the maximum line length may be modified + for all tests by setting the value of **TextMessageWriter.MaximumLineLength** in the appropriate level of setup. +6. When used with arrays, collections or dictionaries, EqualConstraint operates recursively. Any modifiers are saved and + used as they apply to individual items. +7. A user-specified comparer will not be called by **EqualConstraint** if either or both arguments are null. If both are + null, the Constraint succeeds. If only one is null, it fails. +8. NUnit has special semantics for comparing **Streams** and **DirectoryInfos**. For a **Stream**, the contents are + compared. For a **DirectoryInfo**, the first-level directory contents are compared. ## See also diff --git a/docs/articles/nunit/writing-tests/constraints/ExactCountConstraint.md b/docs/articles/nunit/writing-tests/constraints/ExactCountConstraint.md index d8f18d1d7..dbc3c65b0 100644 --- a/docs/articles/nunit/writing-tests/constraints/ExactCountConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/ExactCountConstraint.md @@ -2,9 +2,11 @@ `ExactCountConstraint` has two functions. -In its simplest use, it simply verifies the number of items in an array, collection or `IEnumerable`, providing a way to count items that is independent of any `Length` or `Count` property. +In its simplest use, it simply verifies the number of items in an array, collection or `IEnumerable`, providing a way to +count items that is independent of any `Length` or `Count` property. -When used with another constraint, it applies that constraint to each item in the array, collection or `IEnumerable`, succeeding if the specified number of items succeed. +When used with another constraint, it applies that constraint to each item in the array, collection or `IEnumerable`, +succeeding if the specified number of items succeed. An exception is thrown if the actual value passed does not implement `IEnumerable`. @@ -34,8 +36,10 @@ Assert.That(array, Has.Exactly(1).EqualTo(1).And.Exactly(1).EqualTo(3)); ``` > [!NOTE] -> The keyword `Items` is optional when used before a constraint but required when merely counting items with no constraint specified. +> The keyword `Items` is optional when used before a constraint but required when merely counting items with no +> constraint specified. ## See also -* [PropertyConstraint](PropertyConstraint.md) - For constraints on the `Count` or `Length` property, e.g. `Has.Count.GreaterThan(10)` or `Has.Length.EqualTo(6)`. +* [PropertyConstraint](PropertyConstraint.md) - For constraints on the `Count` or `Length` property, e.g. + `Has.Count.GreaterThan(10)` or `Has.Length.EqualTo(6)`. diff --git a/docs/articles/nunit/writing-tests/constraints/NoItemConstraint.md b/docs/articles/nunit/writing-tests/constraints/NoItemConstraint.md index 91d0b1a98..82a6fff06 100644 --- a/docs/articles/nunit/writing-tests/constraints/NoItemConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/NoItemConstraint.md @@ -1,6 +1,7 @@ # NoItem Constraint -`NoItemConstraint` applies a constraint to each item in a collection, succeeding only if all of them fail. An exception is thrown if the actual value passed does not implement `IEnumerable`. +`NoItemConstraint` applies a constraint to each item in a collection, succeeding only if all of them fail. An exception +is thrown if the actual value passed does not implement `IEnumerable`. ## Constructor diff --git a/docs/articles/nunit/writing-tests/constraints/NotConstraint.md b/docs/articles/nunit/writing-tests/constraints/NotConstraint.md index b36ed62a8..41821ca82 100644 --- a/docs/articles/nunit/writing-tests/constraints/NotConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/NotConstraint.md @@ -1,6 +1,7 @@ # Not Constraint -`NotConstraint` reverses the effect of another constraint. If the base constraint fails, NotConstraint succeeds. If the base constraint succeeds, NotConstraint fails. +`NotConstraint` reverses the effect of another constraint. If the base constraint fails, NotConstraint succeeds. If the +base constraint succeeds, NotConstraint fails. ## Constructor diff --git a/docs/articles/nunit/writing-tests/constraints/OrConstraint.md b/docs/articles/nunit/writing-tests/constraints/OrConstraint.md index 19e388b14..25c33a76d 100644 --- a/docs/articles/nunit/writing-tests/constraints/OrConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/OrConstraint.md @@ -22,8 +22,10 @@ Assert.That(3, Is.LessThan(5).Or.GreaterThan(10)); ## Evaluation Order and Precedence -Note that the constraint evaluates the sub-constraints left to right, meaning that `Assert.That(i, Is.Null.Or.GreaterThan(9));` where `i` is a nullable `int` will work for both `12` and `null`. On the other hand, -`Assert.That(i, Is.GreaterThan(9).Or.Null);` will only work for `12`, but throw an exception for `null`, as `null` cannot be compared to `9`. +Note that the constraint evaluates the sub-constraints left to right, meaning that +`Assert.That(i,Is.Null.Or.GreaterThan(9));` where `i` is a nullable `int` will work for both `12` and `null`. On the +other hand, `Assert.That(i, Is.GreaterThan(9).Or.Null);` will only work for `12`, but throw an exception for `null`, as +`null` cannot be compared to `9`. The **OrConstraint** has precedence over the **AndConstraint**. diff --git a/docs/articles/nunit/writing-tests/constraints/PropertyConstraint.md b/docs/articles/nunit/writing-tests/constraints/PropertyConstraint.md index d45f953ff..c26f74ac9 100644 --- a/docs/articles/nunit/writing-tests/constraints/PropertyConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/PropertyConstraint.md @@ -1,7 +1,7 @@ # Property Constraint -`PropertyConstraint` tests for the existence of a named property on an object and then -applies a constraint test to the property value. +`PropertyConstraint` tests for the existence of a named property on an object and then applies a constraint test to the +property value. ## Constructor @@ -23,7 +23,8 @@ Assert.That(collection, Has.Property("Count").GreaterThan(10)); Assert.That(collection, Has.Count.GreaterThan(10); ``` -As shown in the example, certain common properties are known to NUnit and may be tested using a shorter form. The following properties are supported: +As shown in the example, certain common properties are known to NUnit and may be tested using a shorter form. The +following properties are supported: ```csharp Has.Length... diff --git a/docs/articles/nunit/writing-tests/constraints/SomeItemsConstraint.md b/docs/articles/nunit/writing-tests/constraints/SomeItemsConstraint.md index b4d9134ef..01b14c133 100644 --- a/docs/articles/nunit/writing-tests/constraints/SomeItemsConstraint.md +++ b/docs/articles/nunit/writing-tests/constraints/SomeItemsConstraint.md @@ -1,6 +1,7 @@ # SomeItems Constraint -`SomeItemsConstraint` applies a constraint to each item in an `IEnumerable`, succeeding if at least one of them succeeds. An exception is thrown if the actual value passed does not implement `IEnumerable`. +`SomeItemsConstraint` applies a constraint to each item in an `IEnumerable`, succeeding if at least one of them +succeeds. An exception is thrown if the actual value passed does not implement `IEnumerable`. ## Constructor diff --git a/docs/articles/nunit/writing-tests/setup-teardown/SetUp-and-TearDown-Changes.md b/docs/articles/nunit/writing-tests/setup-teardown/SetUp-and-TearDown-Changes.md index 8a8c60093..af5517186 100644 --- a/docs/articles/nunit/writing-tests/setup-teardown/SetUp-and-TearDown-Changes.md +++ b/docs/articles/nunit/writing-tests/setup-teardown/SetUp-and-TearDown-Changes.md @@ -14,23 +14,29 @@ Existing NUnit 2.6.4 attributes used for SetUp and TearDown were * TestFixtureTearDownAttribute * SetUpFixtureAttribute -Taken together, these attributes provided per-test setup and teardown at the fixture level and one-time setup and teardown at the fixture, namespace and assembly levels. +Taken together, these attributes provided per-test setup and teardown at the fixture level and one-time setup and +teardown at the fixture, namespace and assembly levels. These features were somewhat confusing: * SetUpFixture seems not very well understood by users in general. * TestFixtureSetUp and TestFixtureTearDown could do with better names. -* SetUp and TearDown designate per-test setup/teardown within a test fixture, one-time setup/teardown within a setup fixture +* SetUp and TearDown designate per-test setup/teardown within a test fixture, one-time setup/teardown within a setup + fixture -For NUnit 3.0 we standardized the use of attributes for setup and teardown and renamed some of them to make their function clearer. +For NUnit 3.0 we standardized the use of attributes for setup and teardown and renamed some of them to make their +function clearer. ## Attribute Usage * [SetUpAttribute](xref:setup-attribute) is now used exclusively for per-test setup. * [TearDownAttribute](xref:teardown-attribute) is now used exclusively for per-test teardown. -* [OneTimeSetUpAttribute](xref:onetimesetup-attribute) is used for one-time setup per test-run. If you run _n_ tests, this event will only occur once. -* [OneTimeTearDownAttribute](xref:onetimeteardown-attribute) is used for one-time teardown per test-run. If you run _n_ tests, this event will only occur once -* [SetUpFixtureAttribute](xref:setupfixture-attribute) continues to be used as at before, but with changed method attributes. +* [OneTimeSetUpAttribute](xref:onetimesetup-attribute) is used for one-time setup per test-run. If you run _n_ tests, + this event will only occur once. +* [OneTimeTearDownAttribute](xref:onetimeteardown-attribute) is used for one-time teardown per test-run. If you run _n_ + tests, this event will only occur once +* [SetUpFixtureAttribute](xref:setupfixture-attribute) continues to be used as at before, but with changed method + attributes. ### Attribute Usage by Fixture Type @@ -45,19 +51,28 @@ For NUnit 3.0 we standardized the use of attributes for setup and teardown and r ## Backward Compatibility -**TestFixtureSetUpAttribute** and **TestFixtureTearDownAttribute** continue to be supported as synonyms for **OneTimeSetUpAttribute** and **OneTimeTearDownAttribute** in test fixtures, but are deprecated. +**TestFixtureSetUpAttribute** and **TestFixtureTearDownAttribute** continue to be supported as synonyms for +**OneTimeSetUpAttribute** and **OneTimeTearDownAttribute** in test fixtures, but are deprecated. -Since **SetUpAttribute** and **TearDownAttribute** are used in two different ways, it's not possible to simply deprecate their usage in SetUpFixture. They have been disallowed in that context, which is a [breaking change](xref:breakingchanges). +Since **SetUpAttribute** and **TearDownAttribute** are used in two different ways, it's not possible to simply deprecate +their usage in SetUpFixture. They have been disallowed in that context, which is a [breaking +change](xref:breakingchanges). ## How Setup and TearDown Methods Are Called -Multiple SetUp, OneTimeSetUp, TearDown and OneTimeTearDown methods may exist within a class. The rules for how the setup methods are called will be the same in NUnit 3.0 as in NUnit 2.6. However, there is a change in the calling of the teardown methods. +Multiple SetUp, OneTimeSetUp, TearDown and OneTimeTearDown methods may exist within a class. The rules for how the setup +methods are called will be the same in NUnit 3.0 as in NUnit 2.6. However, there is a change in the calling of the +teardown methods. -Setup methods (both types) are called on base classes first, then on derived classes. If any setup method throws an exception, no further setups are called. This is the same as in NUnit 2.6. +Setup methods (both types) are called on base classes first, then on derived classes. If any setup method throws an +exception, no further setups are called. This is the same as in NUnit 2.6. -Teardown methods (again, both types) are called on derived classes first, then on the base class. In NUnit 2.6, all teardown methods were called so long as **any** setup method was called. It was entirely up to the teardown method to determine how much of the initialization took place. +Teardown methods (again, both types) are called on derived classes first, then on the base class. In NUnit 2.6, all +teardown methods were called so long as **any** setup method was called. It was entirely up to the teardown method to +determine how much of the initialization took place. -In NUnit 3.0, the teardown methods at any level in the inheritance hierarchy will be called only if a setup method **at the same level** was called. The following example is illustrates the difference. +In NUnit 3.0, the teardown methods at any level in the inheritance hierarchy will be called only if a setup method **at +the same level** was called. The following example is illustrates the difference. ```csharp public class BaseClass @@ -98,4 +113,5 @@ This is potentially a [breaking change](xref:breakingchanges) for some users. ## Unresolved Issues -* We need to define how setup and teardown methods are ordered with respect to the newly introduced [Action Attributes](xref:actionattributes) and how they interact. +* We need to define how setup and teardown methods are ordered with respect to the newly introduced [Action + Attributes](xref:actionattributes) and how they interact. diff --git a/docs/articles/nunit/writing-tests/setup-teardown/index.md b/docs/articles/nunit/writing-tests/setup-teardown/index.md index 1aaca5137..4a9b792c9 100644 --- a/docs/articles/nunit/writing-tests/setup-teardown/index.md +++ b/docs/articles/nunit/writing-tests/setup-teardown/index.md @@ -4,9 +4,12 @@ * [SetUpAttribute](../attributes/setup.md) is now used exclusively for per-test setup. * [TearDownAttribute](../attributes/teardown.md) is now used exclusively for per-test teardown. -* [OneTimeSetUpAttribute](../attributes/onetimesetup.md) is used for one-time setup per test-run. If you run _n_ tests, this event will only occur once. -* [OneTimeTearDownAttribute](../attributes/onetimeteardown.md) is used for one-time teardown per test-run. If you run _n_ tests, this event will only occur once -* [SetUpFixtureAttribute](../attributes/setupfixture.md) continues to be used as at before, but with changed method attributes. +* [OneTimeSetUpAttribute](../attributes/onetimesetup.md) is used for one-time setup per test-run. If you run _n_ tests, + this event will only occur once. +* [OneTimeTearDownAttribute](../attributes/onetimeteardown.md) is used for one-time teardown per test-run. If you run + _n_ tests, this event will only occur once +* [SetUpFixtureAttribute](../attributes/setupfixture.md) continues to be used as at before, but with changed method + attributes. ### Attribute Usage by Fixture Type @@ -23,9 +26,12 @@ Multiple SetUp, OneTimeSetUp, TearDown and OneTimeTearDown methods may exist within a class. -Setup methods (both types) are called on base classes first, then on derived classes. If any setup method throws an exception, no further setups are called. +Setup methods (both types) are called on base classes first, then on derived classes. If any setup method throws an +exception, no further setups are called. -Teardown methods (again, both types) are called on derived classes first, then on the base class. The teardown methods at any level in the inheritance hierarchy will be called only if a setup method **at the same level** was called. The following example illustrates the difference. +Teardown methods (again, both types) are called on derived classes first, then on the base class. The teardown methods +at any level in the inheritance hierarchy will be called only if a setup method **at the same level** was called. The +following example illustrates the difference. ```csharp public class BaseClass diff --git a/docs/articles/vs-test-adapter/Adapter-Engine-Compatibility.md b/docs/articles/vs-test-adapter/Adapter-Engine-Compatibility.md index de34529d2..a966c06d1 100644 --- a/docs/articles/vs-test-adapter/Adapter-Engine-Compatibility.md +++ b/docs/articles/vs-test-adapter/Adapter-Engine-Compatibility.md @@ -1,12 +1,17 @@ # Compatibility of the Test Adapter with the Test Engine -The `NUnit3TestAdapter` has an embedded `NUnit.Engine` package. This means that you don't need to install the engine separately, and you don't need to add a reference to the engine in your test project. +The `NUnit3TestAdapter` has an embedded `NUnit.Engine` package. This means that you don't need to install the engine +separately, and you don't need to add a reference to the engine in your test project. -You should **never** add an extra reference to the `NUnit.Engine` when using the adapter in a project, as that may cause the adapter to malfunction. +You should **never** add an extra reference to the `NUnit.Engine` when using the adapter in a project, as that may cause +the adapter to malfunction. -[@CharliePoole](https://github.com/charliepoole) has written a [blog post](http://charliepoole.org/technical/nunit-engine-version-conflicts-in-visual-studio.html) about the compatibility of the adapter with the engine, explaining how it works and how you should work with both the console, engine and adapter. +[@CharliePoole](https://github.com/charliepoole) has written a [blog +post](http://charliepoole.org/technical/nunit-engine-version-conflicts-in-visual-studio.html) about the compatibility of +the adapter with the engine, explaining how it works and how you should work with both the console, engine and adapter. -The table below shows the embedded engine versions for the different adapter versions, extended from Charlie's blog post. +The table below shows the embedded engine versions for the different adapter versions, extended from Charlie's blog +post. | Adapter version | Embedded engine version | | --------------- | ----------------------- | @@ -28,16 +33,24 @@ The table below shows the embedded engine versions for the different adapter ver ## Using the console -If, for some unknown reason, you really badly want to use the NUnit.Console, and you really want to add it as a package reference instead of just installing it globally, you should use the exact same version as listed for the engine in the table above. +If, for some unknown reason, you really badly want to use the NUnit.Console, and you really want to add it as a package +reference instead of just installing it globally, you should use the exact same version as listed for the engine in the +table above. -Note that most of what the console can do, can be done using the `dotnet test` command with the appropriate runsettings added, see [Tips&Tricks](https://docs.nunit.org/articles/vs-test-adapter/Tips-And-Tricks.html). +Note that most of what the console can do, can be done using the `dotnet test` command with the appropriate runsettings +added, see [Tips&Tricks](https://docs.nunit.org/articles/vs-test-adapter/Tips-And-Tricks.html). ## :warning: Warning -If you try to add another engine version package, it may seem that the adapter and test are still working. That is just by luck, and it does so because the interfaces between the version you have added are the same as the embedded version. But if you try to use a feature that is not in the embedded version, it will fail. +If you try to add another engine version package, it may seem that the adapter and test are still working. That is just +by luck, and it does so because the interfaces between the version you have added are the same as the embedded version. +But if you try to use a feature that is not in the embedded version, it will fail. Most likely you will see messages about "no tests found", or it may simply crash during test. ## :warning: Warning -Version 4.4.1 use an engine version that is not released yet. This is because the engine has a bug that prevents it from working with the adapter. The bug is fixed in the engine, but the fix is not yet released. The adapter will be updated to use the released engine version as soon as it is released. You may try to use 3.15.2, but we can currently not confirm that it works. +Version 4.4.1 use an engine version that is not released yet. This is because the engine has a bug that prevents it +from working with the adapter. The bug is fixed in the engine, but the fix is not yet released. The adapter will be +updated to use the released engine version as soon as it is released. You may try to use 3.15.2, but we can currently +not confirm that it works. diff --git a/docs/articles/vs-test-adapter/Adapter-Installation.md b/docs/articles/vs-test-adapter/Adapter-Installation.md index c20aa293f..991cbff86 100644 --- a/docs/articles/vs-test-adapter/Adapter-Installation.md +++ b/docs/articles/vs-test-adapter/Adapter-Installation.md @@ -8,7 +8,8 @@ You'll need to install the adapter as a NuGet package for each of your test proj ## Installing the NuGet Package -You will most likely want to add a new NUnit Test Project to your solution. The easiest way is to use the ```dotnet``` command on the command line. +You will most likely want to add a new NUnit Test Project to your solution. The easiest way is to use the ```dotnet``` +command on the command line. Go to your project root and where you want to add your project. @@ -16,11 +17,13 @@ Create a folder for the project with a name matching what your new test project Then run the command `dotnet new nunit`. -You will now get a complete nunit test project with the same name as the folder. You will also have a template unit test class there as a starter. +You will now get a complete nunit test project with the same name as the folder. You will also have a template unit +test class there as a starter. If you have a Visual Studio solution file in the root folder, you can go there and add the new nunit csproj easily: -Assume you are at a solution root, and you either have a solution file, or have just been adding it with `dotnet new sln`. +Assume you are at a solution root, and you either have a solution file, or have just been adding it with `dotnet new +sln`. ```cmd md Whatever.Test @@ -34,12 +37,16 @@ And you're ready to go ! ### Manually Adding the Adapter as a Package Reference to Your Test Projects -When adding packages manually, we recommended installing the framework, the adapter, and the analyzer for optimal out-of-the-box functionality. The adapter and the framework are required. The analyzer will help during development, but is not strictly required to make your project work. `coverlet.collector` is the recommended code coverage package you should go for. +When adding packages manually, we recommended installing the framework, the adapter, and the analyzer for optimal +out-of-the-box functionality. The adapter and the framework are required. The analyzer will help during development, +but is not strictly required to make your project work. `coverlet.collector` is the recommended code coverage package +you should go for. You should ensure you also reference `Microsoft.NET.Test.Sdk` as well; it is required for test discoverability. 1. Open your test project `csproj` file -2. Add the necessary package references as shown in the snippet example below (NOTE: these are the current versions at time of writing; you'll want to install the latest versions.) +2. Add the necessary package references as shown in the snippet example below (NOTE: these are the current versions at + time of writing; you'll want to install the latest versions.) ```xml @@ -55,7 +62,9 @@ Note: *You don't need to, nor should you, add any nunit.console or any other run ### Working with the Visual Studio Nuget manager -If you have a legacy project type, or prefer working outside of the command line, you can also use the Visual Studio 'Manage NuGet packages in the solution' menu option. It can also be used for the new SDK projects, but you may find it faster to open the `csproj` and copy/paste the references in. +If you have a legacy project type, or prefer working outside of the command line, you can also use the Visual Studio +'Manage NuGet packages in the solution' menu option. It can also be used for the new SDK projects, but you may find it +faster to open the `csproj` and copy/paste the references in. With an active solution in Visual Studio, follow these steps: diff --git a/docs/articles/vs-test-adapter/Adapter-Source-Stepping.md b/docs/articles/vs-test-adapter/Adapter-Source-Stepping.md index 03eb2c0cf..65fbc6660 100644 --- a/docs/articles/vs-test-adapter/Adapter-Source-Stepping.md +++ b/docs/articles/vs-test-adapter/Adapter-Source-Stepping.md @@ -1,8 +1,11 @@ # Adapter Source Stepping -As of version 3.10, the NUnit3TestAdapter NuGet package and VSIX contain source-indexed PDBs for the adapter. Debuggers can step into the source code, set breakpoints, watch variables, etc. It’s easy to drop into NUnit adapter code any time you want to understand what’s going on. +As of version 3.10, the NUnit3TestAdapter NuGet package and VSIX contain source-indexed PDBs for the adapter. Debuggers +can step into the source code, set breakpoints, watch variables, etc. It’s easy to drop into NUnit adapter code any time +you want to understand what’s going on. -If you’re getting ready to report a bug in the adapter, figuring out how to create a minimal repro is much easier since you aren’t dealing with a black box! +If you’re getting ready to report a bug in the adapter, figuring out how to create a minimal repro is much easier since +you aren’t dealing with a black box! ## How to step into adapter source in the Visual Studio debugger @@ -11,16 +14,19 @@ The NUnit adapter PDBs are source-linked and work with Visual Studio 2017 or lat * Turn **off** Debug > Options > ‘Enable Just My Code.’ > [!NOTE] -> This is something you’ll want to leave on and only turn off when you want to step into source that isn’t contained in your solution. +> This is something you’ll want to leave on and only turn off when you want to step into source that isn’t +> contained in your solution. ![Screenshot of how to disable just my code in Visual Studio](~/images/disable-just-my-code.png) -(Next time you can make this faster by installing the excellent extension -[Just My Code Toggle](https://marketplace.visualstudio.com/items?itemName=SamHarwell.JustMyCodeToggle). -This allows you to set a keyboard shortcut along with adding a toolbar button and call stack context menu item.) +(Next time you can make this faster by installing the excellent extension [Just My Code +Toggle](https://marketplace.visualstudio.com/items?itemName=SamHarwell.JustMyCodeToggle). This allows you to set a +keyboard shortcut along with adding a toolbar button and call stack context menu item.) * If needed, turn **on** Debug > Options > ‘Enable Source Link support.’ This can usually be left on. ![Screenshot of how to enable source link support in Visual Studio](~/images/enable-source-link-support.png) -* Congratulations! You can now use the debugger to step into method calls to the NUnit adapter and to set breakpoints and watch variables in the source! Keep in mind that it’s still a release build of the adapter, so variables and sequence points may not be available depending on runtime optimizations. +* Congratulations! You can now use the debugger to step into method calls to the NUnit adapter and to set breakpoints + and watch variables in the source! Keep in mind that it’s still a release build of the adapter, so variables and + sequence points may not be available depending on runtime optimizations. diff --git a/docs/articles/vs-test-adapter/AdapterV2-Release-Notes.md b/docs/articles/vs-test-adapter/AdapterV2-Release-Notes.md index 7f62333f6..265ce3953 100644 --- a/docs/articles/vs-test-adapter/AdapterV2-Release-Notes.md +++ b/docs/articles/vs-test-adapter/AdapterV2-Release-Notes.md @@ -6,14 +6,18 @@ Updates the NUnit framework to 2.7.1 -* [#186](https://github.com/nunit/nunit-vs-adapter/issues/186) How to change used NUnit 2 version of test adapter to e.g. v2.7.1 ? +* [#186](https://github.com/nunit/nunit-vs-adapter/issues/186) How to change used NUnit 2 version of test adapter to + e.g. v2.7.1 ? * [#184](https://github.com/nunit/nunit-vs-adapter/issues/184) Update NUnit library to 2.7.1 -Thanks to [BobSilent](https://github.com/BobSilent) for [#188](https://github.com/nunit/nunit-vs-adapter/pull/188) solving [#184](https://github.com/nunit/nunit-vs-adapter/issues/184) and [#186](https://github.com/nunit/nunit-vs-adapter/issues/186). +Thanks to [BobSilent](https://github.com/BobSilent) for [#188](https://github.com/nunit/nunit-vs-adapter/pull/188) +solving [#184](https://github.com/nunit/nunit-vs-adapter/issues/184) and +[#186](https://github.com/nunit/nunit-vs-adapter/issues/186). #### Bugs -[189](https://github.com/nunit/nunit-vs-adapter/issues/189) NUnit adapter is failing when PropertyAttribute is used with NULL value +[189](https://github.com/nunit/nunit-vs-adapter/issues/189) NUnit adapter is failing when PropertyAttribute is used with +NULL value --- @@ -22,12 +26,15 @@ Thanks to [BobSilent](https://github.com/BobSilent) for [#188](https://github.co ### Features * [#180](https://github.com/nunit/nunit-vs-adapter/issues/180) NUnit 2 test adapter does not support Visual Studio 2019 -* [#175](https://github.com/nunit/nunit-vs-adapter/issues/175) NuGet Package : Add `repository` metadata. Thanks to [MaximRouiller](https://github.com/MaximRouiller) for the PR -* [#174](https://github.com/nunit/nunit-vs-adapter/issues/174) NUnitTestAdapter 2.1.1 not working with Visual Studio 2017 15.8.0 +* [#175](https://github.com/nunit/nunit-vs-adapter/issues/175) NuGet Package : Add `repository` metadata. Thanks to + [MaximRouiller](https://github.com/MaximRouiller) for the PR +* [#174](https://github.com/nunit/nunit-vs-adapter/issues/174) NUnitTestAdapter 2.1.1 not working with Visual Studio + 2017 15.8.0 ### Bugfixes -* [#147](https://github.com/nunit/nunit-vs-adapter/issues/147) Fails to resolve assembly for base type of TestFixture if placed in a different dll +* [#147](https://github.com/nunit/nunit-vs-adapter/issues/147) Fails to resolve assembly for base type of TestFixture if + placed in a different dll * [#178](https://github.com/nunit/nunit-vs-adapter/issues/178) Test Explorer Picks up Zero Tests in VS 2017 for NUnit 2 --- @@ -58,8 +65,10 @@ Hotfix release ### Notes -* The NUnit V2 adapter does not support the Live Unit Testing feature in VS 2017. That support is only included with the NUnit V3 adapter. -* The package including both the adapter and the framework are discontinued. Please install the separate packages instead when upgrading. +* The NUnit V2 adapter does not support the Live Unit Testing feature in VS 2017. That support is only included with + the NUnit V3 adapter. +* The package including both the adapter and the framework are discontinued. Please install the separate packages + instead when upgrading. --- @@ -222,7 +231,8 @@ Hotfix release ### Features * Works with Visual Studio 2012 RTM. Some features require the November CTP update. -* The adapter now uses NUnit 2.6.2. Among other things, this allows us to support async test methods. See the NUnit Release Notes for more info. +* The adapter now uses NUnit 2.6.2. Among other things, this allows us to support async test methods. See the NUnit + Release Notes for more info. * Source file and line number can now be found for test cases that have an alternate name set. * Console output from tests is now displayed in the Visual Studio Output window. * TestFixtureSetUp and TestFixtureTearDown errors are now displayed in the Output window. diff --git a/docs/articles/vs-test-adapter/AdapterV3-Release-Notes.md b/docs/articles/vs-test-adapter/AdapterV3-Release-Notes.md index 4410abfaa..16a49373c 100644 --- a/docs/articles/vs-test-adapter/AdapterV3-Release-Notes.md +++ b/docs/articles/vs-test-adapter/AdapterV3-Release-Notes.md @@ -2,36 +2,51 @@ ## NUnit3 Test Adapter for Visual Studio - Version 3.17.0 - July 11, 2020 -This release has a series of enhancements and bugfixes. There have been two 3.17 beta releases (beta.1 and beta.2) published earlier on nuget.org. -A major bugfix is that the console output now is properly appearing. There are also a series of fixes for corner cases. +This release has a series of enhancements and bugfixes. There have been two 3.17 beta releases (beta.1 and beta.2) +published earlier on nuget.org. A major bugfix is that the console output now is properly appearing. There are also a +series of fixes for corner cases. -[StopOnError](/articles/vs-test-adapter/Tips-And-Tricks.html#stoponerror) can be very useful to reduce time of long test runs that are failing. +[StopOnError](/articles/vs-test-adapter/Tips-And-Tricks.html#stoponerror) can be very useful to reduce time of long test +runs that are failing. -The ability to set custom paths for the test code can be useful with data driven tests, where you want to point to the data file (and line number therein) instead of the default C# test code. +The ability to set custom paths for the test code can be useful with data driven tests, where you want to point to the +data file (and line number therein) instead of the default C# test code. See [here for all details](/articles/vs-test-adapter/Tips-And-Tricks.html) on the settings. ### Features and Enhancements -* [640](https://github.com/nunit/nunit3-vs-adapter/issues/640) Allow use of FullName as the DisplayName for Converted Tests +* [640](https://github.com/nunit/nunit3-vs-adapter/issues/640) Allow use of FullName as the DisplayName for Converted + Tests * [675](https://github.com/nunit/nunit3-vs-adapter/issues/675) Ability to set StopOnError via .runsettings -* [723](https://github.com/nunit/nunit3-vs-adapter/issues/723) and [735](https://github.com/nunit/nunit3-vs-adapter/issues/735) CodeFilePath like in nunit2 and TestCaseData: Missing Feature "Jump to File" +* [723](https://github.com/nunit/nunit3-vs-adapter/issues/723) and + [735](https://github.com/nunit/nunit3-vs-adapter/issues/735) CodeFilePath like in nunit2 and TestCaseData: Missing + Feature "Jump to File" * [740](https://github.com/nunit/nunit3-vs-adapter/issues/740) Allow Warnings to be mapped to any outcome -* [758](https://github.com/nunit/nunit3-vs-adapter/issues/758) Feature Request: Adapter to support NonTestAssemblyAttribute +* [758](https://github.com/nunit/nunit3-vs-adapter/issues/758) Feature Request: Adapter to support + NonTestAssemblyAttribute ### Resolved issues/bugs * [301](https://github.com/nunit/nunit3-vs-adapter/issues/301) Issue Revisited: Console Output -* [343](https://github.com/nunit/nunit3-vs-adapter/issues/343) Console.WriteLine() does not write to console when running`dotnet test` -* [697](https://github.com/nunit/nunit3-vs-adapter/issues/697) Test adapter props files should not add assemblies to Content ItemGroup -* [737](https://github.com/nunit/nunit3-vs-adapter/issues/737) An assembly specified in the application dependencies manifest was not found -* [745](https://github.com/nunit/nunit3-vs-adapter/issues/745) NUnit engine IDriverFactory extensions don't load using the adapter. Thanks to [aolszowka](https://github.com/aolszowka) for [PR 749](https://github.com/nunit/nunit3-vs-adapter/pull/749) -* [750](https://github.com/nunit/nunit3-vs-adapter/issues/750) ShadowCopyFiles doesn't work on .NET Framework. Thanks to [DavidSimner](https://github.com/DavidSimner) for [PR 751](https://github.com/nunit/nunit3-vs-adapter/pull/751) +* [343](https://github.com/nunit/nunit3-vs-adapter/issues/343) Console.WriteLine() does not write to console when + running`dotnet test` +* [697](https://github.com/nunit/nunit3-vs-adapter/issues/697) Test adapter props files should not add assemblies to + Content ItemGroup +* [737](https://github.com/nunit/nunit3-vs-adapter/issues/737) An assembly specified in the application dependencies + manifest was not found +* [745](https://github.com/nunit/nunit3-vs-adapter/issues/745) NUnit engine IDriverFactory extensions don't load using + the adapter. Thanks to [aolszowka](https://github.com/aolszowka) for [PR + 749](https://github.com/nunit/nunit3-vs-adapter/pull/749) +* [750](https://github.com/nunit/nunit3-vs-adapter/issues/750) ShadowCopyFiles doesn't work on .NET Framework. Thanks to + [DavidSimner](https://github.com/DavidSimner) for [PR 751](https://github.com/nunit/nunit3-vs-adapter/pull/751) ### Internal development stuff -* [746](https://github.com/nunit/nunit3-vs-adapter/issues/746) EditorConfig for *.props Types. Thanks to [aolszowka](https://github.com/aolszowka) for [PR 747](https://github.com/nunit/nunit3-vs-adapter/pull/747) -* [753](https://github.com/nunit/nunit3-vs-adapter/issues/753) EditorConfig for *.csproj Types. Thanks to [aolszowka](https://github.com/aolszowka) for [PR 754](https://github.com/nunit/nunit3-vs-adapter/pull/754) +* [746](https://github.com/nunit/nunit3-vs-adapter/issues/746) EditorConfig for *.props Types. Thanks to + [aolszowka](https://github.com/aolszowka) for [PR 747](https://github.com/nunit/nunit3-vs-adapter/pull/747) +* [753](https://github.com/nunit/nunit3-vs-adapter/issues/753) EditorConfig for *.csproj Types. Thanks to + [aolszowka](https://github.com/aolszowka) for [PR 754](https://github.com/nunit/nunit3-vs-adapter/pull/754) ----- @@ -41,19 +56,26 @@ This is the 2nd beta for 3.17, published on [Nuget](https://www.nuget.org/). ### Features and Enhancements -* [758](https://github.com/nunit/nunit3-vs-adapter/issues/758) Feature Request: Adapter to support NonTestAssemblyAttribute +* [758](https://github.com/nunit/nunit3-vs-adapter/issues/758) Feature Request: Adapter to support + NonTestAssemblyAttribute * [740](https://github.com/nunit/nunit3-vs-adapter/issues/740) Allow Warnings to be mapped to any outcome -* [640](https://github.com/nunit/nunit3-vs-adapter/issues/640) Allow use of FullName as the DisplayName for Converted Tests +* [640](https://github.com/nunit/nunit3-vs-adapter/issues/640) Allow use of FullName as the DisplayName for Converted + Tests ### Resolved issues/bugs -* [750](https://github.com/nunit/nunit3-vs-adapter/issues/750) ShadowCopyFiles doesn't work on .NET Framework. Thanks to [DavidSimner](https://github.com/DavidSimner) for [PR 751](https://github.com/nunit/nunit3-vs-adapter/pull/751) -* [745](https://github.com/nunit/nunit3-vs-adapter/issues/745) NUnit engine IDriverFactory extensions don't load using the adapter. Thanks to [aolszowka](https://github.com/aolszowka) for [PR 749](https://github.com/nunit/nunit3-vs-adapter/pull/749) +* [750](https://github.com/nunit/nunit3-vs-adapter/issues/750) ShadowCopyFiles doesn't work on .NET Framework. Thanks to + [DavidSimner](https://github.com/DavidSimner) for [PR 751](https://github.com/nunit/nunit3-vs-adapter/pull/751) +* [745](https://github.com/nunit/nunit3-vs-adapter/issues/745) NUnit engine IDriverFactory extensions don't load using + the adapter. Thanks to [aolszowka](https://github.com/aolszowka) for [PR + 749](https://github.com/nunit/nunit3-vs-adapter/pull/749) ### Internal development stuff -* [746](https://github.com/nunit/nunit3-vs-adapter/issues/746) EditorConfig for *.props Types. Thanks to [aolszowka](https://github.com/aolszowka) for [PR 747](https://github.com/nunit/nunit3-vs-adapter/pull/747) -* [753](https://github.com/nunit/nunit3-vs-adapter/issues/753) EditorConfig for *.csproj Types. Thanks to [aolszowka](https://github.com/aolszowka) for [PR 754](https://github.com/nunit/nunit3-vs-adapter/pull/754) +* [746](https://github.com/nunit/nunit3-vs-adapter/issues/746) EditorConfig for *.props Types. Thanks to + [aolszowka](https://github.com/aolszowka) for [PR 747](https://github.com/nunit/nunit3-vs-adapter/pull/747) +* [753](https://github.com/nunit/nunit3-vs-adapter/issues/753) EditorConfig for *.csproj Types. Thanks to + [aolszowka](https://github.com/aolszowka) for [PR 754](https://github.com/nunit/nunit3-vs-adapter/pull/754) ----- @@ -66,14 +88,19 @@ It contains new features and some bugfixes. ### Features and Enhancements * [675](https://github.com/nunit/nunit3-vs-adapter/issues/675) Ability to set StopOnError via .runsettings -* [723](https://github.com/nunit/nunit3-vs-adapter/issues/723) and [735](https://github.com/nunit/nunit3-vs-adapter/issues/735) CodeFilePath like in nunit2 and TestCaseData: Missing Feature "Jump to File" +* [723](https://github.com/nunit/nunit3-vs-adapter/issues/723) and + [735](https://github.com/nunit/nunit3-vs-adapter/issues/735) CodeFilePath like in nunit2 and TestCaseData: Missing + Feature "Jump to File" ### Resolved issues/bugs * [301](https://github.com/nunit/nunit3-vs-adapter/issues/301) Issue Revisited: Console Output -* [343](https://github.com/nunit/nunit3-vs-adapter/issues/343) Console.WriteLine() does not write to console when running`dotnet test` -* [697](https://github.com/nunit/nunit3-vs-adapter/issues/697) Test adapter props files should not add assemblies to Content ItemGroup -* [737](https://github.com/nunit/nunit3-vs-adapter/issues/737) An assembly specified in the application dependencies manifest was not found +* [343](https://github.com/nunit/nunit3-vs-adapter/issues/343) Console.WriteLine() does not write to console when + running`dotnet test` +* [697](https://github.com/nunit/nunit3-vs-adapter/issues/697) Test adapter props files should not add assemblies to + Content ItemGroup +* [737](https://github.com/nunit/nunit3-vs-adapter/issues/737) An assembly specified in the application dependencies + manifest was not found ----- @@ -81,16 +108,21 @@ It contains new features and some bugfixes. This release is a hotfix release intended to fix three major issues: -* [686](https://github.com/nunit/nunit3-vs-adapter/issues/686) NUnit3TestAdapter3.16. dotnet filter argument is not applied +* [686](https://github.com/nunit/nunit3-vs-adapter/issues/686) NUnit3TestAdapter3.16. dotnet filter argument is not + applied * [690](https://github.com/nunit/nunit3-vs-adapter/issues/690) Can run only one test case from combinatorial test -* [692](https://github.com/nunit/nunit3-vs-adapter/issues/692) NUnit Test Adaptor 3.16.0 never displays results of test under Visual Studio 2015 +* [692](https://github.com/nunit/nunit3-vs-adapter/issues/692) NUnit Test Adaptor 3.16.0 never displays results of test + under Visual Studio 2015 Together with these, the following issues are changed: -* [676](https://github.com/nunit/nunit3-vs-adapter/issues/676) Test cases are skipped with TestCaseSource under Visual Studio 2019. This works under 3.16.0, but need the changes below in a runsettings file under 3.16.1 +* [676](https://github.com/nunit/nunit3-vs-adapter/issues/676) Test cases are skipped with TestCaseSource under Visual + Studio 2019. This works under 3.16.0, but need the changes below in a runsettings file under 3.16.1 Note that this hotfix changes some of the new defaults introduced in 3.16.0. -These can be set back using the two new runsettings [UseParentFQNForParametrizedTests](xref:tipsandtricks#useparentfqnforparametrizedtests) and [UseNUnitIdforTestCaseId](xref:tipsandtricks#usenunitidfortestcaseid) +These can be set back using the two new runsettings +[UseParentFQNForParametrizedTests](xref:tipsandtricks#useparentfqnforparametrizedtests) and +[UseNUnitIdforTestCaseId](xref:tipsandtricks#usenunitidfortestcaseid) ----- @@ -98,28 +130,47 @@ These can be set back using the two new runsettings [UseParentFQNForParametrized This release has three major changes. -1. The support for .NET Core `1.*` has been removed. This is done to open up more functionality for the later .NET Core versions. Also, since .NET Core `1.*` is no longer supported by Microsoft, we decided to remove the support too. If you do have .NET Core 1.* solutions and can't upgrade, you should stay with the the adapter 3.15.1 or lower. The change also means we now support dump files in .NET Core :-). It also means the total size of the package has been reduced by around 30%. +1. The support for .NET Core `1.*` has been removed. This is done to open up more functionality for the later .NET Core + versions. Also, since .NET Core `1.*` is no longer supported by Microsoft, we decided to remove the support too. If + you do have .NET Core 1.* solutions and can't upgrade, you should stay with the the adapter 3.15.1 or lower. The + change also means we now support dump files in .NET Core :-). It also means the total size of the package has been + reduced by around 30%. -2. The filter syntax issues we've had with special names and characters have been mostly solved, thanks to excellent work by [John M.Wright](https://github.com/johnmwright). The filter syntax is now closer to a correct FQN (Full Qualified Name), but this might cause some issues with your own filter in some rare cases. The fix done resolves a lot of issues, all of them listed below. For a detailed explanation of what has been done, see the [Pull Request #668](https://github.com/nunit/nunit3-vs-adapter/pull/668). +2. The filter syntax issues we've had with special names and characters have been mostly solved, thanks to excellent + work by [John M.Wright](https://github.com/johnmwright). The filter syntax is now closer to a correct FQN (Full + Qualified Name), but this might cause some issues with your own filter in some rare cases. The fix done resolves a + lot of issues, all of them listed below. For a detailed explanation of what has been done, see the [Pull Request + #668](https://github.com/nunit/nunit3-vs-adapter/pull/668). -3. You can now use the NUnit filter syntax, either from command line or through settings in the runsettings file. This was due to an idea by [Michael Letterle](https://github.com/mletterle) and a subsequent implementation [Pull Request #669](https://github.com/nunit/nunit3-vs-adapter/pull/669). Michael also wrote [a great blog post](https://blog.prokrams.com/2019/12/16/nunit3-filter-dotnet/) to explain how this works, and how he arrived at the solution. For more information see the [NUnit Test Selection Language](xref:testselectionlanguage). +3. You can now use the NUnit filter syntax, either from command line or through settings in the runsettings file. This + was due to an idea by [Michael Letterle](https://github.com/mletterle) and a subsequent implementation [Pull Request + #669](https://github.com/nunit/nunit3-vs-adapter/pull/669). Michael also wrote [a great blog + post](https://blog.prokrams.com/2019/12/16/nunit3-filter-dotnet/) to explain how this works, and how he arrived at + the solution. For more information see the [NUnit Test Selection Language](xref:testselectionlanguage). ### Resolved issues **All the following are solved by [Pull Request #668](https://github.com/nunit/nunit3-vs-adapter/pull/668)** -* [622](https://github.com/nunit/nunit3-vs-adapter/issues/622) An exception occurred while invoking executor 'executor://nunit3testexecutor/': Incorrect format for TestCaseFilter Error: Missing ')' +* [622](https://github.com/nunit/nunit3-vs-adapter/issues/622) An exception occurred while invoking executor + 'executor://nunit3testexecutor/': Incorrect format for TestCaseFilter Error: Missing ')' * [549](https://github.com/nunit/nunit3-vs-adapter/issues/549) Invalid characters in test name breaks test runner -* [607](https://github.com/nunit/nunit3-vs-adapter/issues/607) VS Test Explorer does not show results for test cases that have custom names +* [607](https://github.com/nunit/nunit3-vs-adapter/issues/607) VS Test Explorer does not show results for test cases + that have custom names * [613](https://github.com/nunit/nunit3-vs-adapter/issues/613) TestCaseSource tests get wrongly displayed -* [672](https://github.com/nunit/nunit3-vs-adapter/issues/672) VS Test Explorer fails to run tests with test cases mocked with NSubstitute -* [644](https://github.com/nunit/nunit3-vs-adapter/issues/644) Test Explorer shows excess class name for tests with multiple TestCaseAttribute -* [615](https://github.com/nunit/nunit3-vs-adapter/issues/515) Dynamic TestCaseSource from reflection are not listed as sub-tests of the test method +* [672](https://github.com/nunit/nunit3-vs-adapter/issues/672) VS Test Explorer fails to run tests with test cases + mocked with NSubstitute +* [644](https://github.com/nunit/nunit3-vs-adapter/issues/644) Test Explorer shows excess class name for tests with + multiple TestCaseAttribute +* [615](https://github.com/nunit/nunit3-vs-adapter/issues/515) Dynamic TestCaseSource from reflection are not listed as + sub-tests of the test method -**The following are resolved (fully or partially) by [Pull Request #669](https://github.com/nunit/nunit3-vs-adapter/pull/669)** +**The following are resolved (fully or partially) by [Pull Request +669](https://github.com/nunit/nunit3-vs-adapter/pull/669)** * [655](https://github.com/nunit/nunit3-vs-adapter/issues/655) How to run parameterized NUnit tests on .NET Core? -* [425](https://github.com/nunit/nunit3-vs-adapter/issues/425) Partly resolved using NUnit Test Selection Language. Run only specific tests when using dotnet test? +* [425](https://github.com/nunit/nunit3-vs-adapter/issues/425) Partly resolved using NUnit Test Selection Language. Run + only specific tests when using dotnet test? ### The following is also resolved, but can't repro the original @@ -127,36 +178,49 @@ This release has three major changes. ### Other resolved issues -* [679](https://github.com/nunit/nunit3-vs-adapter/issues/679) Build.cake does not work in a pure visual studio preview installation. Fixed by [PR #680](https://github.com/nunit/nunit3-vs-adapter/pull/680) by [Ove Bastiansen](https://github.com/ovebastiansen) +* [679](https://github.com/nunit/nunit3-vs-adapter/issues/679) Build.cake does not work in a pure visual studio preview + installation. Fixed by [PR #680](https://github.com/nunit/nunit3-vs-adapter/pull/680) by [Ove + Bastiansen](https://github.com/ovebastiansen) ----- ## NUnit3 Test Adapter for Visual Studio - Version 3.15.1 - August 30, 2019 -This is a hotfix release due to some issues with special cases in NUnit, causing the tests to not run. -The major difference is that this release makes PreFiltering which was introduced in 3.15, optional - and default off. It can be enabled by setting PreFilter to true in a runsettings file. +This is a hotfix release due to some issues with special cases in NUnit, causing the tests to not run. The major +difference is that this release makes PreFiltering which was introduced in 3.15, optional - and default off. It can be +enabled by setting PreFilter to true in a runsettings file. ### Resolved Issues -* [651](https://github.com/nunit/nunit3-vs-adapter/issues/651) Add feature flag to enable/disable pre-filtering. This one contains the links to the issues below: +* [651](https://github.com/nunit/nunit3-vs-adapter/issues/651) Add feature flag to enable/disable pre-filtering. This + one contains the links to the issues below: -* [648](https://github.com/nunit/nunit3-vs-adapter/issues/648) NUnit3TestAdapter 3.15.0 fails to run test: "NUnit failed to load" (when using NUnit framework less than version 3.11) -* [649](https://github.com/nunit/nunit3-vs-adapter/issues/649) NUnit3TestAdapter 3.15 OneTimeSetUp not working anymore (When a SetupFixture is being used) -* [650](https://github.com/nunit/nunit3-vs-adapter/issues/650) NUnit3TestAdapter 3.15 not running tests with custom TestCaseSource (when using SetName instead of SetArgDisplayNames) +* [648](https://github.com/nunit/nunit3-vs-adapter/issues/648) NUnit3TestAdapter 3.15.0 fails to run test: "NUnit failed + to load" (when using NUnit framework less than version 3.11) +* [649](https://github.com/nunit/nunit3-vs-adapter/issues/649) NUnit3TestAdapter 3.15 OneTimeSetUp not working anymore + (When a SetupFixture is being used) +* [650](https://github.com/nunit/nunit3-vs-adapter/issues/650) NUnit3TestAdapter 3.15 not running tests with custom + TestCaseSource (when using SetName instead of SetArgDisplayNames) ----- ## NUnit3 Test Adapter for Visual Studio - Version 3.15 - August 23, 2019 -This release is a major performance improvement release. When used from Visual Studio, and used with a selection of tests, it will significantly speed up the discovery of those. Note that discovery is also a part of the execution, so you will also see the performance improvement for execution. It will be mostly noticeable when you have a large set of tests. +This release is a major performance improvement release. When used from Visual Studio, and used with a selection of +tests, it will significantly speed up the discovery of those. Note that discovery is also a part of the execution, so +you will also see the performance improvement for execution. It will be mostly noticeable when you have a large set of +tests. ### Features and Enhancements -* [529](https://github.com/nunit/nunit3-vs-adapter/issues/529) Use framework prefilter for massive perf improvement when running fraction of tests. Thanks to [MatthewBeardmore](https://github.com/MatthewBeardmore) for the [Pull request](https://github.com/nunit/nunit3-vs-adapter/pull/553) and patience +* [529](https://github.com/nunit/nunit3-vs-adapter/issues/529) Use framework prefilter for massive perf improvement + when running fraction of tests. Thanks to [MatthewBeardmore](https://github.com/MatthewBeardmore) for the [Pull + request](https://github.com/nunit/nunit3-vs-adapter/pull/553) and patience ### Resolved Issues -* [645](https://github.com/nunit/nunit3-vs-adapter/issues/645) NUnit3TestAdapter 3.14.0 includes NUnit3.TestAdapter.dll versioned 3.13. Version number of dll corrected to match package version 3.15 +* [645](https://github.com/nunit/nunit3-vs-adapter/issues/645) NUnit3TestAdapter 3.14.0 includes NUnit3.TestAdapter.dll + versioned 3.13. Version number of dll corrected to match package version 3.15 * [580](https://github.com/nunit/nunit3-vs-adapter/issues/580) Fix licenseUrl in nuspec, will be deprecated ----- @@ -165,16 +229,22 @@ This release is a major performance improvement release. When used from Visual ### Features and Enhancements -* [609](https://github.com/nunit/nunit3-vs-adapter/issues/609) Request to change working directory from Windows/System32 to another directory -and - [303](https://github.com/nunit/nunit3-vs-adapter/issues/303) Directory.GetCurrentDirectory is C:\WINDOWS\system32 for NUnit3TestAdapter. If your current directory points to either Windows directory or the Program Files folders, it will be redirected to your temp folder. -* [621](https://github.com/nunit/nunit3-vs-adapter/issues/621) TestContext.Progress output. It will only go to the console, not the test output. -* [222](https://github.com/nunit/nunit3-vs-adapter/issues/222) NUnit3TestAdapter errors when running xUnit tests. Thanks to [nvborisenko](https://github.com/nvborisenko) for the [Pull Request](https://github.com/nunit/nunit3-vs-adapter/pull/624) +* [609](https://github.com/nunit/nunit3-vs-adapter/issues/609) Request to change working directory from Windows/System32 +to another directory and [303](https://github.com/nunit/nunit3-vs-adapter/issues/303) Directory.GetCurrentDirectory is + C:\WINDOWS\system32 for NUnit3TestAdapter. If your current directory points to either Windows directory or the + Program Files folders, it will be redirected to your temp folder. +* [621](https://github.com/nunit/nunit3-vs-adapter/issues/621) TestContext.Progress output. It will only go to the + console, not the test output. +* [222](https://github.com/nunit/nunit3-vs-adapter/issues/222) NUnit3TestAdapter errors when running xUnit tests. Thanks + to [nvborisenko](https://github.com/nvborisenko) for the [Pull + Request](https://github.com/nunit/nunit3-vs-adapter/pull/624) ### Resolved Issues * [629](https://github.com/nunit/nunit3-vs-adapter/issues/629) NUnit3TestAdapter errors when running xUnit tests -* [630](https://github.com/nunit/nunit3-vs-adapter/issues/630) Assert.Multiple produces new tests in the report if inner assertions fail. Thanks again to [nvborisenko](https://github.com/nvborisenko) for the [Pull Request](https://github.com/nunit/nunit3-vs-adapter/pull/631) +* [630](https://github.com/nunit/nunit3-vs-adapter/issues/630) Assert.Multiple produces new tests in the report if inner + assertions fail. Thanks again to [nvborisenko](https://github.com/nvborisenko) for the [Pull + Request](https://github.com/nunit/nunit3-vs-adapter/pull/631) ### Comments @@ -184,29 +254,48 @@ This version also includes the latest version 3.10 of the NUnit.Engine.dll ## NUnit3 Test Adapter for Visual Studio - Version 3.13 - February 20, 2019 -This release focuses on producing NUnit test result XML which can be useful when you need reports using tools that support the NUnit format. This can be enabled using [a new setting](xref:tipsandtricks#testoutputxml) in the [runsettings file](https://marketplace.visualstudio.com/items?itemName=OsirisTerje.Runsettings-19151). +This release focuses on producing NUnit test result XML which can be useful when you need reports using tools that +support the NUnit format. This can be enabled using [a new setting](xref:tipsandtricks#testoutputxml) in the +[runsettings file](https://marketplace.visualstudio.com/items?itemName=OsirisTerje.Runsettings-19151). -The VSIX is also made compatible with the upcoming VS 2019. Please note support for the VSIX is being deprecated in Visual Studio, and we strongly recommend you to change your test projects to use the [NuGet adapter version](https://www.nuget.org/packages/NUnit3TestAdapter/). +The VSIX is also made compatible with the upcoming VS 2019. Please note support for the VSIX is being deprecated in +Visual Studio, and we strongly recommend you to change your test projects to use the [NuGet adapter +version](https://www.nuget.org/packages/NUnit3TestAdapter/). -The [NUnit internal properties](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Internal/PropertyNames.cs) have been "over-populating" in the Test Explorer. These are now filtered out, although you may still see these when you have [Source Based Discovery (SBD)](https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2017/test/test-explorer-faq?view=vs-2017) turned on (which is the default in VS). Once you have run, they will be gone. We expect this part of the issue (SBD) to be fixed in VS. +The [NUnit internal +properties](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Internal/PropertyNames.cs) have been +"over-populating" in the Test Explorer. These are now filtered out, although you may still see these when you have +[Source Based Discovery +(SBD)](https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2017/test/test-explorer-faq?view=vs-2017) +turned on (which is the default in VS). Once you have run, they will be gone. We expect this part of the issue (SBD) to +be fixed in VS. -If you still want to see the properties, you can enable that again setting a runsettings property `ShowInternalProperties` to true. +If you still want to see the properties, you can enable that again setting a runsettings property +`ShowInternalProperties` to true. ### Enhancements -* [323](https://github.com/nunit/nunit3-vs-adapter/issues/323) Add support for producing XML test results in NUnit format -* [474](https://github.com/nunit/nunit3-vs-adapter/issues/474) Skip surfacing certain properties as UI groupings (Internal NUnit properties are no longer visible in Test Explorer) +* [323](https://github.com/nunit/nunit3-vs-adapter/issues/323) Add support for producing XML test results in NUnit + format +* [474](https://github.com/nunit/nunit3-vs-adapter/issues/474) Skip surfacing certain properties as UI groupings + (Internal NUnit properties are no longer visible in Test Explorer) * [590](https://github.com/nunit/nunit3-vs-adapter/issues/590) Support for Visual Studio 2019 (VSIX) ### Resolved Issues -* [302](https://github.com/nunit/nunit3-vs-adapter/issues/302) BadImageFormatException building solution with unmanaged projects) Extra fix for this, see [PR 592](https://github.com/nunit/nunit3-vs-adapter/pull/592) Issue302 native execution in execution. Thanks to [Oski Kervinen](https://github.com/OskiKervinen-MF) for fixing this. -* [596](https://github.com/nunit/nunit3-vs-adapter/issues/596) TestOutputXml should handle relative paths relative to the `Workfolder` -* [600](https://github.com/nunit/nunit3-vs-adapter/issues/600) TestOutputXml setting ignored on netcore2.1, works on net461 +* [302](https://github.com/nunit/nunit3-vs-adapter/issues/302) BadImageFormatException building solution with unmanaged + projects) Extra fix for this, see [PR 592](https://github.com/nunit/nunit3-vs-adapter/pull/592) Issue302 native + execution in execution. Thanks to [Oski Kervinen](https://github.com/OskiKervinen-MF) for fixing this. +* [596](https://github.com/nunit/nunit3-vs-adapter/issues/596) TestOutputXml should handle relative paths relative to + the `Workfolder` +* [600](https://github.com/nunit/nunit3-vs-adapter/issues/600) TestOutputXml setting ignored on netcore2.1, works on + net461 ### Other fixes -* [599](https://github.com/nunit/nunit3-vs-adapter/issues/599) Url in the repo header pointing to [nunit.org](https://nunit.org) changed to https, also some other similar changes other places. Thanks to [Julian Verdurmen](https://github.com/304NotModified) for fixing these. +* [599](https://github.com/nunit/nunit3-vs-adapter/issues/599) Url in the repo header pointing to + [nunit.org](https://nunit.org) changed to https, also some other similar changes other places. Thanks to [Julian + Verdurmen](https://github.com/304NotModified) for fixing these. ----- @@ -214,8 +303,10 @@ If you still want to see the properties, you can enable that again setting a run ### Enhancements -* [215](https://github.com/nunit/nunit3-vs-adapter/issues/215) Generate NUnit xml file of test results, specified in .runsettings file for reporting -* [573](https://github.com/nunit/nunit3-vs-adapter/issues/573) NUnit3TestDiscoverer Could not load file or assembly 'nunit.engine' +* [215](https://github.com/nunit/nunit3-vs-adapter/issues/215) Generate NUnit xml file of test results, specified in + .runsettings file for reporting +* [573](https://github.com/nunit/nunit3-vs-adapter/issues/573) NUnit3TestDiscoverer Could not load file or assembly + 'nunit.engine' ----- @@ -225,11 +316,13 @@ This is a yet another hotfix release to fix the missing categories issue. ### Resolved Issues -* [568](https://github.com/nunit/nunit3-vs-adapter/issues/568) NUnit3TestAdapter 3.11.1 TestCategory from VSTest no longer working (No tests selected) +* [568](https://github.com/nunit/nunit3-vs-adapter/issues/568) NUnit3TestAdapter 3.11.1 TestCategory from VSTest no + longer working (No tests selected) ### Reopened issues -This issue was fixed, with a workaround, in 3.11 but had unforeseen consequences, and has been reopened as of this release +This issue was fixed, with a workaround, in 3.11 but had unforeseen consequences, and has been reopened as of this +release * [506](https://github.com/nunit/nunit3-vs-adapter/issues/506) Test categories aren't propagated to vstest trx logs @@ -243,7 +336,8 @@ This is a hotfix release to fix the duplicated traits issue. ### Resolved Issues -* [559](https://github.com/nunit/nunit3-vs-adapter/issues/559) Duplicating tags in Test Explorer when using NUnit3TestAdapter 3.11.0 +* [559](https://github.com/nunit/nunit3-vs-adapter/issues/559) Duplicating tags in Test Explorer when using + NUnit3TestAdapter 3.11.0 * [561](https://github.com/nunit/nunit3-vs-adapter/issues/561) Test task aborted when using TestCategory filters ----- @@ -252,9 +346,14 @@ This is a hotfix release to fix the duplicated traits issue. ### Features -* [PR 500](https://github.com/nunit/nunit3-vs-adapter/pull/500) NUnit3VsAdapter to support managed sources only based on [RFC](https://github.com/Microsoft/vstest-docs/blob/main/RFCs/0020-Improving-Logic-To-Pass-Sources-To-Adapters.md) (Thanks to [mayankbansal018](https://github.com/mayankbansal018) for this PR) +* [PR 500](https://github.com/nunit/nunit3-vs-adapter/pull/500) NUnit3VsAdapter to support managed sources only based on + [RFC](https://github.com/Microsoft/vstest-docs/blob/main/RFCs/0020-Improving-Logic-To-Pass-Sources-To-Adapters.md) + (Thanks to [mayankbansal018](https://github.com/mayankbansal018) for this PR) -* [543](https://github.com/nunit/nunit3-vs-adapter/issues/543) Adapter should pass `Error` and `Progress` messages to vstest engine as well as stdOut messages (Thanks to [NikolayPianikov](https://github.com/NikolayPianikov) for [PR 544](https://github.com/nunit/nunit3-vs-adapter/pull/544)). Also fixes this [TeamCity issue](https://youtrack.jetbrains.com/issue/TW-55900) +* [543](https://github.com/nunit/nunit3-vs-adapter/issues/543) Adapter should pass `Error` and `Progress` messages to + vstest engine as well as stdOut messages (Thanks to [NikolayPianikov](https://github.com/NikolayPianikov) for [PR + 544](https://github.com/nunit/nunit3-vs-adapter/pull/544)). Also fixes this [TeamCity + issue](https://youtrack.jetbrains.com/issue/TW-55900) * Mono.Cecil is now embedded with the adapter, so user dependencies are no longer overwritten. @@ -264,26 +363,33 @@ This is a hotfix release to fix the duplicated traits issue. ### Resolved Issues -* [426](https://github.com/nunit/nunit3-vs-adapter/issues/426) -Exception thrown while loading tests if In-Proc VSTest DataCollector is used (Thanks to [drognanar](https://github.com/drognanar) for [PR 510](https://github.com/nunit/nunit3-vs-adapter/pull/510) ) +* [426](https://github.com/nunit/nunit3-vs-adapter/issues/426) Exception thrown while loading tests if In-Proc VSTest +DataCollector is used (Thanks to [drognanar](https://github.com/drognanar) for [PR +510](https://github.com/nunit/nunit3-vs-adapter/pull/510) ) -* [490](https://github.com/nunit/nunit3-vs-adapter/issues/490) Fix Causes Build Error (Somewhat Indirectly) by published pdb files from [Issue 461](https://github.com/nunit/nunit3-vs-adapter/issues/461) +* [490](https://github.com/nunit/nunit3-vs-adapter/issues/490) Fix Causes Build Error (Somewhat Indirectly) by published + pdb files from [Issue 461](https://github.com/nunit/nunit3-vs-adapter/issues/461) -* [494](https://github.com/nunit/nunit3-vs-adapter/issues/494) TestContext.AddTestAttachment does not work on Linux environment with specified dotnet logger (Thanks to [Kira-Lappo](https://github.com/Kira-Lappo) for [PR 527](https://github.com/nunit/nunit3-vs-adapter/pull/527)) +* [494](https://github.com/nunit/nunit3-vs-adapter/issues/494) TestContext.AddTestAttachment does not work on Linux + environment with specified dotnet logger (Thanks to [Kira-Lappo](https://github.com/Kira-Lappo) for [PR + 527](https://github.com/nunit/nunit3-vs-adapter/pull/527)) -* [495](https://github.com/nunit/nunit3-vs-adapter/issues/495) Category as filter not working in single agent flow in vstest task +* [495](https://github.com/nunit/nunit3-vs-adapter/issues/495) Category as filter not working in single agent flow in + vstest task * [506](https://github.com/nunit/nunit3-vs-adapter/issues/506) Test categories aren't propagated to vstest trx logs * [516](https://github.com/nunit/nunit3-vs-adapter/issues/516) ArgumentException when whitespace sent to logger -* [538](https://github.com/nunit/nunit3-vs-adapter/issues/538) NuGet Package : Add repository metadata (Thanks to [MaximRouiller](https://github.com/MaximRouiller) for [PR 539](https://github.com/nunit/nunit3-vs-adapter/pull/539)) +* [538](https://github.com/nunit/nunit3-vs-adapter/issues/538) NuGet Package : Add repository metadata (Thanks to + [MaximRouiller](https://github.com/MaximRouiller) for [PR 539](https://github.com/nunit/nunit3-vs-adapter/pull/539)) * [540](https://github.com/nunit/nunit3-vs-adapter/issues/540) Missing null check before runner dispose ### Notes -* [518](https://github.com/nunit/nunit3-vs-adapter/issues/518) NUnit VSIX test adapters deprecation notice added. NUnit will still deliver a vsix for this version. +* [518](https://github.com/nunit/nunit3-vs-adapter/issues/518) NUnit VSIX test adapters deprecation notice added. NUnit + will still deliver a vsix for this version. ----- @@ -291,17 +397,24 @@ Exception thrown while loading tests if In-Proc VSTest DataCollector is used (Th ### Features -* [461](https://github.com/nunit/nunit3-vs-adapter/issues/461) Publish symbols with the adapter for debugging into the adapter and NUnit +* [461](https://github.com/nunit/nunit3-vs-adapter/issues/461) Publish symbols with the adapter for debugging into the + adapter and NUnit ### Resolved Issues -* [47](https://github.com/nunit/nunit3-vs-adapter/issues/47) Adapter runs explicit tests when TFS TestCaseFilter is used -* [296](https://github.com/nunit/nunit3-vs-adapter/issues/296) Mono.Cecil causes OutOfMemoryException with new .csproj PDBs +* [47](https://github.com/nunit/nunit3-vs-adapter/issues/47) Adapter runs explicit tests when TFS TestCaseFilter is + used +* [296](https://github.com/nunit/nunit3-vs-adapter/issues/296) Mono.Cecil causes OutOfMemoryException with new .csproj + PDBs * [310](https://github.com/nunit/nunit3-vs-adapter/issues/310) Consistent Category Display in Test Explorer Window -* [365](https://github.com/nunit/nunit3-vs-adapter/issues/365) An exception occurred while invoking executor: Could not load file or assembly System.Runtime.InteropServices.RuntimeInformation (Thanks to [halex2005](https://github.com/halex2005) for [PR 418](https://github.com/nunit/nunit3-vs-adapter/pull/418)) -* [419](https://github.com/nunit/nunit3-vs-adapter/issues/419) Test result is Skipped when an exception has been thrown and the only warning is in TearDown +* [365](https://github.com/nunit/nunit3-vs-adapter/issues/365) An exception occurred while invoking executor: Could not + load file or assembly System.Runtime.InteropServices.RuntimeInformation (Thanks to + [halex2005](https://github.com/halex2005) for [PR 418](https://github.com/nunit/nunit3-vs-adapter/pull/418)) +* [419](https://github.com/nunit/nunit3-vs-adapter/issues/419) Test result is Skipped when an exception has been thrown + and the only warning is in TearDown * [444](https://github.com/nunit/nunit3-vs-adapter/issues/444) Dump file is not created when the test crashes -* [452](https://github.com/nunit/nunit3-vs-adapter/issues/452) Adapter does not seem to respect any TestCategory filtering +* [452](https://github.com/nunit/nunit3-vs-adapter/issues/452) Adapter does not seem to respect any TestCategory + filtering * [460](https://github.com/nunit/nunit3-vs-adapter/issues/460) Failure to load dependency assembly causes hang Also see [Release Readiness Review](https://github.com/nunit/nunit3-vs-adapter/issues/472) @@ -310,7 +423,8 @@ Also see [Release Readiness Review](https://github.com/nunit/nunit3-vs-adapter/i Special thanks to : [Joseph Musser](https://github.com/jnm2) for awesome work on this release, -and to [Loren Halvorsen](https://www.linkedin.com/in/lorenhalvorson/) for the workaround for VSTest [issue 261](https://github.com/nunit/nunit3-vs-adapter/issues/261#issuecomment-259970442). +and to [Loren Halvorsen](https://www.linkedin.com/in/lorenhalvorson/) for the workaround for VSTest [issue +261](https://github.com/nunit/nunit3-vs-adapter/issues/261#issuecomment-259970442). ----- @@ -318,19 +432,27 @@ and to [Loren Halvorsen](https://www.linkedin.com/in/lorenhalvorson/) for the wo ### Change in supported versions -This version supports Visual Studio from version 2012, Update 1 and upwards, and all subsequent versions in 2013, 2015 and 2017. Visual Studio 2012 RTM is then no longer supported. +This version supports Visual Studio from version 2012, Update 1 and upwards, and all subsequent versions in 2013, 2015 +and 2017. Visual Studio 2012 RTM is then no longer supported. ### Features -* [390](https://github.com/nunit/nunit3-vs-adapter/issues/390) Pass DisableAppDomain and DisableParallelization settings to the Engine -* [392](https://github.com/nunit/nunit3-vs-adapter/issues/392) Improve performance of discovery (Thanks to [Navin (Microsoft)](https://github.com/navin22) for [PR 393](https://github.com/nunit/nunit3-vs-adapter/pull/393), [PR 406](https://github.com/nunit/nunit3-vs-adapter/pull/406) ) +* [390](https://github.com/nunit/nunit3-vs-adapter/issues/390) Pass DisableAppDomain and DisableParallelization settings + to the Engine +* [392](https://github.com/nunit/nunit3-vs-adapter/issues/392) Improve performance of discovery (Thanks to [Navin + (Microsoft)](https://github.com/navin22) for [PR 393](https://github.com/nunit/nunit3-vs-adapter/pull/393), [PR + 406](https://github.com/nunit/nunit3-vs-adapter/pull/406) ) * [394](https://github.com/nunit/nunit3-vs-adapter/issues/394) The adapter tests are updated to use NUnit 3.8.1 ### Resolved Issues -* [372](https://github.com/nunit/nunit3-vs-adapter/issues/372) netcoreapp + CultureInfo.CurrentCulture = bad time (Thanks to [Aaron Housh (Dispersia)](https://github.com/Dispersia) for [PR 380](https://github.com/nunit/nunit3-vs-adapter/pull/380) ) -* [386](https://github.com/nunit/nunit3-vs-adapter/issues/386) DateTime.Parse issue during test discovery with certain cultures (Also fixed by [PR 380](https://github.com/nunit/nunit3-vs-adapter/pull/380) ) -* [302](https://github.com/nunit/nunit3-vs-adapter/issues/302) BadImageFormatException building solution with unmanaged projects +* [372](https://github.com/nunit/nunit3-vs-adapter/issues/372) netcoreapp + CultureInfo.CurrentCulture = bad time + (Thanks to [Aaron Housh (Dispersia)](https://github.com/Dispersia) for [PR + 380](https://github.com/nunit/nunit3-vs-adapter/pull/380) ) +* [386](https://github.com/nunit/nunit3-vs-adapter/issues/386) DateTime.Parse issue during test discovery with certain + cultures (Also fixed by [PR 380](https://github.com/nunit/nunit3-vs-adapter/pull/380) ) +* [302](https://github.com/nunit/nunit3-vs-adapter/issues/302) BadImageFormatException building solution with unmanaged + projects ----- @@ -338,18 +460,28 @@ This version supports Visual Studio from version 2012, Update 1 and upwards, and ### Features -* The adapter now support running .net core projects. See [this post](https://alteridem.net/2017/05/04/test-net-core-nunit-vs2017/) for details. Note: Only supported by the nuget adapter, not the vsix. -* The adapter now uses version 3.7 of the engine to run tests ([360](https://github.com/nunit/nunit3-vs-adapter/issues/360)) +* The adapter now support running .net core projects. See [this + post](https://alteridem.net/2017/05/04/test-net-core-nunit-vs2017/) for details. Note: Only supported by the nuget + adapter, not the vsix. +* The adapter now uses version 3.7 of the engine to run tests + ([360](https://github.com/nunit/nunit3-vs-adapter/issues/360)) * Attachments can be added to tests ([358](https://github.com/nunit/nunit3-vs-adapter/issues/358)) -* Prepared for new upcoming Test Explorer functionality, as documented in this [RFC](https://github.com/Microsoft/vstest-docs/blob/main/RFCs/0010-Source-Information-For-Discovered-Tests.md) ([351](https://github.com/nunit/nunit3-vs-adapter/issues/351)) +* Prepared for new upcoming Test Explorer functionality, as documented in this + [RFC](https://github.com/Microsoft/vstest-docs/blob/main/RFCs/0010-Source-Information-For-Discovered-Tests.md) + ([351](https://github.com/nunit/nunit3-vs-adapter/issues/351)) ### Resolved Issues -* [298](https://github.com/nunit/nunit3-vs-adapter/issues/298) $RANDOM_SEED$ is appearing in non-test project build output -* [259](https://github.com/nunit/nunit3-vs-adapter/issues/259) An exception occurred while invoking executor `'executor://nunit3testexecutor/'` -* [314](https://github.com/nunit/nunit3-vs-adapter/issues/314) Any TestFixture deriving from a base-class which defines unit-tests will fail when the base-class is from another class-library -* [231](https://github.com/nunit/nunit3-vs-adapter/issues/231) Improved message on failed loading. See also [PR 309](https://github.com/nunit/nunit3-vs-adapter/pull/309) -* [338](https://github.com/nunit/nunit3-vs-adapter/issues/338) Unhandled Exception when running through `vstest.console.exe /listtests` +* [298](https://github.com/nunit/nunit3-vs-adapter/issues/298) $RANDOM_SEED$ is appearing in non-test project build + output +* [259](https://github.com/nunit/nunit3-vs-adapter/issues/259) An exception occurred while invoking executor + `'executor://nunit3testexecutor/'` +* [314](https://github.com/nunit/nunit3-vs-adapter/issues/314) Any TestFixture deriving from a base-class which defines + unit-tests will fail when the base-class is from another class-library +* [231](https://github.com/nunit/nunit3-vs-adapter/issues/231) Improved message on failed loading. See also [PR + 309](https://github.com/nunit/nunit3-vs-adapter/pull/309) +* [338](https://github.com/nunit/nunit3-vs-adapter/issues/338) Unhandled Exception when running through + `vstest.console.exe /listtests` ----- @@ -377,7 +509,8 @@ This version supports Visual Studio from version 2012, Update 1 and upwards, and ## NUnit3 Test Adapter for Visual Studio - Version 3.6.1 - December 5, 2016 > [!NOTE] -> This was a hotfix release of the vsix package only, fixing an issue that prevented it from installing under VS2012 and 2013. +> This was a hotfix release of the vsix package only, fixing an issue that prevented it from installing under +> VS2012 and 2013. ### Resolved Issues @@ -438,7 +571,8 @@ This version supports Visual Studio from version 2012, Update 1 and upwards, and * The adapter now uses the NUnit 3.4.1 TestEngine. * TestRunParameters may now be provided in the `.runsettings` file. -* Immediate text output from tests now displays in the Output window. This includes any output produced through Console.Error, TestContext.Error or TestContext.Progress. +* Immediate text output from tests now displays in the Output window. This includes any output produced through + Console.Error, TestContext.Error or TestContext.Progress. ### Resolved Issues @@ -474,9 +608,11 @@ This version supports Visual Studio from version 2012, Update 1 and upwards, and ### Features -* This is the final production release of the 3.0 adapter. It continues to use the 3.0.1 release of the NUnit TestEngine. +* This is the final production release of the 3.0 adapter. It continues to use the 3.0.1 release of the NUnit + TestEngine. -* The adapter now uses a `.runsettings` file for all optional settings. Registry entries used in the CTP releases are no longer used. +* The adapter now uses a `.runsettings` file for all optional settings. Registry entries used in the CTP releases are no + longer used. ### Resolved Issues @@ -576,11 +712,13 @@ This version supports Visual Studio from version 2012, Update 1 and upwards, and ### Features -* This release continues to use the NUnit 3.0 beta-2 engine but is nevertheless able to run tests that reference NUnit 3.0 beta-3 framework. +* This release continues to use the NUnit 3.0 beta-2 engine but is nevertheless able to run tests that reference NUnit + 3.0 beta-3 framework. * When a debugger is attached, only a single worker thread is used to run tests. -* The adapter now compensates for the fact that NUnit does not send results for tests that were skipped due to an attribute on the fixture by generating those results itself. +* The adapter now compensates for the fact that NUnit does not send results for tests that were skipped due to an + attribute on the fixture by generating those results itself. ### Resolved Issues @@ -607,9 +745,11 @@ This release was issued to correct a problem with locking of assemblies in ctp-2 ### Features -* The adapter now uses the new nunit.core.engine to load and run tests, eliminating ad-hoc code that worked directly with the framework. This will allow us to much greater flexibility in the future. +* The adapter now uses the new nunit.core.engine to load and run tests, eliminating ad-hoc code that worked directly + with the framework. This will allow us to much greater flexibility in the future. -* The adapter has been upgraded to use the beta-2 release of the NUnit core engine. Because the API has changed from beta-1, the adapter can only run tests built against the beta-2 release of NUnit. +* The adapter has been upgraded to use the beta-2 release of the NUnit core engine. Because the API has changed from + beta-1, the adapter can only run tests built against the beta-2 release of NUnit. ### Resolved Issues @@ -625,7 +765,9 @@ This release was issued to correct a problem with locking of assemblies in ctp-2 ### Features -* Initial release of the test adapter using NUnit 3.0. Note that the adapter may **not** be used to run tests written against earlier versions of NUnit. The original adapter is still available for that purpose and both adapters may be installed if necessary. +* Initial release of the test adapter using NUnit 3.0. Note that the adapter may **not** be used to run tests written + against earlier versions of NUnit. The original adapter is still available for that purpose and both adapters may be + installed if necessary. ----- @@ -786,7 +928,8 @@ This release was issued to correct a problem with locking of assemblies in ctp-2 ### Features * Works with Visual Studio 2012 RTM. Some features require the November CTP update. -* The adapter now uses NUnit 2.6.2. Among other things, this allows us to support async test methods. See the NUnit Release Notes for more info. +* The adapter now uses NUnit 2.6.2. Among other things, this allows us to support async test methods. See the NUnit + Release Notes for more info. * Source file and line number can now be found for test cases that have an alternate name set. * Console output from tests is now displayed in the Visual Studio Output window. * TestFixtureSetUp and TestFixtureTearDown errors are now displayed in the Output window. diff --git a/docs/articles/vs-test-adapter/AdapterV4-Release-Notes.md b/docs/articles/vs-test-adapter/AdapterV4-Release-Notes.md index ea6f4128b..cb4bfeb87 100644 --- a/docs/articles/vs-test-adapter/AdapterV4-Release-Notes.md +++ b/docs/articles/vs-test-adapter/AdapterV4-Release-Notes.md @@ -2,25 +2,33 @@ ## NUnit3 Test Adapter for Visual Studio and Dotnet - Version 4.5.0 - May 30, 2023 -This is a version supporting the upcoming NUnit version 4. It uses a released version of the NUnit.Engine, version 3.15.4. +This is a version supporting the upcoming NUnit version 4. It uses a released version of the NUnit.Engine, version +3.15.4. * [1080](https://github.com/nunit/nunit3-vs-adapter/issues/1080) Allow the adapter to be used with NUnit version 4 * [1100](https://github.com/nunit/nunit3-vs-adapter/issues/1100) Allow to debug parallel tests ## NUnit3 Test Adapter for Visual Studio - Version 4.4.2 - Mar 1, 2023 -This is a hotfix for the 4.4.0 version. The 4.4.0 included the NUnit.Engine 3.16.3, which uses an external package for loading assemblies. It turns out the engine fails for certain types of loading, in particular when an assembly is loaded by reflection. +This is a hotfix for the 4.4.0 version. The 4.4.0 included the NUnit.Engine 3.16.3, which uses an external package for +loading assemblies. It turns out the engine fails for certain types of loading, in particular when an assembly is +loaded by reflection. -In order to fix this, this version have reverted to a version of the NUnit.Engine based on 3.15.2, which does not have this way of loading assemblies. The included Engine is not available as a separate package, but if you use anything that needs the engine package (like the NUnit.Console), version 3.15.2 should work. +In order to fix this, this version have reverted to a version of the NUnit.Engine based on 3.15.2, which does not have +this way of loading assemblies. The included Engine is not available as a separate package, but if you use anything that +needs the engine package (like the NUnit.Console), version 3.15.2 should work. The embedded engine handles the .net 8 the same way as with the 4.4.0 adapter. The following issues, all related to the same problem, are fixed in this release: -* [1065](https://github.com/nunit/nunit3-vs-adapter/issues/1065) WebHostBuilder.ConfigureServices method not found when using version 4.4.0 +* [1065](https://github.com/nunit/nunit3-vs-adapter/issues/1065) WebHostBuilder.ConfigureServices method not found when + using version 4.4.0 * [1066](https://github.com/nunit/nunit3-vs-adapter/issues/1066) Breaking change for TestAssemblyLoadContext -* [1069](https://github.com/nunit/nunit3-vs-adapter/issues/1069) Any type loaded from assembly at runtime does not match compile-time type -* [1070](https://github.com/nunit/nunit3-vs-adapter/issues/1070) NUnit failed to load test assembly after upgrading from 4.3.1 to 4.4.0 +* [1069](https://github.com/nunit/nunit3-vs-adapter/issues/1069) Any type loaded from assembly at runtime does not match + compile-time type +* [1070](https://github.com/nunit/nunit3-vs-adapter/issues/1070) NUnit failed to load test assembly after upgrading from + 4.3.1 to 4.4.0 Thanks to everyone that reported in, and special thanks to everyone that provided repro solutions for the problem. @@ -28,59 +36,84 @@ Thanks to everyone that reported in, and special thanks to everyone that provide **:warning: This version has been unlisted on NuGet, please use version 4.4.2 instead.** -The main focus is the support for .Net 8. This version of the adapter will accept any higher version of the .net, also future higher versions than .net 8. +The main focus is the support for .Net 8. This version of the adapter will accept any higher version of the .net, also +future higher versions than .net 8. The following issues are fixed in this release: -* [1049](https://github.com/nunit/nunit3-vs-adapter/issues/1049) .Net Framework tests fails when .Net 8 is present on system +* [1049](https://github.com/nunit/nunit3-vs-adapter/issues/1049) .Net Framework tests fails when .Net 8 is present on + system -* [1037](https://github.com/nunit/nunit3-vs-adapter/issues/1037) TestContext.Progress shows up as Warning in TFS/Azure Dev Ops. Thanks to [mharwig](https://github.com/mharwig) for the [PR](https://github.com/nunit/nunit3-vs-adapter/pull/1038). +* [1037](https://github.com/nunit/nunit3-vs-adapter/issues/1037) TestContext.Progress shows up as Warning in TFS/Azure + Dev Ops. Thanks to [mharwig](https://github.com/mharwig) for the + [PR](https://github.com/nunit/nunit3-vs-adapter/pull/1038). ### Beta release -A beta release, Version 4.4.0-beta.1, was released on Feb 23, 2023. There is no changes between this and the previous beta release, except for updates of packages for the test projects. +A beta release, Version 4.4.0-beta.1, was released on Feb 23, 2023. There is no changes between this and the previous +beta release, except for updates of packages for the test projects. ## NUnit3 Test Adapter for Visual Studio - Version 4.3.1 - Nov 19, 2022 This is a hotfix release for three major and critical problems: -1) .Net Framework (4.8 and lower) would crash due to InternalTracelog files trying to be written to the Program Files directory. +1) .Net Framework (4.8 and lower) would crash due to InternalTracelog files trying to be written to the Program Files + directory. 2) InternalTracelog files would appear in root of solution 3) TestOutputXml did not work correctly when specified -In order to get these fixed the support for netcore2.1 had to be dropped. This version is also now unsupported by Microsoft, so the adapter follows that. +In order to get these fixed the support for netcore2.1 had to be dropped. This version is also now unsupported by +Microsoft, so the adapter follows that. -* [987](https://github.com/nunit/nunit3-vs-adapter/issues/987) Regression on this issue due to the InternalTracelog files +* [987](https://github.com/nunit/nunit3-vs-adapter/issues/987) Regression on this issue due to the InternalTracelog + files * [1026](https://github.com/nunit/nunit3-vs-adapter/issues/1026) Current directory C:\WINDOWS\system32 again -* [1027](https://github.com/nunit/nunit3-vs-adapter/issues/1027) Test Explorer is finding tests, but not running them after upgrading to NUnit3TestAdapter v4.3.0 -* [1028](https://github.com/nunit/nunit3-vs-adapter/issues/1028) Test discovery emits zero length `internaltrace` log file per project -* [1030](https://github.com/nunit/nunit3-vs-adapter/issues/1030) Problem if OutputXmlFolderMode setting is not in .runsettings +* [1027](https://github.com/nunit/nunit3-vs-adapter/issues/1027) Test Explorer is finding tests, but not running them + after upgrading to NUnit3TestAdapter v4.3.0 +* [1028](https://github.com/nunit/nunit3-vs-adapter/issues/1028) Test discovery emits zero length `internaltrace` log + file per project +* [1030](https://github.com/nunit/nunit3-vs-adapter/issues/1030) Problem if OutputXmlFolderMode setting is not in + .runsettings * [1031](https://github.com/nunit/nunit3-vs-adapter/issues/1031) TestOutputXml regressions ### Credits -Thanks to [Jan Inge Dalsbø](https://github.com/janid1967), [Taylor Willis](https://github.com/Guitrum), [Kai Nadler](https://github.com/smkanadl), [Barnabas Lakner](https://github.com/barnabas90), [sandrohanea](https://github.com/sandrohanea), [Elliot Prior](https://github.com/Quogu), [Todd Ogin](https://github.com/ojintoad), [Evheniyrz](https://github.com/evheniyrz), [Manfred Brands](https://github.com/manfred-brands), [Boris Drajer](https://github.com/bdrajer), [Ken V](https://github.com/varnk), [Mike Vorhees](https://github.com/mrvoorhe) for all the help with reporting the issues, reproducing them, analysis and diagnostics, and confirming that 4.3.1 resolves the issues. Your help is really appreciated! +Thanks to [Jan Inge Dalsbø](https://github.com/janid1967), [Taylor Willis](https://github.com/Guitrum), [Kai +Nadler](https://github.com/smkanadl), [Barnabas Lakner](https://github.com/barnabas90), +[sandrohanea](https://github.com/sandrohanea), [Elliot Prior](https://github.com/Quogu), [Todd +Ogin](https://github.com/ojintoad), [Evheniyrz](https://github.com/evheniyrz), [Manfred +Brands](https://github.com/manfred-brands), [Boris Drajer](https://github.com/bdrajer), [Ken +V](https://github.com/varnk), [Mike Vorhees](https://github.com/mrvoorhe) for all the help with reporting the issues, +reproducing them, analysis and diagnostics, and confirming that 4.3.1 resolves the issues. Your help is really +appreciated! ## NUnit3 Test Adapter for Visual Studio - Version 4.3.0 - Oct 29, 2022 -This version is for support of the .net 7 framework. See an overview of [supported frameworks here](/articles/vs-test-adapter/Supported-Frameworks.html). +This version is for support of the .net 7 framework. See an overview of [supported frameworks +here](/articles/vs-test-adapter/Supported-Frameworks.html). -The support is due to the updated embedded [NUnit.Engine version 3.15.2](/articles/nunit-engine/release-notes.html#nunit-console--engine-3152---june-30-2022). +The support is due to the updated embedded [NUnit.Engine version +3.15.2](/articles/nunit-engine/release-notes.html#nunit-console--engine-3152---june-30-2022). * [987](https://github.com/nunit/nunit3-vs-adapter/issues/987) System.ArgumentException: Unknown framework version 7.0 Other bugs fixed: -* [990](https://github.com/nunit/nunit3-vs-adapter/issues/990) Missing output with failed test stack traces for Assert.Multiple -* [997](https://github.com/nunit/nunit3-vs-adapter/issues/997) TRX report file folder inconsistent with XML report folder using .runsettings file. Note that a new runsettings flag has been added for supporting this, see [OutputXmlFolderMode](/articles/vs-test-adapter/Tips-And-Tricks.html#OutputXmlFolderMode). +* [990](https://github.com/nunit/nunit3-vs-adapter/issues/990) Missing output with failed test stack traces for + Assert.Multiple +* [997](https://github.com/nunit/nunit3-vs-adapter/issues/997) TRX report file folder inconsistent with XML report + folder using .runsettings file. Note that a new runsettings flag has been added for supporting this, see + [OutputXmlFolderMode](/articles/vs-test-adapter/Tips-And-Tricks.html#OutputXmlFolderMode). ## NUnit3 Test Adapter for Visual Studio - Version 4.2.1 - Jan 21, 2022 This is a hotfix release for -* [941](https://github.com/nunit/nunit3-vs-adapter/issues/941) When running `dotnet test` with filter, all tests are run and all console output is logged. +* [941](https://github.com/nunit/nunit3-vs-adapter/issues/941) When running `dotnet test` with filter, all tests are run + and all console output is logged. -This fix applies to test projects where all tests are excluded by a test item filter. Previously, as of v4.2.0, all tests were unintentionally run. Note that this issue did not affect category filters. +This fix applies to test projects where all tests are excluded by a test item filter. Previously, as of v4.2.0, all +tests were unintentionally run. Note that this issue did not affect category filters. ## NUnit3 Test Adapter for Visual Studio - Version 4.2.0 - Dec 19, 2021 @@ -89,42 +122,57 @@ This is a bug fix release, with the following fixes: * [818](https://github.com/nunit/nunit3-vs-adapter/issues/818) Known Vulnerability in System.Xml.XPath.XmlDocument * [912](https://github.com/nunit/nunit3-vs-adapter/issues/912) Explicit runs when using NUnit-filters 'cat!=FOO' * [914](https://github.com/nunit/nunit3-vs-adapter/issues/914) AddTestAttachment does not work anymore in VS2022 -* [918](https://github.com/nunit/nunit3-vs-adapter/issues/918) New DiscoveryMode doesn't play nicely with TestFixtureSource - Missing GenericFixture +* [918](https://github.com/nunit/nunit3-vs-adapter/issues/918) New DiscoveryMode doesn't play nicely with + TestFixtureSource - Missing GenericFixture * [919](https://github.com/nunit/nunit3-vs-adapter/issues/919) VSTest test case filter does not work with parentheses -* [929](https://github.com/nunit/nunit3-vs-adapter/issues/929) Lots of warnings logged when filter matches no tests 'cat=BAZ', including other issues in the same. Thanks to [@runehalfdan](https://github.com/runehalfdan) for a lot of help reproducing and verifying these issues. Fixing this also improved performance, and cleared out issues with Explicit tests. +* [929](https://github.com/nunit/nunit3-vs-adapter/issues/929) Lots of warnings logged when filter matches no tests + 'cat=BAZ', including other issues in the same. Thanks to [@runehalfdan](https://github.com/runehalfdan) for a lot of + help reproducing and verifying these issues. Fixing this also improved performance, and cleared out issues with + Explicit tests. * [934](https://github.com/nunit/nunit3-vs-adapter/issues/934) Console output no longer output by dotnet test -v n. ### Engine update -The NUnit.Engine has been updated to version 3.13 in this release. See [engine release notes](xref:consoleenginereleasenotes) for details. +The NUnit.Engine has been updated to version 3.13 in this release. See [engine release +notes](xref:consoleenginereleasenotes) for details. ### Development -The [debugging of an adapter](Debugging.md) has been made simpler, using just a runsetting to enable it. See [this post](http://hermit.no/debugging-the-nunit3testadapter-take-2/) for details on the process. +The [debugging of an adapter](Debugging.md) has been made simpler, using just a runsetting to enable it. See [this +post](http://hermit.no/debugging-the-nunit3testadapter-take-2/) for details on the process. ## NUnit3 Test Adapter for Visual Studio - Version 4.1.0 - Nov 8, 2021 This is a bug fix release, with the following fixes: -* [516](https://github.com/nunit/nunit3-vs-adapter/issues/516) ArgumentException when whitespace sent to logger. Thanks to [Matt Jones - mthjones](https://github.com/mthjones) for a very good repro, that helped nail this down! +* [516](https://github.com/nunit/nunit3-vs-adapter/issues/516) ArgumentException when whitespace sent to logger. Thanks + to [Matt Jones - mthjones](https://github.com/mthjones) for a very good repro, that helped nail this down! -* [865](https://github.com/nunit/nunit3-vs-adapter/issues/865) Breaking changing in 3.17 on "Exception encountered unloading application domain" +* [865](https://github.com/nunit/nunit3-vs-adapter/issues/865) Breaking changing in 3.17 on "Exception encountered + unloading application domain" * [869](https://github.com/nunit/nunit3-vs-adapter/issues/869) NUnitTestAdapter - Discovery exception -* [884](https://github.com/nunit/nunit3-vs-adapter/issues/884) NUnit3TestAdapter 4.0.0 - DiscoveryException: Not a TestFixture, SetUpFixture or TestSuite, but ParameterizedFixture +* [884](https://github.com/nunit/nunit3-vs-adapter/issues/884) NUnit3TestAdapter 4.0.0 - DiscoveryException: Not a + TestFixture, SetUpFixture or TestSuite, but ParameterizedFixture ## NUnit3 Test Adapter for Visual Studio - Version 4.0.0 - June 6, 2021 This major release contains a series of changes, and also underlying changes in the adapter. -This is currently the version that will support Visual Studio 2022. The earlier versions will initially not support VS 2022. +This is currently the version that will support Visual Studio 2022. The earlier versions will initially not support VS +2022. -(There is a currently unknown issue that blocks the 3.X series for VS 2022. It is currently unclear if the Visual Studio team may be able to fix this issue. Any fix from the adapter side will include an upgrade, and then the 4.X series is the solution for that.) +(There is a currently unknown issue that blocks the 3.X series for VS 2022. It is currently unclear if the Visual +Studio team may be able to fix this issue. Any fix from the adapter side will include an upgrade, and then the 4.X +series is the solution for that.) -* [**Explicit**](https://github.com/nunit/nunit3-vs-adapter/issues?q=is%3Aissue+is%3Aclosed+project%3Anunit%2Fnunit3-vs-adapter%2F3) works now for all versions of Visual Studio. This is covered by several issues, see below on alpha and beta release notes. +* [**Explicit**](https://github.com/nunit/nunit3-vs-adapter/issues?q=is%3Aissue+is%3Aclosed+project%3Anunit%2Fnunit3-vs-adapter%2F3) + works now for all versions of Visual Studio. This is covered by several issues, see below on alpha and beta release + notes. -See the alpha and beta release notes below for more issues and features that have been resolved and is included in this major release. +See the alpha and beta release notes below for more issues and features that have been resolved and is included in this +major release. The following additional features have been implemented in the final release. @@ -132,61 +180,90 @@ The following additional features have been implemented in the final release. * [843](https://github.com/nunit/nunit3-vs-adapter/issues/843) Reporting random seed for a test case -* [863](https://github.com/nunit/nunit3-vs-adapter/pull/863) The Test Name is by default added to the console output for tests. It can be turned off by the [UseTestNameInConsoleOutput](/articles/vs-test-adapter/Tips-And-Tricks.html#usetestnameinconsoleoutput) property. +* [863](https://github.com/nunit/nunit3-vs-adapter/pull/863) The Test Name is by default added to the console output for + tests. It can be turned off by the + [UseTestNameInConsoleOutput](/articles/vs-test-adapter/Tips-And-Tricks.html#usetestnameinconsoleoutput) property. The following additional issue has been resolved: * [779](https://github.com/nunit/nunit3-vs-adapter/issues/779) Filtering tests with any "PropertyAttribute" -* [852](https://github.com/nunit/nunit3-vs-adapter/issues/852) NullReferenceException in ExtractTestFixture in v4.0.0-beta2. +* [852](https://github.com/nunit/nunit3-vs-adapter/issues/852) NullReferenceException in ExtractTestFixture in + v4.0.0-beta2. ## NUnit3 Test Adapter for Visual Studio - Version 4.0.0-beta.2 - April 6, 2021 This will be a short beta.2, given we don't hit on any intricate issues. -A major change in this version is the upgrade of the NUnit.Engine to version 3.12, and thus Mono.Cecil is no longer used. Instead it has a reduced version (based on Mono.Cecil) packed into TestCentric.engine.metadata doing the same job with navigation data. +A major change in this version is the upgrade of the NUnit.Engine to version 3.12, and thus Mono.Cecil is no longer +used. Instead it has a reduced version (based on Mono.Cecil) packed into TestCentric.engine.metadata doing the same job +with navigation data. The following issues have been resolved: -* [824](https://github.com/nunit/nunit3-vs-adapter/issues/824 ) "Not a TestFixture or TestSuite, but SetUpFixture" exception is being thrown in case of more than one SetUpFixture -* [811](https://github.com/nunit/nunit3-vs-adapter/issues/811) "System.FormatException: The UTC representation of the date falls outside the year range 1-9999" from skipped test in Eastern European time zone. Thanks to [KalleOlaviNiemitalo](https://github.com/KalleOlaviNiemitalo) for suggesting the fix. +* [824](https://github.com/nunit/nunit3-vs-adapter/issues/824 ) "Not a TestFixture or TestSuite, but SetUpFixture" + exception is being thrown in case of more than one SetUpFixture +* [811](https://github.com/nunit/nunit3-vs-adapter/issues/811) "System.FormatException: The UTC representation of the + date falls outside the year range 1-9999" from skipped test in Eastern European time zone. Thanks to + [KalleOlaviNiemitalo](https://github.com/KalleOlaviNiemitalo) for suggesting the fix. -Also a performance improvement was done, thanks to [Pakrym](https://github.com/pakrym) for the [PR 821](https://github.com/nunit/nunit3-vs-adapter/pull/821) +Also a performance improvement was done, thanks to [Pakrym](https://github.com/pakrym) for the [PR +821](https://github.com/nunit/nunit3-vs-adapter/pull/821) ## NUnit3 Test Adapter for Visual Studio - Version 4.0.0-beta.1 - Nov 20, 2020 -This beta is based on the earlier alpha version, and includes new fixes, some reported in the alpha. A great thank you to those who reported and checked out the fixes in the alpha! +This beta is based on the earlier alpha version, and includes new fixes, some reported in the alpha. A great thank you +to those who reported and checked out the fixes in the alpha! -The alpha has more than 32000 downloads, with only a few issues reported, so we feel safe to move up to a beta. The time for beta will be much shorter, so we might be able to release a final 4.0.0 version before end of 2020. +The alpha has more than 32000 downloads, with only a few issues reported, so we feel safe to move up to a beta. The +time for beta will be much shorter, so we might be able to release a final 4.0.0 version before end of 2020. We have also been able to shoehorn some new features into the release. -* [770](https://github.com/nunit/nunit3-vs-adapter/issues/770) "Not a TestFixture, but TestSuite" error when using un-namespaced SetupFixture. +* [770](https://github.com/nunit/nunit3-vs-adapter/issues/770) "Not a TestFixture, but TestSuite" error when using + un-namespaced SetupFixture. * [774](https://github.com/nunit/nunit3-vs-adapter/issues/774) Tests not executed if Console.WriteLine() is used. * [780](https://github.com/nunit/nunit3-vs-adapter/issues/780) NUnit3TestAdapter 3.17.0 empty output file regression? -* [781](https://github.com/nunit/nunit3-vs-adapter/issues/781) An exception occurred while test discoverer 'NUnit3TestDiscoverer' was loading tests. Exception: Object reference not set to an instance of an object, with VS2015. -* [785](https://github.com/nunit/nunit3-vs-adapter/issues/785) Seemingly redundant dependency on Microsoft.DotNet.InternalAbstractions. Thanks to [teo-tsirpanis](https://github.com/teo-tsirpanis) for [PR 790](https://github.com/nunit/nunit3-vs-adapter/pull/790). -* [786](https://github.com/nunit/nunit3-vs-adapter/issues/786) When using TRX logger, should warn about incompatible test adapter across .NET Framework and .NET Core and/or log where an adapter is located. -* [788](https://github.com/nunit/nunit3-vs-adapter/issues/788) Documentation: Broken links in user guide [vs-test-adapter/Resources.html]. +* [781](https://github.com/nunit/nunit3-vs-adapter/issues/781) An exception occurred while test discoverer + 'NUnit3TestDiscoverer' was loading tests. Exception: Object reference not set to an instance of an object, with + VS2015. +* [785](https://github.com/nunit/nunit3-vs-adapter/issues/785) Seemingly redundant dependency on + Microsoft.DotNet.InternalAbstractions. Thanks to [teo-tsirpanis](https://github.com/teo-tsirpanis) for [PR + 790](https://github.com/nunit/nunit3-vs-adapter/pull/790). +* [786](https://github.com/nunit/nunit3-vs-adapter/issues/786) When using TRX logger, should warn about incompatible + test adapter across .NET Framework and .NET Core and/or log where an adapter is located. +* [788](https://github.com/nunit/nunit3-vs-adapter/issues/788) Documentation: Broken links in user guide + [vs-test-adapter/Resources.html]. * [797](https://github.com/nunit/nunit3-vs-adapter/issues/797) Proprietary licensed files -* [800](https://github.com/nunit/nunit3-vs-adapter/issues/800) Rerun in azure devops overwrites last test results xml. Thanks to [netcorefactory](https://github.com/netcorefactory) for [PR 799](https://github.com/nunit/nunit3-vs-adapter/pull/799). +* [800](https://github.com/nunit/nunit3-vs-adapter/issues/800) Rerun in azure devops overwrites last test results xml. + Thanks to [netcorefactory](https://github.com/netcorefactory) for [PR + 799](https://github.com/nunit/nunit3-vs-adapter/pull/799). ## NUnit3 Test Adapter for Visual Studio - Version 4.0.0-alpha.1 - July 12, 2020 This is an early pre-release version. -The code has been rewritten/refactored in order to get some of the more complex issues fixed. It does pass all the automatic tests we have, but there are still more tests we would like to take it through, before we release a beta. +The code has been rewritten/refactored in order to get some of the more complex issues fixed. It does pass all the +automatic tests we have, but there are still more tests we would like to take it through, before we release a beta. -We would really appreciate it if you give this alpha a spin. and [report](https://github.com/nunit/nunit3-vs-adapter/issues) whatever you find back to us. +We would really appreciate it if you give this alpha a spin. and +[report](https://github.com/nunit/nunit3-vs-adapter/issues) whatever you find back to us. -The major fixes now are Explicit runs are fully back, both in Visual Studio and on command line with dotnet test and vstest.console. +The major fixes now are Explicit runs are fully back, both in Visual Studio and on command line with dotnet test and +vstest.console. -Further there has been a significant performance improvement for large test sets, and in particular when you run with categories or other filters. +Further there has been a significant performance improvement for large test sets, and in particular when you run with +categories or other filters. -For those interested in details, some of this has been achieved by converting the VSTest type of filters to NUnit native filters (Thanks to [Charlie Poole](https://github.com/CharliePoole) for his excellent contribution here.). +For those interested in details, some of this has been achieved by converting the VSTest type of filters to NUnit native +filters (Thanks to [Charlie Poole](https://github.com/CharliePoole) for his excellent contribution here.). -* [497](https://github.com/nunit/nunit3-vs-adapter/issues/497) Dotnet test with category filter is slow with a lot of tests -* [545](https://github.com/nunit/nunit3-vs-adapter/issues/545) Setting `TestCaseSource` to `Explicit` makes other tests in fixture explicit -* [612](https://github.com/nunit/nunit3-vs-adapter/issues/612) It is not possible to run an explicit test from Test Explorer -* [658](https://github.com/nunit/nunit3-vs-adapter/issues/658) Explicit tests are automatically run in Visual Studio 2019 +* [497](https://github.com/nunit/nunit3-vs-adapter/issues/497) Dotnet test with category filter is slow with a lot of + tests +* [545](https://github.com/nunit/nunit3-vs-adapter/issues/545) Setting `TestCaseSource` to `Explicit` makes other tests + in fixture explicit +* [612](https://github.com/nunit/nunit3-vs-adapter/issues/612) It is not possible to run an explicit test from Test + Explorer +* [658](https://github.com/nunit/nunit3-vs-adapter/issues/658) Explicit tests are automatically run in Visual Studio + 2019 * [767](https://github.com/nunit/nunit3-vs-adapter/issues/767) Replace use of VSTest filters with NUnit filters diff --git a/docs/articles/vs-test-adapter/Index.md b/docs/articles/vs-test-adapter/Index.md index e5dd67665..381218678 100644 --- a/docs/articles/vs-test-adapter/Index.md +++ b/docs/articles/vs-test-adapter/Index.md @@ -2,11 +2,13 @@ The NUnit 3 Test Adapter allows you to run NUnit 3 tests inside Visual Studio or with `dotnet` on the command line. -The current release is designed to work with Visual Studio 2012, 2013, 2015, 2017, 2019 and 2022. Some features are not available under VS2012 RTM. It also works from the command line using either `vstest.console` or `dotnet test`. +The current release is designed to work with Visual Studio 2012, 2013, 2015, 2017, 2019 and 2022. Some features are not +available under VS2012 RTM. It also works from the command line using either `vstest.console` or `dotnet test`. The current release works with .net framework 3.5 and higher, with .net core `3.*`, and with .net 5, .net 6, and .net 7. -Releases of Visual Studio prior to VS 2012 did not have the ability to directly run tests built with Open Source testing frameworks like NUnit. +Releases of Visual Studio prior to VS 2012 did not have the ability to directly run tests built with Open Source testing +frameworks like NUnit. [Download Released versions](https://www.nuget.org/packages/NUnit3TestAdapter/) @@ -15,5 +17,8 @@ Releases of Visual Studio prior to VS 2012 did not have the ability to directly The adapter is delivered as a nuget package to be installed into all test projects. > [!NOTE] -> Up to version 3.17 there is also a VSIX extension version, which was used earlier for Visual Studio up to version 2019. The support for this has been deprecated, and the existing VSIX version does not work for VS 2022. The recommendation is to avoid this altogether and use the nuget version. -> It is not possible to run NUnit 2.x tests using this adapter. Use the original adapter for that purpose. If you need to work with projects using NUnit 2.x and other projects using NUnit 3, you may install both versions of the adapter. +> Up to version 3.17 there is also a VSIX extension version, which was used earlier for Visual Studio up to +> version 2019. The support for this has been deprecated, and the existing VSIX version does not work for VS 2022. The +> recommendation is to avoid this altogether and use the nuget version. It is not possible to run NUnit 2.x tests using +> this adapter. Use the original adapter for that purpose. If you need to work with projects using NUnit 2.x and other +> projects using NUnit 3, you may install both versions of the adapter. diff --git a/docs/articles/vs-test-adapter/Known-Problems.md b/docs/articles/vs-test-adapter/Known-Problems.md index 0eb902066..367ef4a52 100644 --- a/docs/articles/vs-test-adapter/Known-Problems.md +++ b/docs/articles/vs-test-adapter/Known-Problems.md @@ -1,33 +1,48 @@ # Known Problems -1. Using both the VSIX adapter and nuget adapters at the same time can lead to discovery issues; see [nunit3-vs-adapter/issues #769](https://github.com/nunit/nunit3-vs-adapter/issues/769). The resolution is to uninstall the VSIX adapter, and only use the nuget adapters. The VSIX adapters are being deprecated in later VS versions. +1. Using both the VSIX adapter and nuget adapters at the same time can lead to discovery issues; see + [nunit3-vs-adapter/issues #769](https://github.com/nunit/nunit3-vs-adapter/issues/769). The resolution is to + uninstall the VSIX adapter, and only use the nuget adapters. The VSIX adapters are being deprecated in later VS + versions. 2. Support for Explicit keyword 1 Adapter versions in the 4.XX series support the `explicit` keyword in all Visual Studio versions. - 2 Adapter versions in the 3.XX series: From version 16.2 (Visual Studio 2019) the `Explicit` keyword is no longer explicitly supported by Visual Studio. If you want to use it, it does exist as a Category, so you can use it as a category filter. + 2 Adapter versions in the 3.XX series: From version 16.2 (Visual Studio 2019) the `Explicit` keyword is no longer + explicitly supported by Visual Studio. If you want to use it, it does exist as a Category, so you can use it as a + category filter. -3. There is no test status in Visual Studio corresponding to NUnit's Inconclusive result, so tests with this result are reported as Not Run. Click on the individual test to see the result. +3. There is no test status in Visual Studio corresponding to NUnit's Inconclusive result, so tests with this result are + reported as Not Run. Click on the individual test to see the result. 4. Theories are reported as individual cases, rather as a single unit. -5. In NUnit, tests have names, which are not necessarily unique. Visual Studio wants the names to be unique. So if two tests have the same name, VS displays a warning message in the output window. The message may be ignored. Two separate results will be shown under the single test in the explorer pane. +5. In NUnit, tests have names, which are not necessarily unique. Visual Studio wants the names to be unique. So if two + tests have the same name, VS displays a warning message in the output window. The message may be ignored. Two + separate results will be shown under the single test in the explorer pane. 6. Startup performance is substantially improved but is still slower than using NUnit directly. -7. Applies to pre-VS2017: When using a VSIX adapter and the NuGet adapter, the VSIX adapter will be used regardless of the NuGet adapter version. +7. Applies to pre-VS2017: When using a VSIX adapter and the NuGet adapter, the VSIX adapter will be used regardless of + the NuGet adapter version. - 1. Workaround: Make sure you have upgraded VSIX adapter to latest version, or uninstalled it if you have the NuGet adapter in a solution. The adapter will display its version number in the Output window under Tests. + 1. Workaround: Make sure you have upgraded VSIX adapter to latest version, or uninstalled it if you have the NuGet + adapter in a solution. The adapter will display its version number in the Output window under Tests. - 2. Avoid using the VSIX adapter for VS2017 and upwards. It is being deprecated, but is still supported optionally in VS2019. + 2. Avoid using the VSIX adapter for VS2017 and upwards. It is being deprecated, but is still supported optionally + in VS2019. 8. Visual Studio 2017 Live Unit Testing require NUnit3. The NUnit2 adapter doesn't support Live Unit Testing. -9. `Exception: Could not load file or assembly 'nunit.engine'` - Is caused by an incomplete copy of the adapter in the Visual Studio cache. Close Visual Studio and delete `C:\Users\username\AppData\Local\Temp\VisualStudioTestExplorerExtensions\NUnit3TestAdapter.{{version}}` +9. `Exception: Could not load file or assembly 'nunit.engine'` - Is caused by an incomplete copy of the adapter in the + Visual Studio cache. Close Visual Studio and delete + `C:\Users\username\AppData\Local\Temp\VisualStudioTestExplorerExtensions\NUnit3TestAdapter.{{version}}` ## Issues with other tools -* Versions of ReSharper earlier than the 8.2 version has an issue with the NuGet adapter, which will prevent NUnit tests from running. Make sure you have updated Reshaper to at least version 8.2. +* Versions of ReSharper earlier than the 8.2 version has an issue with the NuGet adapter, which will prevent NUnit tests + from running. Make sure you have updated Reshaper to at least version 8.2. -* ReSharper version 2018.1 are not able to work with adapter versions >= 3.12. This is fixed in 2018.3. See [Issue638](https://github.com/nunit/nunit3-vs-adapter/issues/638) for details. +* ReSharper version 2018.1 are not able to work with adapter versions >= 3.12. This is fixed in 2018.3. See + [Issue638](https://github.com/nunit/nunit3-vs-adapter/issues/638) for details. diff --git a/docs/articles/vs-test-adapter/Resources.md b/docs/articles/vs-test-adapter/Resources.md index 1c9418e8e..dbc3ba8e3 100644 --- a/docs/articles/vs-test-adapter/Resources.md +++ b/docs/articles/vs-test-adapter/Resources.md @@ -2,17 +2,23 @@ ## Further information -For more information see the blogs by [Charlie Poole](http://nunit.com/articles/), [Rob Prouse](https://alteridem.net/) and [Terje Sandstrom](https://hermit.no) +For more information see the blogs by [Charlie Poole](http://nunit.com/articles/), [Rob Prouse](https://alteridem.net/) +and [Terje Sandstrom](https://hermit.no) -The MSDN ALM blog post series on _How to Manage Unit Tests in Visual Studio 2012 Update 1_ is useful for later versions as well: +The MSDN ALM blog post series on _How to Manage Unit Tests in Visual Studio 2012 Update 1_ is useful for later versions +as well: -* [Part 1: Using Traits in the Unit Test Explorer](https://devblogs.microsoft.com/devops/how-to-manage-unit-tests-in-visual-studio-2012-update-1-part-1using-traits-in-the-unit-test-explorer/) +* [Part 1: Using Traits in the Unit Test + Explorer](https://devblogs.microsoft.com/devops/how-to-manage-unit-tests-in-visual-studio-2012-update-1-part-1using-traits-in-the-unit-test-explorer/) -* [Part 2: Using Traits with different test frameworks in the Unit Test Explorer](https://devblogs.microsoft.com/devops/part-2using-traits-with-different-test-frameworks-in-the-unit-test-explorer/) +* [Part 2: Using Traits with different test frameworks in the Unit Test + Explorer](https://devblogs.microsoft.com/devops/part-2using-traits-with-different-test-frameworks-in-the-unit-test-explorer/) -* [Part 3: Unit testing with Traits and code coverage in Visual Studio 2012 using the TFS Build](https://devblogs.microsoft.com/devops/part-3-unit-testing-with-traits-and-code-coverage-in-visual-studio-2012-using-the-tfs-build-and-the-new-nuget-adapter-approach/) +* [Part 3: Unit testing with Traits and code coverage in Visual Studio 2012 using the TFS + Build](https://devblogs.microsoft.com/devops/part-3-unit-testing-with-traits-and-code-coverage-in-visual-studio-2012-using-the-tfs-build-and-the-new-nuget-adapter-approach/) -For Information on testing .Net core see [Testing .NET Core with NUnit in Visual Studio 2017](https://alteridem.net/2017/05/04/test-net-core-nunit-vs2017/) +For Information on testing .Net core see [Testing .NET Core with NUnit in Visual Studio +2017](https://alteridem.net/2017/05/04/test-net-core-nunit-vs2017/) ## Reporting Problems diff --git a/docs/articles/vs-test-adapter/Supported-Frameworks.md b/docs/articles/vs-test-adapter/Supported-Frameworks.md index e9550bb8c..5683e2206 100644 --- a/docs/articles/vs-test-adapter/Supported-Frameworks.md +++ b/docs/articles/vs-test-adapter/Supported-Frameworks.md @@ -18,9 +18,13 @@ The table below shows the supported adapter versions for a given framework versi |Net 7|Works with 4.3 and upwards|| |Net 8+|Works with 4.4 and upwards|| -The adapter is shipped with two different versions of the test framework. The first is the full framework version, which is used for .NET Framework based test projects. The second is the .NET (Core) version, which is used for .NET Core 1.0, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0 and upwards. The different versions of the adapter supports different versions of the test framework. The table above shows the supported versions. +The adapter is shipped with two different versions of the test framework. The first is the full framework version, which +is used for .NET Framework based test projects. The second is the .NET (Core) version, which is used for .NET Core +1.0, 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, 8.0 and upwards. The different versions of the adapter supports different +versions of the test framework. The table above shows the supported versions. -Version 4.4 of the adapter will support future versions of .net, as long as there are no breaking changes. (Earlier versions have been blocking that based on the table above). +Version 4.4 of the adapter will support future versions of .net, as long as there are no breaking changes. (Earlier +versions have been blocking that based on the table above). The included versions are as shown below, only the versions where changes are done are listed. @@ -37,4 +41,5 @@ The included versions are as shown below, only the versions where changes are do ## Tips -See [Adapter/Engine compatibility](Adapter-Engine-Compatibility.md) for information on which engine versions are being used with the adapter. +See [Adapter/Engine compatibility](Adapter-Engine-Compatibility.md) for information on which engine versions are being +used with the adapter. diff --git a/docs/articles/vs-test-adapter/Tips-And-Tricks.md b/docs/articles/vs-test-adapter/Tips-And-Tricks.md index 964a6ed9e..963d45337 100644 --- a/docs/articles/vs-test-adapter/Tips-And-Tricks.md +++ b/docs/articles/vs-test-adapter/Tips-And-Tricks.md @@ -8,49 +8,51 @@ uid: tipsandtricks ### `dotnet test` and VS Test `.runsettings` configuration -Certain NUnit Test Adapter settings are configurable using a .runsettings file. -The following options are available: - -|Key|Type|Options| Default| -|---|----|-------|--------------| -|[InternalTraceLevel](#internaltracelevel)| enum | Off, Error, Warning, Info, Verbose, Debug| Nothing => Off| -|[NumberOfTestWorkers](#numberoftestworkers)| int | nr of workers | -1| -|[ShadowCopyFiles](#shadowcopyfiles)| bool |True, False | False| -|[Verbosity](#verbosity)| int | -1, 0-5 . -1 means quiet mode | 0| -|[UseVsKeepEngineRunning](#usevskeepenginerunning)| bool | True, False| False| -|BasePath| string | path| ?| -|PrivateBinPath | string| directory1;directory2;etc |?| -|RandomSeed | int | seed integer| random| -|DefaultTimeout |int|timeout in mS, 0 means infinite|0| -|[DefaultTestNamePattern](#defaulttestnamepattern)|string|Pattern for display name|{m}{a}| -|[WorkDirectory](#workdirectory)|string|specify directory|Test assembly location| -|[TestOutputXml](#testoutputxml)|string|specify directory|Test Result Xml output folder| -|[OutputXmlFolderMode](#outputxmlfoldermode)|enum|UseResultDirectory,RelativeToResultDirectory,RelativeToWorkFolder,AsSpecified|RelativeToWorkFolder| -|[DumpXmlTestDiscovery](#dumpxmltestdiscovery-and-dumpxmltestresults)|bool|Enable dumping of NUnit discovery response xml|false| -|[DumpXmlTestResults](#dumpxmltestdiscovery-and-dumpxmltestresults)|bool|Enable dumping of NUnit execution response xml|false| -|[PreFilter](#prefilter)|bool|Enable pre-filtering to increase performance for Visual Studio testing|false| -|[ShowInternalProperties](#showinternalproperties)| bool | Turn on showing internal NUnit properties in Test Explorer| false| -|[Where](#where)|string| NUnit Filter expression| -|[UseParentFQNForParametrizedTests](#useparentfqnforparametrizedtests)|bool|Enable parent as FQN for parametrized tests|false| -|[UseNUnitIdforTestCaseId](#usenunitidfortestcaseid) |bool|Uses NUnit test id as VSTest Testcase Id, instead of FullyQualifiedName|false| -|[ConsoleOut](#consoleout)|int|Sends standard console output to the output window|2| -|[UseTestNameInConsoleOutput](#usetestnameinconsoleoutput)|bool|Adds name of test as a prefix in the output window for console output|true| -|[StopOnError](#stoponerror)|bool|Stops on first error|false| -|[SkipNonTestAssemblies](#skipnontestassemblies)|bool|Adapter supports NonTestAssemblyAttribute|true| -|[MapWarningTo](#mapwarningto)|enum|Map Assert.Warn to either Passed, Failed or Skipped|Skipped| -|[DisplayName](#displayname)|enum|Set what a DisplayName is, options: Name, FullName or FullNameSep|Name| -|[FullnameSeparator](#fullnameseparator)|string|FullNameSep separator|':'| -|[DiscoveryMethod](#discoverymethod)|enum|How execution discovery is done, options are `Legacy` or `Current`|Current| -|[AssemblySelectLimit](#assemblyselectlimit)|int|Number of tests accepted before filters are turned off|2000| -|[NewOutputXmlFileForEachRun](#newoutputxmlfileforeachrun)|bool|Creates a new file for each test run|false| -|[IncludeStackTraceForSuites](#includestacktraceforsuites)|bool|Includes stack trace for failures in suites, like exceptions in OneTimeSetup|true| -|[ExplicitMode](#explicitmode)|enum|Changes handling of explicit tests, options are `Strict` or `Relaxed`|Strict| -|[SkipExecutionWhenNoTests](#skipexecutionwhennotests)|bool|Skip execution if no tests are found|false| -|[AllowParallelWithDebugger](#allowparallelwithdebugger)|bool|Allow parallel execution when debugger is attached|false| +Certain NUnit Test Adapter settings are configurable using a .runsettings file. The following options are available: + +| Key | Type | Options | Default | +| --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------- | ----------------------------- | +| [InternalTraceLevel](#internaltracelevel) | enum | Off, Error, Warning, Info, Verbose, Debug | Nothing => Off | +| [NumberOfTestWorkers](#numberoftestworkers) | int | nr of workers | -1 | +| [ShadowCopyFiles](#shadowcopyfiles) | bool | True, False | False | +| [Verbosity](#verbosity) | int | -1, 0-5 . -1 means quiet mode | 0 | +| [UseVsKeepEngineRunning](#usevskeepenginerunning) | bool | True, False | False | +| BasePath | string | path | ? | +| PrivateBinPath | string | directory1;directory2;etc | ? | +| RandomSeed | int | seed integer | random | +| DefaultTimeout | int | timeout in mS, 0 means infinite | 0 | +| [DefaultTestNamePattern](#defaulttestnamepattern) | string | Pattern for display name | {m}{a} | +| [WorkDirectory](#workdirectory) | string | specify directory | Test assembly location | +| [TestOutputXml](#testoutputxml) | string | specify directory | Test Result Xml output folder | +| [OutputXmlFolderMode](#outputxmlfoldermode) | enum | UseResultDirectory,RelativeToResultDirectory,RelativeToWorkFolder,AsSpecified | RelativeToWorkFolder | +| [DumpXmlTestDiscovery](#dumpxmltestdiscovery-and-dumpxmltestresults) | bool | Enable dumping of NUnit discovery response xml | false | +| [DumpXmlTestResults](#dumpxmltestdiscovery-and-dumpxmltestresults) | bool | Enable dumping of NUnit execution response xml | false | +| [PreFilter](#prefilter) | bool | Enable pre-filtering to increase performance for Visual Studio testing | false | +| [ShowInternalProperties](#showinternalproperties) | bool | Turn on showing internal NUnit properties in Test Explorer | false | +| [Where](#where) | string | NUnit Filter expression | | +| [UseParentFQNForParametrizedTests](#useparentfqnforparametrizedtests) | bool | Enable parent as FQN for parametrized tests | false | +| [UseNUnitIdforTestCaseId](#usenunitidfortestcaseid) | bool | Uses NUnit test id as VSTest Testcase Id, instead of FullyQualifiedName | false | +| [ConsoleOut](#consoleout) | int | Sends standard console output to the output window | 2 | +| [UseTestNameInConsoleOutput](#usetestnameinconsoleoutput) | bool | Adds name of test as a prefix in the output window for console output | true | +| [StopOnError](#stoponerror) | bool | Stops on first error | false | +| [SkipNonTestAssemblies](#skipnontestassemblies) | bool | Adapter supports NonTestAssemblyAttribute | true | +| [MapWarningTo](#mapwarningto) | enum | Map Assert.Warn to either Passed, Failed or Skipped | Skipped | +| [DisplayName](#displayname) | enum | Set what a DisplayName is, options: Name, FullName or FullNameSep | Name | +| [FullnameSeparator](#fullnameseparator) | string | FullNameSep separator | ':' | +| [DiscoveryMethod](#discoverymethod) | enum | How execution discovery is done, options are `Legacy` or `Current` | Current | +| [AssemblySelectLimit](#assemblyselectlimit) | int | Number of tests accepted before filters are turned off | 2000 | +| [NewOutputXmlFileForEachRun](#newoutputxmlfileforeachrun) | bool | Creates a new file for each test run | false | +| [IncludeStackTraceForSuites](#includestacktraceforsuites) | bool | Includes stack trace for failures in suites, like exceptions in OneTimeSetup | true | +| [ExplicitMode](#explicitmode) | enum | Changes handling of explicit tests, options are `Strict` or `Relaxed` | Strict | +| [SkipExecutionWhenNoTests](#skipexecutionwhennotests) | bool | Skip execution if no tests are found | false | +| [AllowParallelWithDebugger](#allowparallelwithdebugger) | bool | Allow parallel execution when debugger is attached | false | ### Visual Studio templates for runsettings -You can install [item templates for runsettings](https://marketplace.visualstudio.com/items?itemName=OsirisTerje.Runsettings-19151) in Visual Studio (applies to version 2017, 2019 and upwards) which includes the NUnit settings mentioned here. Note that there are available separate installs for earlier Visual Studio versions, links to these can be found in the above. +You can install [item templates for +runsettings](https://marketplace.visualstudio.com/items?itemName=OsirisTerje.Runsettings-19151) in Visual Studio +(applies to version 2017, 2019 and upwards) which includes the NUnit settings mentioned here. Note that there are +available separate installs for earlier Visual Studio versions, links to these can be found in the above. ### Example implementation @@ -66,26 +68,36 @@ See ``` -Note that the ```Where``` statement does not work for the Visual Studio Test Explorer, as it would generate a conflict with the test list the adapter receives. It is intended for use with command line tools, `dotnet test` or `vstest.console`. +Note that the ```Where``` statement does not work for the Visual Studio Test Explorer, as it would generate a conflict +with the test list the adapter receives. It is intended for use with command line tools, `dotnet test` or +`vstest.console`. (From version 3.16.0) #### UseParentFQNForParametrizedTests -Setting this may give more stable results when you have complex data driven/parametrized tests. However, when this is set selecting a single test within such a group, means that **all** tests in that group is executed. +Setting this may give more stable results when you have complex data driven/parametrized tests. However, when this is +set selecting a single test within such a group, means that **all** tests in that group is executed. Note that this often has to be set together with [UseNUnitIdforTestCaseId](#usenunitidfortestcaseid) @@ -184,9 +214,11 @@ Note that this often has to be set together with [UseNUnitIdforTestCaseId](#usen #### UseNUnitIdforTestCaseId -The default setting is false, causes the VSTest Testcase ID to be based on the NUnit fullname property, which is nearly equal to a FullyQualifiedName. The fullname is also set into the Testcase FullyQualifiedName property. +The default setting is false, causes the VSTest Testcase ID to be based on the NUnit fullname property, which is nearly +equal to a FullyQualifiedName. The fullname is also set into the Testcase FullyQualifiedName property. -By setting this property true, it shifts to using the NUnit id as the basis for the testcase id. This may in certain cases give more stable results, and are more correct. +By setting this property true, it shifts to using the NUnit id as the basis for the testcase id. This may in certain +cases give more stable results, and are more correct. However, it has been seen to also have adverse effects, so use with caution. @@ -194,13 +226,15 @@ However, it has been seen to also have adverse effects, so use with caution. #### ConsoleOut -When set to 1 or 2 (2 is default), will send Console standard output to the Visual Studio Output/Test window, and also with dotnet test, it will appear in the output. +When set to 1 or 2 (2 is default), will send Console standard output to the Visual Studio Output/Test window, and also +with dotnet test, it will appear in the output. Disable this by setting it to 0, which is also the default for version earlier than 3.17.0. The value 1 sends it out as Information, while 2 sends it out as Warning. -Using `dotnet test` with `ConsoleOut=1` (Information) (`dotnet test -- NUnit.ConsoleOut=1`), nothing will appear in the output. +Using `dotnet test` with `ConsoleOut=1` (Information) (`dotnet test -- NUnit.ConsoleOut=1`), nothing will appear in +the output. Setting `ConsoleOut=2` (Warning) the message will be shown. @@ -208,7 +242,8 @@ Adding the logger `dotnet test -l "console;verbosity=detailed" -- NUnit.Consoleo See [Issue 343](https://github.com/nunit/nunit3-vs-adapter/issues/343) for more information and discussion -In earlier versions you had to use `-v n`, but that is no longer required. In order to silence it in `dotnet test` you have to do: +In earlier versions you had to use `-v n`, but that is no longer required. In order to silence it in `dotnet test` you +have to do: ```console dotnet test -- NUnit.ConsoleOut=0 @@ -220,13 +255,15 @@ dotnet test -- NUnit.ConsoleOut=0 #### UseTestNameInConsoleOutput -When set to `true`, the default, the name of the test is added as a prefix in front of each console line output. This only applies to the output in the output window. +When set to `true`, the default, the name of the test is added as a prefix in front of each console line output. This +only applies to the output in the output window. (From version 4.0.0) #### StopOnError -When enabled (set to true), the tests will stop after the first test failed. Useful when working with a system with many tests running for a long time, where a few fails. It can then speed up by stopping at the first one. +When enabled (set to true), the tests will stop after the first test failed. Useful when working with a system with +many tests running for a long time, where a few fails. It can then speed up by stopping at the first one. See [Issue 675](https://github.com/nunit/nunit3-vs-adapter/issues/675) for more information and discussion @@ -234,23 +271,27 @@ See [Issue 675](https://github.com/nunit/nunit3-vs-adapter/issues/675) for more #### MapWarningTo -Assert Warnings will default map to `Skipped`, but you can set this to any other state, using MapWarningTo. The options are: -`Passed`, `Failed` or `Skipped`. +Assert Warnings will default map to `Skipped`, but you can set this to any other state, using MapWarningTo. The options +are: `Passed`, `Failed` or `Skipped`. (From version 3.17.0) #### SkipNonTestAssemblies -If the attribute `NonTestAssembly` is added in an assembly, it will be skipped from further testing. If [RTD](https://devblogs.microsoft.com/dotnet/real-time-test-discovery/) is enabled in Visual Studio, the tests will be displayed, but running will skip them. -See explanation for the [NonTestAssembly Attribute](xref:nontestassembly), and [Issue explanation here](https://github.com/nunit/nunit3-vs-adapter/issues/758). +If the attribute `NonTestAssembly` is added in an assembly, it will be skipped from further testing. If +[RTD](https://devblogs.microsoft.com/dotnet/real-time-test-discovery/) is enabled in Visual Studio, the tests will be +displayed, but running will skip them. +See explanation for the [NonTestAssembly Attribute](xref:nontestassembly), and [Issue explanation +here](https://github.com/nunit/nunit3-vs-adapter/issues/758). -(From version 3.17.0) -(Default changed to true from 4.0.0) +(From version 3.17.0) (Default changed to true from 4.0.0) #### DisplayName -The default for Test Explorer `DisplayName` is to use the Name of the test, which normally is the method name. Using DisplayName you can change between `Name`, `FullName` or `FullNameSep`. The last one will then use the FullNameSeparator,which defaults to '`:`'. -See [Issue 640](https://github.com/nunit/nunit3-vs-adapter/issues/640) for explanations of use and [sample code](https://github.com/nunit/nunit3-vs-adapter.issues/tree/master/Issue640) here. +The default for Test Explorer `DisplayName` is to use the Name of the test, which normally is the method name. Using +DisplayName you can change between `Name`, `FullName` or `FullNameSep`. The last one will then use the +FullNameSeparator,which defaults to '`:`'. See [Issue 640](https://github.com/nunit/nunit3-vs-adapter/issues/640) for +explanations of use and [sample code](https://github.com/nunit/nunit3-vs-adapter.issues/tree/master/Issue640) here. (From version 3.17.0) @@ -262,48 +303,69 @@ The separator character used when DisplayName is FullNameSep. It is default '`: #### DiscoveryMethod -The 4.0 version of the NUnit3TestAdapter has a rewritten discovery mechanism and also other redesigns/refactoring done. This setting let you switch back to the old form of discovery, using the setting `Legacy`. The default value is `Current`. +The 4.0 version of the NUnit3TestAdapter has a rewritten discovery mechanism and also other redesigns/refactoring done. +This setting let you switch back to the old form of discovery, using the setting `Legacy`. The default value is +`Current`. -The `Current` setting enables the Explicit feature back. It also performs better (approx 30% faster for large test sets). It might affect certain special cases, so therefore you can switch back. +The `Current` setting enables the Explicit feature back. It also performs better (approx 30% faster for large test +sets). It might affect certain special cases, so therefore you can switch back. (From version 4.0.0) #### AssemblySelectLimit -If you run from the IDE (Visual Studio) the adapter will receive a list of tests to process. This is heavy when the number of tests are large. If the number of tests exceeds this limit, the list will be skipped and all tests in the assembly will be run (except those tests that are Explicit or Ignored). +If you run from the IDE (Visual Studio) the adapter will receive a list of tests to process. This is heavy when the +number of tests are large. If the number of tests exceeds this limit, the list will be skipped and all tests in the +assembly will be run (except those tests that are Explicit or Ignored). -This might have an adverse effect if you select a category and you have more than 2000 tests, the category setting will be ignored. In that case, just increase this limit to higher than your number of tests. +This might have an adverse effect if you select a category and you have more than 2000 tests, the category setting will +be ignored. In that case, just increase this limit to higher than your number of tests. -You might also receive a list from the command line, and in that case it will also be skipped the same way. Here the category will be honored since the category filter will be converted to a NUnit filter. +You might also receive a list from the command line, and in that case it will also be skipped the same way. Here the +category will be honored since the category filter will be converted to a NUnit filter. (From version 4.0.0) #### NewOutputXmlFileForEachRun -Default behavior is to produce one test output file which is being overwritten for each run Setting this to `true`, the adapter produces a new test output file for each run, numbering them sequentially. Default is `false`. +Default behavior is to produce one test output file which is being overwritten for each run Setting this to `true`, the +adapter produces a new test output file for each run, numbering them sequentially. Default is `false`. -The background is the following scenario, as described by [netcorefactory](https://github.com/netcorefactory) in [Issue 800](https://github.com/nunit/nunit3-vs-adapter/issues/800): +The background is the following scenario, as described by [netcorefactory](https://github.com/netcorefactory) in [Issue +800](https://github.com/nunit/nunit3-vs-adapter/issues/800): -"*Running test in azure devops one can choose to rerun failed ( flaky ) tests. Mostly when running (selenium) e2e tests this becomes important. The .xml results file is currently overwritten each retry run. Other test coverage tooling dependent on this file receives only latest run results. -Better to allow the possibility to deliver a results file per run.*" +"*Running test in azure devops one can choose to rerun failed ( flaky ) tests. Mostly when running (selenium) e2e tests +this becomes important. The .xml results file is currently overwritten each retry run. Other test coverage tooling +dependent on this file receives only latest run results. Better to allow the possibility to deliver a results file per +run.*" (From version 4.0.0) #### IncludeStackTraceForSuites -Exceptions outside test cases are reported with its stack trace included in the message. One example here is exceptions in OneTimeSetUp and OneTimeTearDown. They belong to the outer suite, and their exceptions are reported as part of the message. This option includes the stack trace in that message. If this becomes too much information, this option turns the stack trace reporting off. +Exceptions outside test cases are reported with its stack trace included in the message. One example here is exceptions +in OneTimeSetUp and OneTimeTearDown. They belong to the outer suite, and their exceptions are reported as part of the +message. This option includes the stack trace in that message. If this becomes too much information, this option turns +the stack trace reporting off. (From version 4.0.0) #### ExplicitMode -This setting can be either ```Strict``` or ```Relaxed```. The default is ```Strict```, which means that ```Explicit``` tests can only be run with other Explicit tests, and not mixed with non-Explicit tests. The ```Relaxed``` mode is the original NUnit mode, where if you select a category, a class or a set of tests, both explicit and non-explicit tests will be run. From Visual Studio Test Explorer there are no longer (since VS2019) any way of separating between a ```Run-All``` and ```run selected tests```, so Relaxed mode doesn't work properly. It may or may not work for command line tests, dependent upon how your tests are set up and run. +This setting can be either ```Strict``` or ```Relaxed```. The default is ```Strict```, which means that ```Explicit``` +tests can only be run with other Explicit tests, and not mixed with non-Explicit tests. The ```Relaxed``` mode is the +original NUnit mode, where if you select a category, a class or a set of tests, both explicit and non-explicit tests +will be run. From Visual Studio Test Explorer there are no longer (since VS2019) any way of separating between a +```Run-All``` and ```run selected tests```, so Relaxed mode doesn't work properly. It may or may not work for command +line tests, dependent upon how your tests are set up and run. (From version 4.2.0) #### SkipExecutionWhenNoTests -If set, this setting will skip execution for an assembly if no tests are found during the pre-execution discovery phase. It will give you a small performance boost, but if you skip the execution, this assembly will not generate any log files. The default is false. +If set, this setting will skip execution for an assembly if no tests are found during the pre-execution discovery phase. +It will give you a small performance boost, but if you skip the execution, this assembly will not generate any log +files. The default is false. (From version 4.2.0) @@ -315,16 +377,26 @@ If set, this setting will allow parallel execution of tests even if the debugger --- -### Some further information on directories (From [comment on issue 575](https://github.com/nunit/nunit3-vs-adapter/issues/575#issuecomment-445786421) by [Charlie](https://github.com/CharliePoole) ) +### Some further information on directories + +(From [comment on issue 575](https://github.com/nunit/nunit3-vs-adapter/issues/575#issuecomment-445786421) by +[Charlie](https://github.com/CharliePoole) ) -NUnit also supports TestContext.TestDirectory, which is the directory where the current test assembly is located. Note that if you have several test assemblies in different directories, the value will be different when each one of them accesses it. Note also that there is no way you can set the TestDirectory because it's always where the assembly is located. +NUnit also supports TestContext.TestDirectory, which is the directory where the current test assembly is located. Note +that if you have several test assemblies in different directories, the value will be different when each one of them +accesses it. Note also that there is no way you can set the TestDirectory because it's always where the assembly is +located. -The BasePath is a .NET thing. It's the base directory where assemblies are searched for. You can also have subdirectories listed in the PrivateBinPath. NUnit takes care of all this automatically now, so the old console options are no longer supported. For finding things you want to read at runtime, the TestDirectory and the BasePath will usually be the same thing. +The BasePath is a .NET thing. It's the base directory where assemblies are searched for. You can also have +subdirectories listed in the PrivateBinPath. NUnit takes care of all this automatically now, so the old console options +are no longer supported. For finding things you want to read at runtime, the TestDirectory and the BasePath will usually +be the same thing. ### Registry Settings > [!NOTE] -> As of the 3.0 final release, the registry settings are no longer recognized. Instead, use settings in the `.runsettings` file. +> As of the 3.0 final release, the registry settings are no longer recognized. Instead, use settings in the +> `.runsettings` file. --- @@ -334,18 +406,24 @@ NUnit 2.X does not support runsettings. ### Registry Settings for NUnit 2.x -Certain settings in the registry affect how the adapter runs. All these settings are added by using RegEdit under the key **HKCU\Software\nunit.org\VSAdapter**. +Certain settings in the registry affect how the adapter runs. All these settings are added by using RegEdit under the +key **HKCU\Software\nunit.org\VSAdapter**. #### ShadowCopy -By default NUnit no longer uses shadowcopy. If this causes an issue for you shadowcopy can be enabled by setting the DWORD value UseShadowCopy to 1. +By default NUnit no longer uses shadowcopy. If this causes an issue for you shadowcopy can be enabled by setting the +DWORD value UseShadowCopy to 1. #### KeepEngineRunning -By default the NUnit adapter will "Kill" the Visual Studio Test Execution engine after each run. Visual Studio 2013 and later has a new setting under its top menu, **Test | Test Settings | Keep Test Execution Engine Running**. The adapter normally ignores this setting. +By default the NUnit adapter will "Kill" the Visual Studio Test Execution engine after each run. Visual Studio 2013 and +later has a new setting under its top menu, **Test | Test Settings | Keep Test Execution Engine Running**. The adapter +normally ignores this setting. -In some cases it can be useful to have the engine running, e.g. during debugging of the adapter itself. You can then set the adapter to follow the VS setting by setting the DWORD value UseVsKeepEngineRunning to 1. +In some cases it can be useful to have the engine running, e.g. during debugging of the adapter itself. You can then set +the adapter to follow the VS setting by setting the DWORD value UseVsKeepEngineRunning to 1. #### Verbosity for NUnit 2.x -Normally the adapter reports exceptions using a short format, consisting of the message only. You can change it to report a verbose format that includes the stack trace, by setting a the DWORD value Verbosity to 1. +Normally the adapter reports exceptions using a short format, consisting of the message only. You can change it to +report a verbose format that includes the stack trace, by setting a the DWORD value Verbosity to 1. diff --git a/docs/articles/vs-test-adapter/Trace-and-Debug.md b/docs/articles/vs-test-adapter/Trace-and-Debug.md index 2a3018024..62cbf8439 100644 --- a/docs/articles/vs-test-adapter/Trace-and-Debug.md +++ b/docs/articles/vs-test-adapter/Trace-and-Debug.md @@ -1,12 +1,16 @@ # How to enable Trace and Debug output -Trace and Debug output is by default not sent to the console output, or anywhere else. If you want to have this output, you must add your own `TraceListener`. +Trace and Debug output is by default not sent to the console output, or anywhere else. If you want to have this output, +you must add your own `TraceListener`. ## Implementing the `TraceListener` in your code -This is easy to do, and you can do it per assembly, per namespace or per test. All it takes is to add the necessary initialization of the `TraceListener`. +This is easy to do, and you can do it per assembly, per namespace or per test. All it takes is to add the necessary +initialization of the `TraceListener`. -To add it to a namespace, place the following class inside that namespace, and it will apply to all tests inside that namespace and below. The code shown adds the output to console output. If you like you can change that to another kind of listener. +To add it to a namespace, place the following class inside that namespace, and it will apply to all tests inside that +namespace and below. The code shown adds the output to console output. If you like you can change that to another kind +of listener. ```csharp [SetUpFixture] @@ -28,7 +32,8 @@ public class SetupTrace If you place the code above outside of any namespace it will apply to the whole assembly. -If you'd like to only apply to a given test fixture/class, you can add the `StartTest and EndTest` methods to the given test fixture/class. +If you'd like to only apply to a given test fixture/class, you can add the `StartTest and EndTest` methods to the given +test fixture/class. ## Example outputs @@ -61,6 +66,9 @@ Running `dotnet test -v n`, the output will be: ## Discussion and source -This issue have been discussed at [Issue 718](https://github.com/nunit/nunit3-vs-adapter/issues/718) and [Issue 301](https://github.com/nunit/nunit3-vs-adapter/issues/301). Use of `TraceListener` suggested by [Frans Bouma](https://github.com/FransBouma). +This issue have been discussed at [Issue 718](https://github.com/nunit/nunit3-vs-adapter/issues/718) and [Issue +301](https://github.com/nunit/nunit3-vs-adapter/issues/301). Use of `TraceListener` suggested by [Frans +Bouma](https://github.com/FransBouma). -The repro code for the issue can be found [here](https://github.com/nunit/nunit3-vs-adapter.issues/tree/master/Issue718). +The repro code for the issue can be found +[here](https://github.com/nunit/nunit3-vs-adapter.issues/tree/master/Issue718). diff --git a/docs/articles/vs-test-adapter/Usage.md b/docs/articles/vs-test-adapter/Usage.md index 5b206cc41..9d5d4db45 100644 --- a/docs/articles/vs-test-adapter/Usage.md +++ b/docs/articles/vs-test-adapter/Usage.md @@ -1,18 +1,28 @@ # Usage -In preparation for using the test adapter, make sure that the Unit Test Explorer is shown in your window. If you don't see it, use the menu ( Test | Windows | Test Explorer ) to show it and position the window where you would like it within Visual Studio. +In preparation for using the test adapter, make sure that the Unit Test Explorer is shown in your window. If you don't +see it, use the menu ( Test | Windows | Test Explorer ) to show it and position the window where you would like it +within Visual Studio. ![The unit test explorer window within Visual Studio](~/images/nunitTestAdapter.png) -When you initially open a solution, no tests will be displayed. After compiling the assemblies in the solution, Visual Studio will interact with the NUnit Test Adapter to discover tests and a list of them will be shown in the Test Explorer. +When you initially open a solution, no tests will be displayed. After compiling the assemblies in the solution, Visual +Studio will interact with the NUnit Test Adapter to discover tests and a list of them will be shown in the Test +Explorer. -Click on Run All in the Test Explorer to run all the tests. You may also select one or more tests in the list and run them by right-clicking and using the context menu. The context menu also contains entries for debugging tests and for navigating to the source code of a test. +Click on Run All in the Test Explorer to run all the tests. You may also select one or more tests in the list and run +them by right-clicking and using the context menu. The context menu also contains entries for debugging tests and for +navigating to the source code of a test. -Tests may be grouped by Duration and Outcome under VS2012 RTM and also by Traits and Project using Update 1 or later, and Class using Update 2 or later. NUnit translates any Categories and Properties used on your tests to Visual Studio as Traits. +Tests may be grouped by Duration and Outcome under VS2012 RTM and also by Traits and Project using Update 1 or later, +and Class using Update 2 or later. NUnit translates any Categories and Properties used on your tests to Visual Studio +as Traits. -Tests may be filtered in Visual Studio under Update 1 or later by Trait, Project, Error Message, File Path, Fully Qualified Name, Output and Outcome. Use the search edit box at the top of the list of tests to specify a filter. +Tests may be filtered in Visual Studio under Update 1 or later by Trait, Project, Error Message, File Path, Fully +Qualified Name, Output and Outcome. Use the search edit box at the top of the list of tests to specify a filter. -Tests may be organized by play lists in Visual Studio under Update 2 or later. Playlists are more or less equal to the old test lists from VS 2010. +Tests may be organized by play lists in Visual Studio under Update 2 or later. Playlists are more or less equal to the +old test lists from VS 2010. Parameterized tests will show up as separate test cases for each set of parameters. diff --git a/docs/articles/vs-test-generator/TestGenerator-Installation.md b/docs/articles/vs-test-generator/TestGenerator-Installation.md index 83a26799f..04c496753 100644 --- a/docs/articles/vs-test-generator/TestGenerator-Installation.md +++ b/docs/articles/vs-test-generator/TestGenerator-Installation.md @@ -1,15 +1,22 @@ # TestGenerator Extension for NUnit in Visual Studio Installation -You can download this extension from inside Visual Studio, choosing Tools/Extensions and Updates and search for Test Generator. You will then find the appropriate extension for VS 2015 or VS 2017/2019. +You can download this extension from inside Visual Studio, choosing Tools/Extensions and Updates and search for Test +Generator. You will then find the appropriate extension for VS 2015 or VS 2017/2019. ## For Visual Studio 2022 -You can download from the marketplace [Visual Studio Gallery](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.nunittestgeneratorextension2022) or from the [GitHub Release page](https://github.com/nunit/nunit-vs-testgenerator/releases) +You can download from the marketplace [Visual Studio +Gallery](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.nunittestgeneratorextension2022) or from +the [GitHub Release page](https://github.com/nunit/nunit-vs-testgenerator/releases) ## For Visual Studio 2017/2019 -You can download from the marketplace [Visual Studio Gallery](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.TestGeneratorNUnitextension-18371) or from the [GitHub Release page](https://github.com/nunit/nunit-vs-testgenerator/releases) +You can download from the marketplace [Visual Studio +Gallery](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.TestGeneratorNUnitextension-18371) or from +the [GitHub Release page](https://github.com/nunit/nunit-vs-testgenerator/releases) ## For Visual Studio 2015 -You can download from the marketplace [Visual Studio Gallery](https://visualstudiogallery.msdn.microsoft.com/bd30bf3f-4183-4b00-a245-1875316b8cd3) or from the [GitHub Release page](https://github.com/nunit/nunit-vs-testgenerator/releases) +You can download from the marketplace [Visual Studio +Gallery](https://visualstudiogallery.msdn.microsoft.com/bd30bf3f-4183-4b00-a245-1875316b8cd3) or from the [GitHub +Release page](https://github.com/nunit/nunit-vs-testgenerator/releases) diff --git a/docs/articles/vs-test-generator/TestGenerator-Release-Notes-VS2015.md b/docs/articles/vs-test-generator/TestGenerator-Release-Notes-VS2015.md index efde780a1..b2c5c90e8 100644 --- a/docs/articles/vs-test-generator/TestGenerator-Release-Notes-VS2015.md +++ b/docs/articles/vs-test-generator/TestGenerator-Release-Notes-VS2015.md @@ -11,4 +11,6 @@ ### Notes -* The TestGenerator extension is released as separate VSIXes for VS 2015 and VS 2017/2019. See [Installation](TestGenerator-Installation.md) for details. The Version 2.X is for VS2017/2019, the Version 1.X is for VS 2015. +* The TestGenerator extension is released as separate VSIXes for VS 2015 and VS 2017/2019. See + [Installation](TestGenerator-Installation.md) for details. The Version 2.X is for VS2017/2019, the Version 1.X is for + VS 2015. diff --git a/docs/articles/vs-test-generator/TestGenerator-Release-Notes-VS2017-VS2019.md b/docs/articles/vs-test-generator/TestGenerator-Release-Notes-VS2017-VS2019.md index 20067b0ea..a1d8ac7c0 100644 --- a/docs/articles/vs-test-generator/TestGenerator-Release-Notes-VS2017-VS2019.md +++ b/docs/articles/vs-test-generator/TestGenerator-Release-Notes-VS2017-VS2019.md @@ -4,15 +4,19 @@ ### Features -* [PR 33](https://github.com/nunit/nunit-vs-testgenerator/pull/33) [Create Unit Test] Fixing package versions. This is needed in order to work for .net core projects. With Visual Studio 2019, Update 3, it is possible to use this extension to create tests. +* [PR 33](https://github.com/nunit/nunit-vs-testgenerator/pull/33) [Create Unit Test] Fixing package versions. This is + needed in order to work for .net core projects. With Visual Studio 2019, Update 3, it is possible to use this + extension to create tests. ## TestGenerator Extension for NUnit in Visual Studio 2017/2019 - Version 2.1 - November 22, 2018 -Visual Studio 2017 15.9 and forward should have the adapter added to each test project. This release ensures that by fixing #25. +Visual Studio 2017 15.9 and forward should have the adapter added to each test project. This release ensures that by +fixing #25. ### Features -* [25](https://github.com/nunit/nunit-vs-testgenerator/issues/25) Add the test adapter as part of the package. Thanks to [yowko](https://github.com/yowko) for the PR +* [25](https://github.com/nunit/nunit-vs-testgenerator/issues/25) Add the test adapter as part of the package. Thanks + to [yowko](https://github.com/yowko) for the PR ## TestGenerator Extension for NUnit in Visual Studio 2017/2019 - Version 2 - March 5, 2017 @@ -29,4 +33,6 @@ Visual Studio 2017 15.9 and forward should have the adapter added to each test p ### Notes -* The TestGenerator extension is released as separate VSIXes for VS 2015 and VS 2017/2019. See [Installation](TestGenerator-Installation.md) for details. The Version 2 is for VS2017/2019, the Version 1 is for VS 2015. +* The TestGenerator extension is released as separate VSIXes for VS 2015 and VS 2017/2019. See + [Installation](TestGenerator-Installation.md) for details. The Version 2 is for VS2017/2019, the Version 1 is for VS + 2015. diff --git a/docs/articles/vs-test-generator/Visual-Studio-Test-Generator.md b/docs/articles/vs-test-generator/Visual-Studio-Test-Generator.md index db0459686..b08f4e22a 100644 --- a/docs/articles/vs-test-generator/Visual-Studio-Test-Generator.md +++ b/docs/articles/vs-test-generator/Visual-Studio-Test-Generator.md @@ -4,26 +4,26 @@ uid: vstestgenerator # Visual Studio Test Generator -This is an extension for Visual Studio 2015, 2017/2019 and 2022 that extends -the test functionality to allow you to create unit tests and IntelliTests. -This extension extends the built in test generator functionality allowing -developers to generate tests using NUnit 2.6.x (not for VS2022) or NUnit 3.X. +This is an extension for Visual Studio 2015, 2017/2019 and 2022 that extends the test functionality to allow you to +create unit tests and IntelliTests. This extension extends the built in test generator functionality allowing developers +to generate tests using NUnit 2.6.x (not for VS2022) or NUnit 3.X. -Please note that IntelliTest is only available in Visual -Studio Enterprise edition. Other versions of Visual Studio -only have the `Create Unit Tests` menu option. +Please note that IntelliTest is only available in Visual Studio Enterprise edition. Other versions of Visual Studio only +have the `Create Unit Tests` menu option. ## Download You can download this extension in Visual Studio using **Tools | Extensions and Updates...** -and searching for **Test Generator NUnit Extension**. You can also download from the -[Visual Studio Gallery](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.TestGeneratorNUnitextension) for VS 2015 and [here for VS 2017](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.TestGeneratorNUnitextension-18371), -or from the [GitHub Releases Page](https://github.com/nunit/nunit-vs-testgenerator/releases). +and searching for **Test Generator NUnit Extension**. You can also download from the [Visual Studio +Gallery](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.TestGeneratorNUnitextension) for VS 2015 +and [here for VS +2017](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.TestGeneratorNUnitextension-18371), or from +the [GitHub Releases Page](https://github.com/nunit/nunit-vs-testgenerator/releases). ### How to Use -For more information on using IntelliTest and this extension, please -see the [Microsoft documentation](https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/test/generate-unit-tests-for-your-code-with-intellitest?view=vs-2015&redirectedfrom=MSDN). +For more information on using IntelliTest and this extension, please see the [Microsoft +documentation][IntelliTestLink]. #### Right-Click to Create Tests @@ -32,3 +32,5 @@ see the [Microsoft documentation](https://learn.microsoft.com/en-us/previous-ver #### Select NUnit from the Test Framework dropdown ![Selecting NUnit](~/images/right-click-create-tests-select-nunit.png) + +[IntelliTestLink]: https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/test/generate-unit-tests-for-your-code-with-intellitest?view=vs-2015&redirectedfrom=MSDN diff --git a/docs/articles/xamarin-runners/Getting-Started-in-Visual-Studio-for-Mac.md b/docs/articles/xamarin-runners/Getting-Started-in-Visual-Studio-for-Mac.md index 057da5d4a..bc30cc18f 100644 --- a/docs/articles/xamarin-runners/Getting-Started-in-Visual-Studio-for-Mac.md +++ b/docs/articles/xamarin-runners/Getting-Started-in-Visual-Studio-for-Mac.md @@ -1,6 +1,8 @@ # Getting Started In Visual Studio For Mac -If you're using Visual Studio for Mac the NUnit templates extension can't be used. This guide assumes that you have a solution with either a PCL or a Shared project and a number of platform specific projects. It doesn't matter if you're using Xamarin.Forms or Xamarin.iOS/Xamarin.Android directly. Your solution might look something like this: +If you're using Visual Studio for Mac the NUnit templates extension can't be used. This guide assumes that you have a +solution with either a PCL or a Shared project and a number of platform specific projects. It doesn't matter if you're +using Xamarin.Forms or Xamarin.iOS/Xamarin.Android directly. Your solution might look something like this: ```none Project Solution @@ -11,7 +13,9 @@ Project Solution ## Shared Test Project -First, create a new PCL that holds your shared testing code, so the test code doesn't end up in production builds. Right Click on the Project Solution and Add a new project using the Cross-Platform Shared Library Template. Use Project.Tests as a name. Afterwards, your solution should look like this: +First, create a new PCL that holds your shared testing code, so the test code doesn't end up in production builds. Right +Click on the Project Solution and Add a new project using the Cross-Platform Shared Library Template. Use Project.Tests +as a name. Afterwards, your solution should look like this: ```none Project Solution @@ -21,14 +25,18 @@ Project Solution ...Project.Tests (Holds your testing code) ``` -Edit the references of the newly created test project so that it contains a reference to the standard PCL. Afterwards, add a NuGet dependency on NUnit by right-clicking on Project.Tests and selection Add -> Add NuGet Package. +Edit the references of the newly created test project so that it contains a reference to the standard PCL. Afterwards, +add a NuGet dependency on NUnit by right-clicking on Project.Tests and selection Add -> Add NuGet Package. > [!NOTE] -> Ensure you reference the same version of NUnit as the version of nunit.xamarin you are using. e.g. If you are using nunit.xamarin 3.0.1, add the v3.0.1 NUnit NuGet package. Afterwards, your test project is ready. +> Ensure you reference the same version of NUnit as the version of nunit.xamarin you are using. e.g. If you are +> using nunit.xamarin 3.0.1, add the v3.0.1 NUnit NuGet package. Afterwards, your test project is ready. ## Platform runners -In order to run the tests it's necessary to create a project for each platform you'd like to support (iOS, Android and so on). Do so using the standard Xamarin templates for new platform projects. It's probably sensible to use a naming scheme like Project.Tests.iOS for the individual test projects do keep your solution structured. +In order to run the tests it's necessary to create a project for each platform you'd like to support (iOS, Android and +so on). Do so using the standard Xamarin templates for new platform projects. It's probably sensible to use a naming +scheme like Project.Tests.iOS for the individual test projects do keep your solution structured. ```none Project Solution @@ -40,9 +48,14 @@ Project Solution ...Project.Tests.Android ``` -The NUnit.Xamarin runners are built using Xamarin.Forms, so you need to add NUnit, NUnit.Xamarin and Xamarin.Forms as NuGet dependencies to the newly created projects. It's also necessary to add a reference to the shared test project containing the tests. +The NUnit.Xamarin runners are built using Xamarin.Forms, so you need to add NUnit, NUnit.Xamarin and Xamarin.Forms as +NuGet dependencies to the newly created projects. It's also necessary to add a reference to the shared test project +containing the tests. -If you've followed the steps above, you can now replace the AppDelegate.cs or MainActivity.cs with the code shown below. Since your tests are not in the same assembly as the runner it's a good idea to create a canary test class in the Shared Test Projects that you can use to reference the test assembly explicitly. In the example below, the name of this class is MyTest.cs. +If you've followed the steps above, you can now replace the AppDelegate.cs or MainActivity.cs with the code shown below. +Since your tests are not in the same assembly as the runner it's a good idea to create a canary test class in the Shared +Test Projects that you can use to reference the test assembly explicitly. In the example below, the name of this class +is MyTest.cs. ## Android diff --git a/docs/articles/xamarin-runners/Getting-Started-in-Visual-Studio.md b/docs/articles/xamarin-runners/Getting-Started-in-Visual-Studio.md index abbcbe5e6..80db48ff4 100644 --- a/docs/articles/xamarin-runners/Getting-Started-in-Visual-Studio.md +++ b/docs/articles/xamarin-runners/Getting-Started-in-Visual-Studio.md @@ -1,15 +1,21 @@ # Getting Started In Visual Studio -The easiest way to get started is to install the [NUnit Templates extension for Visual Studio](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.NUnitTemplatesforVisualStudio). It will add project templates for the various Xamarin platforms. +The easiest way to get started is to install the [NUnit Templates extension for Visual +Studio](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.NUnitTemplatesforVisualStudio). It will add +project templates for the various Xamarin platforms. -For more general information, see [Testing Xamarin Projects using NUnit 3](https://alteridem.net/2015/12/21/testing-xamarin-projects-using-nunit-3/). +For more general information, see [Testing Xamarin Projects using NUnit +3](https://alteridem.net/2015/12/21/testing-xamarin-projects-using-nunit-3/). ## Getting started In your solution; -1. Add new test projects to your solution. These project types are included in the [NUnit Templates Extension](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.NUnitTemplatesforVisualStudio): `NUnit 3 Test Project (Android)`. `NUnit 3 Test Project (iOS)`, `NUnit 3 Test Project (Universal Windows)` -2. Write your unit tests in this project, in a portable project, or in a shared project, referencing the project with the tests. +1. Add new test projects to your solution. These project types are included in the [NUnit Templates + Extension][ExtensionLink]: `NUnit 3 Test Project (Android)`. `NUnit 3 Test Project (iOS)`, `NUnit 3 Test Project + (Universal Windows)` +2. Write your unit tests in this project, in a portable project, or in a shared project, referencing the project with + the tests. 3. Build and run the tests on your device or emulator If your tests are in a separate portable project, note that: @@ -20,7 +26,8 @@ If your tests are in a separate portable project, note that: nunit.AddTestAssembly(typeof(MyTests).Assembly); ``` -* Your portable project must reference the same NUnit Framework version as your nunit.xamarin version, e.g. if using nunit.xamarin 3.01, reference nunit.framework 3.01. +* Your portable project must reference the same NUnit Framework version as your nunit.xamarin version, e.g. if using + nunit.xamarin 3.01, reference nunit.framework 3.01. The startup code for each platform is as follows; @@ -175,3 +182,5 @@ protected override void OnLaunched(LaunchActivatedEventArgs e) // } ``` + +[ExtensionLink]: https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.NUnitTemplatesforVisualStudio diff --git a/docs/articles/xamarin-runners/index.md b/docs/articles/xamarin-runners/index.md index da2c96b9f..1f0568fe9 100644 --- a/docs/articles/xamarin-runners/index.md +++ b/docs/articles/xamarin-runners/index.md @@ -4,7 +4,8 @@ uid: xamarinrunners # NUnit Xamarin Runners -The NUnit Xamarin Runners provide NUnit 3 test runners for Xamarin and mobile devices. See [Testing Xamarin projects using NUnit 3](https://alteridem.net/2015/12/21/testing-xamarin-projects-using-nunit-3/) for more general information. +The NUnit Xamarin Runners provide NUnit 3 test runners for Xamarin and mobile devices. See [Testing Xamarin projects +using NUnit 3](https://alteridem.net/2015/12/21/testing-xamarin-projects-using-nunit-3/) for more general information. ## Options diff --git a/docs/index.md b/docs/index.md index b18b5e555..95e51e032 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,13 +1,15 @@ # NUnit Documentation Site -This web site contains the documentation for all active NUnit projects as well as developer documentation for those working on NUnit or wishing to do so. +This web site contains the documentation for all active NUnit projects as well as developer documentation for those +working on NUnit or wishing to do so. ## User Documentation * [NUnit](xref:intro) covers the core tools of NUnit, including the framework, NUnitLite, and the console runner. * [NUnit VS Adapter](xref:vstestadapterinstallation) covers the test adapters for Visual Studio and .Net. * [NUnit Analyzers](xref:nunitanalyzers) covers the NUnit Analyzers. -* [NUnit VS Test Generator](xref:vstestgenerator) covers the Visual Studio extension for generating tests in both NUnit V2 and V3. +* [NUnit VS Test Generator](xref:vstestgenerator) covers the Visual Studio extension for generating tests in both NUnit + V2 and V3. * [NUnit Xamarin Runners](xref:xamarinrunners) covers the NUnit test runners for Xamarin and mobile devices. * [NUnit Engine](xref:nunitengine) covers the NUnit Engine, the central component all test runners are built around.