---
title: Create isolated integration tests
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

Isolated integration tests are [automated tests](https://docs.kentico.com/documentation/developers-and-admins/customization/write-automated-tests.md) that work with database objects within their own separate database. A clean database instance is created for each test (using the default Xperience installation scripts) and then deleted after the test run. Isolated integration tests are significantly slower than [unit tests with faked data](https://docs.kentico.com/documentation/developers-and-admins/customization/write-automated-tests/create-unit-tests.md). If you can use a shared database and clean up manually, see [Create integration tests with a connection string](https://docs.kentico.com/documentation/developers-and-admins/customization/write-automated-tests/create-integration-tests.md).

All test classes with isolated integration tests must inherit from the **IsolatedIntegrationTests** base class (provided by the _CMS.Tests_ library). The base class automatically performs database initialization before test runs and cleanup after.

> **Note:** **Requirements**
>
> To use isolated integration tests, you need **Microsoft SQL Server Express LocalDB** installed. LocalDB is automatically included in Visual Studio or Microsoft SQL Server installations.
>
> If you want to run isolated integration tests in environments without native LocalDB support (e.g., Linux or Docker containers), see [Run without LocalDB](#run-without-localdb).

## Create isolated integration tests

1. Open the solution containing your [test project](https://docs.kentico.com/documentation/developers-and-admins/customization/write-automated-tests/set-up-test-projects.md) in your IDE.

2. Make the test class inherit from the **IsolatedIntegrationTests** base class.

   ```csharp title="Isolated integration test class"
   using CMS.Tests;

   using NUnit.Framework;

   [TestFixture]
   public class IsolatedIntegrationTestsExampleTests : IsolatedIntegrationTests
   {
       [Test]
       public void TestMethod()
       {
           // Test code that creates or modifies database objects
           // The database is automatically cleaned up after the test
       }
   }
   ```

3. Write the required isolated integration test methods. You do not need to manually clean up test data, the framework handles this automatically.

### Share a database across a fixture

By default, a new database is created and destroyed for **each test** in the fixture. For test classes where all tests share a common setup and the database can be reused, apply the **SharedDatabaseForAllTests** attribute to improve performance:

```csharp title="Shared database for all tests"
using CMS.Tests;

using NUnit.Framework;

[TestFixture]
[SharedDatabaseForAllTests]
public class IsolatedIntegrationTestsWithSharedDatabaseExampleTests : IsolatedIntegrationTests
{
    [OneTimeSetUp]
    public void OneTimeSetUp()
    {
        // Test data initialization shared by all tests in the fixture.
    }

    [Test]
    public void FirstTest()
    {
        // Test code that accesses the database.
    }

    [Test]
    public void SecondTest()
    {
        // Test code that accesses the database.
    }
}
```

With `[SharedDatabaseForAllTests]`, the database is created once before the first test in the class and deleted after the last test completes.

## Configuration options

Configure the following keys under `appSettings` in one of the supported test configuration sources (`app.config` in your test project, or global `Tests.config` in the solution root):








```xml title="app.config with custom settings"
<configuration>
    <appSettings>
        <add key="CMSTestDatabaseFolderPath" value="C:\TestDatabases" />
        <add key="CMSTestDatabaseInstanceName" value="(LocalDB)\MSSQLLocalDB" />
    </appSettings>
</configuration>
```

## Run without LocalDB

By default, Xperience uses a LocalDB instance to automatically manage databases for isolated integration tests via integrated security authentication.

In environments where SQL Express LocalDB or integrated security authentication is not supported or available (such as Linux distributions or Docker containers), set an alternative connection string via the **CMSTestIsolatedAltConnectionString** application setting.

The connection string must specify the server instance intended to host test databases together with authentication credentials for a user with full access (able to create and manage databases):

```xml title="app.config for environments without LocalDB"
<configuration>
    <appSettings>
        <add key="CMSTestIsolatedAltConnectionString"
             value="Data Source=localhost;Initial Catalog=##DBNAME##;Integrated Security=False;User ID=sa;Password=yourpassword;Connection Timeout=240;Encrypt=False;" />
        <add key="CMSTestDatabaseFolderPath" value="/var/testdatabases" />
    </appSettings>
</configuration>
```

The connection string must contain the `##DBNAME##` placeholder in place of the database name. The system dynamically resolves this value at runtime to create and dispose of a database for the given test run.

The target SQL Server instance must be running on the same machine and have read-write access to the test databases folder specified via `CMSTestDatabaseFolderPath`.

> **Note:** When running tests in containerized environments, the folder configured in `CMSTestDatabaseFolderPath` must be accessible to both the test runner process and the SQL Server process. If the path is not shared or SQL Server cannot write to it, isolated integration tests fail during database file creation.