Restructure README files for inclusion in nuget packages
This commit is contained in:
Andrew Arnott
Родитель
fabda9e07d
Коммит
2f4794d21c
55
README.md
55
README.md
|
|
@ -1,63 +1,26 @@
|
|||
# Visual Studio SDK Test Framework
|
||||
|
||||
[](https://nuget.org/packages/Microsoft.VisualStudio.Sdk.TestFramework)
|
||||
[](https://dev.azure.com/azure-public/vside/_build/latest?definitionId=45&branchName=main)
|
||||
[](https://gitter.im/Microsoft/extendvs)
|
||||
|
||||
## Microsoft.VisualStudio.Sdk.TestFramework
|
||||
|
||||
[](https://nuget.org/packages/Microsoft.VisualStudio.Sdk.TestFramework)
|
||||
|
||||
The VS SDK Test Framework is a library for your unit tests that exercise VS code to use
|
||||
so that certain core VS functionality works outside the VS process so your unit tests can function.
|
||||
For example, `ThreadHelper` and obtaining global services from the static `ServiceProvider`
|
||||
tend to fail in unit tests without this library installed.
|
||||
|
||||
## Consuming this test framework
|
||||
[Learn more about this package](src/Microsoft.VisualStudio.Sdk.TestFramework/README.md).
|
||||
|
||||
**Microsoft Internal users**: See [specific guidance if consuming within the `VS` repo](doc/vs_repo.md).
|
||||
## Microsoft.VisualStudio.Sdk.TestFramework.Xunit
|
||||
|
||||
1. Install the NuGet package [Microsoft.VisualStudio.Sdk.TestFramework](https://nuget.org/packages/Microsoft.VisualStudio.Sdk.TestFramework),
|
||||
or for Xunit test projects, install the more specific [Microsoft.VisualStudio.Sdk.TestFramework.Xunit](https://nuget.org/packages/Microsoft.VisualStudio.Sdk.TestFramework.Xunit) package
|
||||
[](https://nuget.org/packages/Microsoft.VisualStudio.Sdk.TestFramework.Xunit)
|
||||
|
||||
1. Make sure your unit test project generates the required binding redirects by adding these two properties to your project file:
|
||||
This package contains functionality applicable when using Xunit as your test framework.
|
||||
|
||||
```xml
|
||||
<AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
|
||||
<GenerateBindingRedirectsOutputType>true</GenerateBindingRedirectsOutputType>
|
||||
```
|
||||
|
||||
1. Apply some changes to your test project source as appropriate given the test framework you're already using:
|
||||
|
||||
* [Xunit](doc/xunit.md)
|
||||
* [MSTest](doc/mstest.md)
|
||||
|
||||
### Main Thread considerations
|
||||
|
||||
This library will create a mocked up UI thread, such that `ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync()`
|
||||
can switch to it. Your unit tests do *not* start on this mocked up UI thread. If your product code contains checks
|
||||
that it is invoked on the UI thread (e.g. `ThreadHelper.ThrowIfNotOnUIThread()`) your test method should look like this:
|
||||
|
||||
```cs
|
||||
[TestMethod] // or [Fact]
|
||||
public async Task VerifyWeDoSomethingGood()
|
||||
{
|
||||
await ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync();
|
||||
MyVSPackage.DoSomethingAwesome();
|
||||
}
|
||||
```
|
||||
|
||||
### Built in service mocks
|
||||
|
||||
There are a collection of "base services" that the VSSDKTestFx comes with mocks for.
|
||||
Calling `GlobalServiceProvider.AddService` for any of these will result in an `InvalidOperationException` being thrown claiming
|
||||
that the service is already added.
|
||||
|
||||
These services include:
|
||||
|
||||
* `SVsActivityLog`
|
||||
Customize behavior by acquiring the service and downcasting to the `MockVsActivityLog` type, then setting the `ForwardTo` property.
|
||||
* `OLE.Interop.IServiceProvider`
|
||||
* `SVsTaskSchedulerService`
|
||||
* `SVsUIThreadInvokerPrivate`
|
||||
|
||||
More may be added and can be found in [source code](https://github.com/microsoft/vssdktestfx/blob/main/src/Microsoft.VisualStudio.Sdk.TestFramework/GlobalServiceProvider.cs#L217-L224).
|
||||
[Learn more about this package](src/Microsoft.VisualStudio.Sdk.TestFramework.Xunit/README.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,18 @@
|
|||
# Microsoft.VisualStudio.Sdk.TestFramework.Xunit
|
||||
|
||||
This package contains functionality applicable when using Xunit as your test framework.
|
||||
|
||||
For *each* of your test classes that rely on VS mocked services, apply the `Collection` attribute and add a parameter and statement to your constructor:
|
||||
|
||||
```csharp
|
||||
using Microsoft.VisualStudio.Sdk.TestFramework;
|
||||
|
||||
[Collection(MockedVS.Collection)]
|
||||
public class YourTestClass
|
||||
{
|
||||
public TestFrameworkTests(GlobalServiceProvider sp)
|
||||
{
|
||||
sp.Reset();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
# Microsoft.VisualStudio.Sdk.TestFramework
|
||||
|
||||
The VS SDK Test Framework is a library for your unit tests that exercise VS code to use
|
||||
so that certain core VS functionality works outside the VS process so your unit tests can function.
|
||||
For example, `ThreadHelper` and obtaining global services from the static `ServiceProvider`
|
||||
tend to fail in unit tests without this library installed.
|
||||
|
||||
## Consuming this test framework
|
||||
|
||||
**Microsoft Internal users**: See [specific guidance if consuming within the `VS` repo](https://github.com/microsoft/vssdktestfx/blob/main/doc/vs_repo.md).
|
||||
|
||||
1. Install the NuGet package [Microsoft.VisualStudio.Sdk.TestFramework](https://nuget.org/packages/Microsoft.VisualStudio.Sdk.TestFramework),
|
||||
or for Xunit test projects, install the more specific [Microsoft.VisualStudio.Sdk.TestFramework.Xunit](https://nuget.org/packages/Microsoft.VisualStudio.Sdk.TestFramework.Xunit) package
|
||||
|
||||
1. Make sure your unit test project generates the required binding redirects by adding these two properties to your project file:
|
||||
|
||||
```xml
|
||||
<AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
|
||||
<GenerateBindingRedirectsOutputType>true</GenerateBindingRedirectsOutputType>
|
||||
```
|
||||
|
||||
1. Apply some changes to your test project source as appropriate given the test framework you're already using:
|
||||
|
||||
* [Xunit](https://github.com/microsoft/vssdktestfx/blob/main/doc/xunit.md)
|
||||
* [MSTest](https://github.com/microsoft/vssdktestfx/blob/main/doc/mstest.md)
|
||||
|
||||
### Main Thread considerations
|
||||
|
||||
This library will create a mocked up UI thread, such that `ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync()`
|
||||
can switch to it. Your unit tests do *not* start on this mocked up UI thread. If your product code contains checks
|
||||
that it is invoked on the UI thread (e.g. `ThreadHelper.ThrowIfNotOnUIThread()`) your test method should look like this:
|
||||
|
||||
```cs
|
||||
[TestMethod] // or [Fact]
|
||||
public async Task VerifyWeDoSomethingGood()
|
||||
{
|
||||
await ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync();
|
||||
MyVSPackage.DoSomethingAwesome();
|
||||
}
|
||||
```
|
||||
|
||||
### Built in service mocks
|
||||
|
||||
There are a collection of "base services" that the VSSDKTestFx comes with mocks for.
|
||||
Calling `GlobalServiceProvider.AddService` for any of these will result in an `InvalidOperationException` being thrown claiming
|
||||
that the service is already added.
|
||||
|
||||
These services include:
|
||||
|
||||
* `SVsActivityLog`
|
||||
Customize behavior by acquiring the service and downcasting to the `MockVsActivityLog` type, then setting the `ForwardTo` property.
|
||||
* `OLE.Interop.IServiceProvider`
|
||||
* `SVsTaskSchedulerService`
|
||||
* `SVsUIThreadInvokerPrivate`
|
||||
|
||||
More may be added and can be found in [source code](https://github.com/microsoft/vssdktestfx/blob/main/src/Microsoft.VisualStudio.Sdk.TestFramework/GlobalServiceProvider.cs#L214-L221).
|
||||
Загрузка…
Ссылка в новой задаче