---
name: generate-unit-tests
description: >
  Generates unit tests for C# classes using xUnit, FluentAssertions,
  and NSubstitute. Use when asked to write unit tests, create a test class,
  add tests, cover code with tests, test this method, or write specs for
  a class. Follows AAA pattern (Arrange, Act, Assert).
inputHint: "[ClassName or paste class content]"
---

# Skill: Generowanie testów jednostkowych (.NET)

## Stack testowy
- **Framework:** xUnit 2
- **Asercje:** FluentAssertions 6
- **Mocki:** NSubstitute 5
- **Wzorzec:** AAA (Arrange / Act / Assert)

## Lokalizacja pliku testowego
Umieść plik testowy w projekcie `[NazwaProjektu].Tests`, w podkatalogu
odpowiadającym testowanej klasie. Np. dla `OrderService` z
`Application/Orders/` → plik idzie do `Tests/Application/Orders/`.

## Konwencja nazewnictwa
- Klasa testowa: `[NazwaKlasy]Tests` (np. `OrderServiceTests`)
- Metoda testowa: `[NazwaMetody]_[Scenariusz]_[OczekiwanyWynik]`
  Przykład: `CancelOrder_WhenAlreadyCancelled_ThrowsInvalidOperationException`

## Zasady tworzenia testów

1. **Jeden Assert per test** – jeśli testujesz wiele rzeczy, rozdziel na
   osobne metody.

2. **Sekcje AAA z komentarzami:**
   ```csharp
   // Arrange
   // Act
   // Assert
   ```

3. **Mocki tylko przez NSubstitute:**
   ```csharp
   var repo = Substitute.For();
   repo.GetByIdAsync(orderId).Returns(order);
   ```

4. **Asercje przez FluentAssertions:**
   ```csharp
   result.Should().NotBeNull();
   result.Status.Should().Be(OrderStatus.Cancelled);
   await act.Should().ThrowAsync();
   ```

5. **Nie testuj implementacji – testuj zachowanie:**
   - Złe: `service._repository.Received(1).Save(...)` (weryfikacja internals)
   - Dobre: `result.Status.Should().Be(OrderStatus.Cancelled)`

6. **Happy path + edge cases + błędy:**
   Dla każdej metody wygeneruj przynajmniej:
   - Test dla poprawnego scenariusza (happy path)
   - Test dla niepoprawnych danych wejściowych (np. null, pusta lista)
   - Test dla wyjątku domenowego jeśli metoda go rzuca

## Szablon klasy testowej
Użyj szablonu z pliku [test-class-template.cs](./templates/test-class-template.cs).

using FluentAssertions;
using NSubstitute;
using Xunit;

namespace [Namespace].Tests.[Layer].[Feature];

public class [ClassName]Tests
{
    // Zależności (moki)
    private readonly I[Dependency] _dependency;

    // Testowana klasa
    private readonly [ClassName] _sut;

    public [ClassName]Tests()
    {
        _dependency = Substitute.For<I[Dependency]>();
        _sut = new [ClassName](_dependency);
    }

    [Fact]
    public async Task [MethodName]_[Scenario]_[ExpectedResult]()
    {
        // Arrange
        var input = [setup input];
        _dependency.[Method]([args]).Returns([returnValue]);

        // Act
        var result = await _sut.[MethodName](input);

        // Assert
        result.Should().NotBeNull();
        result.[Property].Should().Be([expectedValue]);
    }

    [Fact]
    public async Task [MethodName]_WhenNullInput_ThrowsArgumentNullException()
    {
        // Arrange
        // (nothing to set up)

        // Act
        var act = async () => await _sut.[MethodName](null!);

        // Assert
        await act.Should().ThrowAsync<ArgumentNullException>()
            .WithParameterName("[paramName]");
    }
}

---
name: scaffold-api-endpoint
description: >
  Scaffolds a complete API endpoint for a .NET Clean Architecture project.
  Generates: MediatR command or query, handler, FluentValidation validator,
  and minimal API endpoint registration. Use when asked to add an endpoint,
  create a new API route, add a controller action, implement a feature,
  or scaffold a REST endpoint.
inputHint: "[HTTP method] [route] – e.g. POST /orders/{id}/cancel"
---

# Skill: Scaffolding endpointu API (.NET Clean Architecture)

## Co generujemy
Dla każdego nowego endpointu tworzymy:
1. **Command lub Query** (Application/[Feature]/Commands/ lub /Queries/)
2. **Handler** (w tym samym katalogu co command/query)
3. **Validator** (Application/[Feature]/Validators/)
4. **Endpoint** (API/Endpoints/ lub rejestracja w istniejącym kontrolerze)

## Zasady

### Command vs Query
- **Command** (POST, PUT, PATCH, DELETE) → modyfikuje stan, zwraca `Result` lub `Result`
- **Query** (GET) → tylko czytanie, zwraca `Result`

### Konwencje nazewnictwa
- Command: `[Akcja][Zasób]Command` (np. `CancelOrderCommand`)
- Handler: `[Akcja][Zasób]CommandHandler`
- Query: `Get[Zasób]Query`, `Get[Zasób]ByIdQuery`
- Validator: `[Akcja][Zasób]CommandValidator`

### Obsługa błędów
- Używaj `Result` z Ardalis.Result lub własnego Result type
- Nie rzucaj wyjątków domenowych z handlera – zwracaj `Result.NotFound()`,
  `Result.Forbidden()`, `Result.Invalid()`
- W endpoincie mapuj Result na odpowiedni HTTP status code

### Walidacja
- Każdy command ma odpowiadający validator we FluentValidation
- Validator jest rejestrowany przez `AddValidatorsFromAssembly` – nie ręcznie
- Zasada: waliduj tylko to co możesz zwalidować bez dostępu do bazy

## Szablony
- Komenda: [command.cs](./templates/command.cs)
- Handler: [handler.cs](./templates/handler.cs)
- Validator: [validator.cs](./templates/validator.cs)
- Endpoint: [endpoint.cs](./templates/endpoint.cs)

## Po wygenerowaniu
Przypomnij użytkownikowi o:
1. Rejestracji endpointu w `Program.cs` lub `RouteGroupExtensions`
2. Dodaniu migracji EF jeśli zmiana dotyczy encji
3. Napisaniu testu integracyjnego dla nowego endpointu

using Ardalis.Result;
using MediatR;

namespace [ProjectName].Application.[Feature].Commands;

/// <summary>
/// [Opis co robi komenda].
/// </summary>
public record [CommandName](
    [Type] [Property1],
    [Type] [Property2]
) : IRequest<Result<[ReturnType]>>;

using Ardalis.Result;
using MediatR;

namespace [ProjectName].Application.[Feature].Commands;

/// <summary>
/// Handler dla [CommandName].
/// </summary>
public class [CommandName]Handler(
    I[Repository] repository
) : IRequestHandler<[CommandName], Result<[ReturnType]>>
{
    public async Task<Result<[ReturnType]>> Handle(
        [CommandName] request,
        CancellationToken cancellationToken)
    {
        var entity = await repository.GetByIdAsync(
            request.[Id], cancellationToken);

        if (entity is null)
            return Result.NotFound();

        // logika biznesowa

        await repository.SaveChangesAsync(cancellationToken);

        return Result.Success([returnValue]);
    }
}

using FluentValidation;

namespace [ProjectName].Application.[Feature].Commands;

public class [CommandName]Validator : AbstractValidator<[CommandName]>
{
    public [CommandName]Validator()
    {
        RuleFor(x => x.[Property1])
            .NotEmpty()
            .WithMessage("[Property1] jest wymagane.");

        RuleFor(x => x.[Property2])
            .GreaterThan(0)
            .WithMessage("[Property2] musi być większe od zera.");
    }
}

using Ardalis.Result.AspNetCore;
using MediatR;

namespace [ProjectName].API.Endpoints.[Feature];

public static class [FeatureName]Endpoints
{
    public static RouteGroupBuilder Map[FeatureName]Endpoints(
        this RouteGroupBuilder group)
    {
        group.MapPost("/{id}/[action]", async (
            [Type] id,
            [CommandName] command,
            ISender sender,
            CancellationToken ct) =>
        {
            var result = await sender.Send(
                command with { Id = id }, ct);
            return result.ToMinimalApiResult();
        })
        .WithName("[EndpointName]")
        .WithSummary("[Krótki opis endpointu]")
        .Produces<[ReturnType]>(StatusCodes.Status200OK)
        .ProducesProblem(StatusCodes.Status404NotFound)
        .RequireAuthorization();

        return group;
    }
}

---
name: create-ef-migration
description: >
  Guides creation of Entity Framework Core migrations for .NET projects.
  Use when asked to add a migration, create a database migration, update
  the schema, add an index, modify a table, or run EF Core migration.
inputHint: "[migration name describing the change, e.g. AddOrderStatusIndex]"
---

# Skill: Tworzenie migracji EF Core

## Konwencja nazewnictwa migracji
Nazwa migracji powinna opisywać zmianę (nie być datą ani numerem):
- ✅ `AddOrderStatusIndex`
- ✅ `RenameCustomerEmailColumn`
- ✅ `CreateProductsTable`
- ❌ `Migration001`
- ❌ `Update`
- ❌ `FixBug`

## Komendy

### Dodanie nowej migracji
```bash
dotnet ef migrations add [NazwaMigracji] \
  --project src/[ProjectName].Infrastructure \
  --startup-project src/[ProjectName].API \
  --output-dir Migrations
```

### Zastosowanie migracji
```bash
dotnet ef database update \
  --project src/[ProjectName].Infrastructure \
  --startup-project src/[ProjectName].API
```

### Rollback do poprzedniej migracji
```bash
dotnet ef database update [NazwaPoprzedniej] \
  --project src/[ProjectName].Infrastructure \
  --startup-project src/[ProjectName].API
```

### Usunięcie ostatniej migracji (jeśli niezastosowana)
```bash
dotnet ef migrations remove \
  --project src/[ProjectName].Infrastructure \
  --startup-project src/[ProjectName].API
```

## Checklist przed commitem migracji

Przed commitem sprawdź wygenerowany plik migracji:

1. **Indeksy** – czy dodajesz kolumnę która będzie używana w WHERE lub JOIN?
   Jeśli tak, dodaj indeks:
   ```csharp
   migrationBuilder.CreateIndex(
       name: "IX_Orders_CustomerId",
       table: "Orders",
       column: "CustomerId");
   ```

2. **Nullable vs NOT NULL** – czy nowa kolumna w istniejącej tabeli jest
   nullable lub ma wartość domyślną? Inaczej migracja nie przejdzie na
   niepustej tabeli produkcyjnej.

3. **Down() jest kompletne** – upewnij się że metoda `Down()` poprawnie
   cofa wszystkie zmiany z `Up()`. EF generuje to automatycznie, ale
   warto sprawdzić przy złożonych migracjach.

4. **Nie edytuj istniejących migracji** – jeśli migracja jest już
   zastosowana w jakimkolwiek środowisku, stwórz nową zamiast edytować.

## Ostrzeżenia
- Migracje które zmieniają nazwę kolumny przez `DropColumn` + `AddColumn`
  **tracą dane**. Użyj `RenameColumn` zamiast tego.
- Przy dodawaniu NOT NULL do istniejącej tabeli zawsze podaj
  `defaultValue` lub użyj migracji dwuetapowej.