# Test-driven development w Cursorze

URL: https://developertoolkit.ai/pl/cursor-ide/test/testing-tdd/
Description: TDD w Cursorze: zablokuj czerwone testy jako specyfikację w Gicie, implementuj do zielonego bez zmian w testach i sprawdź siłę wyroczni testami mutacyjnymi.

Test-driven development w Cursorze rozdziela specyfikację od implementacji: agent najpierw pisze czerwone testy, programista zatwierdza je i blokuje w Gicie jako kontrakt, a świeża sesja Agenta implementuje kod do zielonego bez edycji testów. Kontrola diffu testów, testy mutacyjne i wymagane bramki CI pozwalają recenzentom czytać testy zamiast każdej wygenerowanej linii.

Poproś Agenta Cursora o napisanie konwertera markdownu albo kalkulatora cen w jednym przebiegu, a dostaniesz 400 schludnych linii ukrywających błędy brzegowe. Przejrzenie 40 dokładnych asercji na starcie zajmuje minuty i zamyka zachowanie, zanim powstanie pierwsza linia implementacji. Ten przewodnik pokazuje programistom i tech leadom powtarzalną pętlę TDD w Cursorze; ogólne zasady niezależne od narzędzia opisuje [test-driven development ze wsparciem AI](/pl/method/principles/test-driven-development/).

## Pętla TDD z zablokowanym kontraktem w Cursorze

Całą pętlę trzyma jedna zasada: **testy są kontraktem i wyłącznie człowiek zmienia kontrakt.**

1. **Napisz czerwone testy i zaślepkę rzucającą wyjątek.** Zleć Agentowi napisanie testów sprawdzających dokładny wynik funkcji publicznej oraz zaślepki rzucającej `Not implemented`, aby każdy test padał z właściwego powodu przed powstaniem logiki.

2. **Przejrzyj, zacommituj i otaguj czerwony kontrakt.** Tutaj inwestujesz uwagę: sprawdź, czy oczekiwane wyniki odpowiadają intencji domenowej i wyrzuć słabe asercje (`toBeDefined`, `typeof`). Zacommituj zestaw i otaguj go (`git tag tdd-red`), aby późniejsze sprawdzenia miały stały punkt odniesienia.

3. **Implementuj do zielonego w nowym czacie z testami tylko do odczytu.** Nowa sesja usuwa zakotwiczenie z fazy pisania testów. Dodaj komendę testów do allowlisty w Run Modes (Auto-review lub Allowlist, utrzymując komendy destrukcyjne za bramką; zobacz [cursor.com/docs](https://cursor.com/docs)), aby Agent sprawnie iterował z twardym warunkiem stopu po trzech iteracjach bez postępu.

4. **Potwierdź niezmienność testów i siłę wyroczni.** Sprawdź w Gicie względem `tdd-red`, że testy pozostały nietknięte, a następnie uruchom zawężone testy mutacyjne na zmienionych plikach implementacji, by wykryć słabe asercje.

5. **Uruchom uporządkowaną bramkę przed PR lokalnie i w CI.** Wykonaj kolejno kontrolę typów, lint i testy z progami pokrycia gałęzi, a potem oprzyj decyzję o scaleniu na wynikach CI z commita PR.

### Krok 1: Zapisz specyfikację jako czerwone testy

**Prompt do skopiowania: najpierw testy, bez implementacji**

```text
Write a test suite at src/lib/markdown/__tests__/markdown-to-html.test.ts for
markdownToHtml(input: string): string. Do NOT implement the converter.

Cover one describe block each:
1. Headings h1-h6 with inline formatting
2. Paragraphs separated by blank lines
3. Emphasis (*italic*, **bold**, ***bold italic***, ~~strikethrough~~)
4. Links [text](url "title") and images ![alt](src "title")
5. Inline code, fenced blocks with language hints, indented blocks
6. Nested ordered/unordered lists (three levels) and mixed blockquotes
7. HTML entity escaping (&, <, >, ") without parsing markdown inside code
8. Edge cases: empty input, whitespace only, \r\n line endings, unclosed **

Assertion rules:
- Assert exact strings with toBe(); never use toBeDefined(), toBeTruthy(), or typeof checks.
- Test only the public function; never mock or spy on internal helpers.
- One behaviour per test, named after the expected output.

Create src/lib/markdown/markdown-to-html.ts exporting the signature and throwing
new Error("Not implemented"). Run `npx vitest run src/lib/markdown` and report
the failure count; every test must fail with "Not implemented".
```

Sprawdź każdą asercję, popraw błędne założenia i zamróź specyfikację w Gicie:

```bash
git add src/lib/markdown
git commit -m "test: markdownToHtml specification (red)"
git tag tdd-red
```

### Krok 2: Implementuj do zielonego przy testach tylko do odczytu

Otwórz nowy czat Agenta, aby implementacja opierała się wyłącznie na zablokowanym kontrakcie:

**Prompt do skopiowania: implementacja do zielonego, testy tylko do odczytu**

```text
Implement markdownToHtml in src/lib/markdown/markdown-to-html.ts so every test
in src/lib/markdown/__tests__/markdown-to-html.test.ts passes.

Constraints:
1. Test files are read-only. Never edit, skip, rename, or delete any test or add .skip/.only/.todo.
2. Never special-case literal test inputs.
3. No external markdown library; implement from scratch.
4. After each edit, run: npx vitest run src/lib/markdown
5. If a test appears incorrect, stop and report which test and why.
6. If the failure count does not drop for three consecutive iterations, stop and summarize your hypothesis.

When all tests pass, run `npx tsc --noEmit` and report the final test count.
```

Warunek 6 zatrzymuje jałowe pętle: gdy liczba błędów przestaje spadać, problemem jest zwykle projekt algorytmu — np. parser linia po linii nie radzi sobie z zagnieżdżeniami — i czas wrócić do [Plan Mode](/pl/cursor-ide/build/agent-modes-deep-dive/) zamiast dokładać łaty.

### Krok 3: Zamieniaj błędy produkcyjne najpierw w czerwony test regresyjny

Ten sam podział stosuj przy naprawie błędów: najpierw odtwórz błąd testem, zatwierdź go i przesuń tag `tdd-red` (`git tag -f tdd-red`), a dopiero potem uruchom prompt implementacji przy testach tylko do odczytu.

**Prompt do skopiowania: od zgłoszenia błędu do czerwonego testu regresyjnego**

```text
Bug: markdown with Windows line endings (\r\n) produces an empty <p></p> between paragraphs.

1. Add the smallest test reproducing this in src/lib/markdown/__tests__/markdown-to-html.test.ts asserting exact HTML output.
2. Run it and confirm it fails specifically for this reason.
3. Stop and wait for approval before touching implementation code.
```

## Jak zweryfikować, że zestaw nie został osłabiony ani spłycony

Nigdy nie polegaj na słownym zapewnieniu agenta, że nie tknął testów ani że testy łapią realne błędy. Nałóż trzy kontrole:

**1. Mechaniczna weryfikacja blokady testów.** Uruchom oba polecenia w katalogu głównym repozytorium: `git diff` wykrywa zmiany w śledzonych testach, a `git status` wyłapuje nowo dodane pliki testowe:

```bash
git diff --exit-code tdd-red -- src/lib/markdown/__tests__/
git status --porcelain src/lib/markdown/__tests__/
```

Zakaz edycji testów zapisz w `.cursor/rules/` ([reguły projektu](/pl/cursor-ide/quick-start/project-rules/)) jako wytyczną, a egzekwuj go mechanicznie przez `CODEOWNERS`, hooki lub kontrolę diffu w CI ([ochrona wyroczni](/pl/workflows/test/protect-the-oracle/)).

**2. Zawężone testy mutacyjne.** Narzędzia mutacyjne (np. Stryker z twoim runnerem testów) odwracają operatory i usuwają warunki wyłącznie w zmienionych plikach (`--mutate <zmieniony-plik> --incremental`). Ocalałe mutanty ujawniają asercje zbyt słabe do wychwycenia regresji. Przekaż raport Agentowi, aby dopisał celowane testy w osobnym pliku, przejrzyj je, zacommituj i przesuń `tdd-red` ([siła wyroczni](/pl/workflows/test/oracle-strength/)).

**3. Audyt wyroczni repozytorium.** Uruchom `npx @wondelai/harness-audit` ([Harness Audit](/pl/harness-audit/)), aby przeskanować Stację 5 (Verification) pod kątem wycieków `.skip`/`.only`, asercji tautologicznych, braku ochrony testów oraz wyciszania reguł lintera i typów.

| Warstwa weryfikacji | Czego dowodzi | Właściciel |
| --- | --- | --- |
| Przegląd testów przed commitem (`tdd-red`) | Asercje odpowiadają intencji domenowej | Programista zlecający zmianę |
| `git diff tdd-red` + `git status` na testach | Agent zachował kontrakt w całości | Programista lokalnie; CI na PR |
| Wynik mutacyjny zmienionych plików | Testy wykrywają realne regresje logiki | Programista; próg ustala tech lead |
| Typy, lint, testy i pokrycie gałęzi | Spójność z repozytorium i ścieżki brzegowe | Wymagany check CI |
| Review PR + [Bugbot](/pl/cursor-ide/ship/bugbot/) | Zmiana testów i publicznego API jest celowa | Recenzent (najpierw testy, kod w wyjątkach) |

## Kiedy TDD pasuje, a kiedy wygrywa inna wyrocznia

| Mocne zastosowanie TDD w Cursorze | Słabe dopasowanie | Lepsza wyrocznia |
| --- | --- | --- |
| Parsery, formatery, walidatory, reguły cenowe | Układ wizualny i odstępy | Testy E2E w przeglądarce i porównania wizualne |
| Handlery API z kontraktem wejścia i wyjścia | Orkiestracja wielu usług | Testy integracyjne na efemerycznych usługach |
| Odtwarzalne błędy produkcyjne | Optymalizacja opóźnień i przepustowości | Benchmarki z budżetem wydajności |
| Czyste transformacje danych | Nieprzetestowane moduły legacy | Najpierw testy charakteryzacyjne, potem TDD |

Przy szerokiej przestrzeni wejść testy przykładowe sprzyjają dopasowaniu się do przykładów; dodaj niezmienniki oparte na właściwościach ([przepływy testowania](/pl/workflows/test/)), których agent nie obejdzie twardymi warunkami.

## Zapisz pętlę jako zespołowy Agent Skill

Gdy zespół codziennie stosuje sekwencję red-green-refactor, przenieś ją z pojedynczych promptów do wersjonowanego pliku `SKILL.md` w `.cursor/skills/` lub `.agents/skills/`, dzięki czemu Cursor, Claude Code i Codex korzystają z jednej procedury. Strukturę i zasady bezpieczeństwa opisują [Agent Skills](/pl/ecosystem/skills/), [agentskills.io](https://agentskills.io) oraz [skills.wondel.ai](https://skills.wondel.ai) — pamiętając, że skill ukierunkowuje pracę, a egzekwują ją Git i CI.

## Co psuje się w pętli TDD prowadzonej przez Cursora?

**Agent edytuje testy, żeby dojść do zielonego.** Spadek liczby testów, poluzowanie `toBe` do `toContain` albo dopisanie `.skip` maskuje uszkodzony kod. Wykryj to przez `git diff --exit-code tdd-red`, przywróć testy z tagu, otwórz nowy czat i wymuś blokadę testów w CI lub hookach.

**Agent dopisuje gałęzie pod dosłowne wejścia testowe.** Warunki dopasowane do przykładowych stringów przechodzą zestaw testowy i psują ruch produkcyjny. Stosuj testy mutacyjne oraz ukryty zestaw kontrolny lub testy właściwościowe.

**Tautologiczne asercje przechodzą każdą implementację.** Sprawdzenia w stylu `toBeDefined()` lub `typeof x === 'string'` nie łapią błędnej logiki. Zakaż ich w prompcie testowym i wyeliminuj ocalałe mutanty testami mutacyjnymi.

**Testy wiążą się z prywatnymi szczegółami.** Szpiegowanie wewnętrznych funkcji psuje sensowny refaktoring i utrwala złą architekturę. Asertuj wyłącznie przez publiczny interfejs.

**Pętla zatrzymuje się w miejscu.** Brak postępu przez trzy iteracje sygnalizuje wadę projektu. Przerwij sesję, przeanalizuj przyczyny w [Plan Mode](/pl/cursor-ide/build/agent-modes-deep-dive/), zatwierdź nowe podejście i rozpocznij implementację od czystego czatu.

## Oficjalna dokumentacja i kolejne kroki

Konfigurację allowlisty w Run Modes i aktualne polecenia edytora sprawdzaj w [cursor.com/docs](https://cursor.com/docs), a przenośne definicje skilli TDD na [agentskills.io](https://agentskills.io).

- [Ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) — Hooki, CODEOWNERS i strażniki CI, których agent nie obejdzie.
- [Siła wyroczni](/pl/workflows/test/oracle-strength/) — Wyniki mutacyjne i poprzeczka wymagana przed autonomią.
- [Testowanie w Claude Code](/pl/claude-code/test/testing/) — Ta sama pętla TDD z zablokowanym kontraktem w Claude Code.
- [Testowanie w Codeksie](/pl/codex/test/testing/) — Weryfikacja test-first w piaskownicach Codeksa.
