Documentation on provider specification tests (#3665)

Closes #3664

entity-framework/core/providers/writing-a-provider.md

@@ -33,3 +33,16 @@ For example:
 * `Microsoft.EntityFrameworkCore.SqlServer`
 * `Npgsql.EntityFrameworkCore.PostgreSQL`
 * `EntityFrameworkCore.SqlServerCompact40`
+
+## The EF Core specification tests
+
+EF Core provides a specification test suite project, which all providers are encouraged to implement. The project contains tests which ensure that the provider function correctly, e.g. by executing various LINQ queries and ensuring that the correct results are returned. This test suite is used by EF Core's own providers (SQL Server, SQLite, Cosmos...) as the primary regression testing mechanism, and are continuously updated and improved as new features are added to EF Core. By implementing these tests for other, 3rd-party providers, you can ensure that your database provider works correctly and implements all the latest EF Core features. Note that the test suite is quite large, as it covers the entire EF Core feature set; you don't have to implement everything - it's perfectly fine to cherry-pick certain test classes, and incrementally improve your coverage with time.
+
+To start using the specification tests, follow these steps:
+
+* Create an xunit test project in your provider solution. We suggest the name `<Provider>.FunctionalTests` for consistency, so if your provider is called `AcmeSoftware.EntityFramework.AcmeDb`, call the test project `AcmeSoftware.EntityFramework.AcmeDb.FunctionalTests`.
+* From your new test project, reference the EF specification tests, which are published as regular Nuget packages. For relational providers, the specification test suite is [Microsoft.EntityFrameworkCore.Relational.Specification.Tests](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.Relational.Specification.Tests), for non-relational provider, use [Microsoft.EntityFrameworkCore.Specification.Tests](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.Specification.Tests)).
+* Pick a test class from the EF specification tests, and extend it from a corresponding test class in your own project. The available test classes can be seen in the [EF source code](https://github.com/dotnet/efcore/tree/main/test/EFCore.Relational.Specification.Tests). Your class should be named based on the EF test class, with your provider name inserted where appropriate. For example, `NorthwindWhereQueryRelationalTestBase` (which is a good place to start), would be extended by `NorthwindWhereQueryAcmeDbTest`.
+* At the very beginning, you'll have a bit of test infrastructure to implement - once that's done once, things will become easier. For example, for `NorthwindWhereQueryAcmeDbTest` you'll have to implement `NorthwindWhereQueryAcmeDbFixture`, which will require a `AcmeDbNorthwindTestStoreFactory`, which would need a Northwind.sql script to seed the AcmeDb version of the Northwind database. We strongly suggest keeping another EF Core provider's test suite open nearby, and following what it does. For example, the SQL Server implementation of the specification tests is visible [here](https://github.com/dotnet/efcore/tree/main/test/EFCore.SqlServer.FunctionalTests).
+* Once the infrastructure for the test class is done, you'll start seeing some green tests on it. You can investigate the failing tests, or temporarily skip them for later investigation. In this way you can add more and more test classes.
+* At some point, when you've extended most of the upstream test classes, you can also create `AcmeDbComplianceTest`, which extends `RelationalComplianceTestBase`. This test class will fail if your own test project doesn't extend an EF Core test class - it's a great way to know whether your test suite is complete, and also whether EF added a new test class in a new version. You can also opt out of extending specific test classes if they're not ready (or not relevant).