‫راهنمای مهاجرت به xUnit v3

• حل وابستگی‌ها (Dependency Resolution): در نسخه جدید، تمام وابستگی‌ها در زمان کامپایل (Build Time) توسط کامپایلر حل می‌شوند، نه در زمان اجرا (Runtime). این امر از بروز بسیاری از خطاهای مرتبط با بارگذاری Assemblyها در زمان اجرای تست‌ها جلوگیری می‌کند.
• ایزوله‌سازی فرآیندها (Process Isolation): تست‌ها اکنون در فرآیندهای مجزا اجرا می‌شوند که ایزوله‌سازی بسیار قوی‌تری نسبت به رویکرد Application Domain در نسخه ۲ فراهم می‌کند. این یعنی تست‌ها کمتر روی یکدیگر تأثیر منفی می‌گذارند.
• اجرای ساده و مستقیم: شما می‌توانید فایل خروجی پروژه تست خود را مستقیماً اجرا کنید و دیگر نیازی به ابزارهای جانبی (Runner) برای اجرای تست‌ها ندارید.

• برای ‎.NET Framework: یک فایل .exe که مستقیماً تست‌ها را اجرا می‌کند.
• برای ‎.NET (Core): یک فایل .dll حاوی تست‌ها به همراه یک فایل راه‌انداز (Stub) با پسوند .exe.

// این Attribute خروجی‌های Console.WriteLine را ثبت می‌کند
[assembly: Xunit.CaptureConsole]

// این Attribute خروجی‌های Debug.WriteLine و Trace.WriteLine را ثبت می‌کند
[assembly: Xunit.CaptureTrace]

// AssemblyFixture را در سطح Assembly تعریف می‌کنیم
[assembly: Xunit.AssemblyFixture(typeof(DatabaseFixture))]

// کلاس فیکسچر که باید یک بار ساخته و در پایان از بین برود
public class DatabaseFixture : IDisposable
{
    public SqlConnection Db { get; private set; }

    public DatabaseFixture()
    {
        Db = new SqlConnection("MyConnectionString");
        // ... کد مربوط به راه‌اندازی و مقداردهی اولیه دیتابیس ...
    }

    public void Dispose()
    {
        // ... کد مربوط به پاک‌سازی دیتابیس پس از اتمام تمام تست‌ها ...
        Db.Dispose();
    }
}

// کلاس تست اول که از فیکسچر استفاده می‌کند
public class DatabaseTestClass1
{
    private readonly DatabaseFixture _fixture;

    // فیکسچر از طریق Constructor تزریق می‌شود
    public DatabaseTestClass1(DatabaseFixture fixture)
    {
        _fixture = fixture;
    }

    [Fact]
    public void Test1()
    {
        // استفاده از _fixture.Db
    }
}

// کلاس تست دوم نیز از همان نمونه فیکسچر استفاده می‌کند
public class DatabaseTestClass2
{
    private readonly DatabaseFixture _fixture;

    public DatabaseTestClass2(DatabaseFixture fixture)
    {
        _fixture = fixture;
    }
    // ...
}

• نسخه‌های دات‌نت: xUnit v3 به حداقل نسخه‌های زیر نیاز دارد:
• .NET Framework 4.7.2 یا بالاتر
• .NET 8 یا بالاتر
• پروژه‌های SDK-style: پروژه تست شما حتماً باید از فرمت جدید و مدرن SDK-style (.csproj) استفاده کند. اگر هنوز از فرمت قدیمی استفاده می‌کنید، ابتدا باید پروژه خود را به این فرمت تبدیل کنید.

<PackageReference Include="xunit" Version="2.x.x" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.x.x" />
<PackageReference Include="xunit.analyzers" Version="0.x.x" />

<PackageReference Include="xunit.v3" Version="0.x.x" />
<PackageReference Include="xunit.runner.visualstudio" Version="3.x.x" />
<PackageReference Include="xunit.analyzers" Version="1.x.x" />

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <OutputType>Exe</OutputType> <IsPackable>false</IsPackable>
  </PropertyGroup>

  </Project>

dotnet restore
dotnet build

# اجرای مستقیم فایل اجرایی
./bin/Debug/net8.0/YourTestProject.exe

# یا اجرای از طریق دستور dotnet run
dotnet run

# می‌توانید آرگومان‌های خط فرمان xUnit را نیز به آن پاس دهید
dotnet run -- -xml results.xml

• استفاده از ValueTask برای تست‌های async: برای بهبود عملکرد در تست‌های آسنکرون، توصیه می‌شود به جای Task از ValueTask استفاده کنید. این کار در سناریوهایی که متد به صورت همزمان (Synchronously) کامل می‌شود، از تخصیص حافظه روی Heap جلوگیری می‌کند.

[Fact]
public async ValueTask MyAsyncTest()
{
    // ...
}

• بهره‌گیری از Assertionهای جدید: نسخه ۳ شامل متدها و overloadهای جدیدی برای Assert است. مستندات رسمی را برای آشنایی با آن‌ها بررسی کنید.
• سازماندهی بهینه تست‌ها: با مدل اجرایی جدید، می‌توانید پروژه‌های تست بزرگ را به چندین پروژه اجرایی کوچک‌تر تقسیم کنید. این کار به شما امکان موازی‌سازی بهتر و مدیریت ساده‌تر تست‌ها را می‌دهد.
• تأثیر بر روی CI/CD: در پایپ‌لاین‌های CI/CD، قبلاً از دستور dotnet test استفاده می‌کردید. این دستور همچنان با وجود پکیج xunit.runner.visualstudio کار می‌کند. اما اکنون یک گزینه جدید و قدرتمند دیگر نیز دارید: اجرای مستقیم فایل .exe خروجی. این روش می‌تواند سریع‌تر باشد و کنترل بیشتری بر روی فرآیند اجرای تست‌ها به شما بدهد.