Swift Testing: Ghid Complet @Test, @Suite, Traits și Migrare de la XCTest (2026)

Actualizat: 16 iunie 2026

Swift Testing este noul framework oficial Apple pentru teste unitare, introdus la WWDC 2024 și stabilizat în Swift 6.0, care înlocuiește treptat XCTest cu o sintaxă bazată pe macro-uri (@Test, @Suite, #expect) și suport nativ pentru async/await, parametrizare și paralelism. În 2026, framework-ul e standard în Xcode 16.2+ și complet integrat cu Swift Package Manager, oferind execuție mai rapidă, rapoarte mai clare și un model de organizare a testelor mult mai modern decât XCTestCase.

• Swift Testing folosește macro-urile @Test și @Suite în loc de moștenirea din XCTestCase, eliminând prefixul obligatoriu test.
• #expect raportează eroarea și continuă, iar #require oprește testul când o precondiție eșuează. Alegerea corectă reduce zgomotul în rapoarte.
• Testele parametrizate cu arguments: rulează același cod pe seturi de date și raportează fiecare combinație individual.
• Traits ca .tags, .enabled(if:), .serialized și .timeLimit controlează filtrarea, condiționarea și paralelismul fără cod imperativ.
• Swift Testing și XCTest pot coexista în același target, așa că migrarea poate fi incrementală, fișier cu fișier.
• Suportul nativ pentru async/await elimină nevoia de XCTestExpectation în 90% dintre testele asincrone.

Ce este Swift Testing și de ce înlocuiește XCTest

Swift Testing este un framework open-source dezvoltat de Apple, scris integral în Swift modern și disponibil în repository-ul oficial swift-testing pe GitHub. Spre deosebire de XCTest, care moștenește un model bazat pe Objective-C și clase, Swift Testing folosește macro-uri Swift compilate la build-time pentru a transforma funcții simple în teste. Asta înseamnă mai puțin boilerplate, mesaje de eroare mai bune (cu expresie evaluată și subexpresii imprimate automat) și integrare nativă cu sistemul de concurență Swift 6.

Sincer, prima dată când am migrat un proiect pe Swift Testing, am rămas surprins cât de puțin cod scriu pentru același număr de cazuri. Apple a anunțat oficial la WWDC 2025 că framework-ul e recomandat pentru toate proiectele noi, iar Xcode 16.2 a adăugat suportul complet în Test Navigator: pictograme pentru suite, tag-uri colorate și execuție paralelă vizibilă pe linia de timp. XCTest rămâne funcțional și suportat pentru testele UI și pentru cod Objective-C, dar pentru logică Swift pură noul framework câștigă pe orice metrică, fie că vorbim de timp de scriere, claritate a output-ului sau flexibilitate. Dacă lucrezi cu modele moderne SwiftUI, articolul nostru despre migrarea către macro-ul @Observable arată cum aceleași principii de macro-uri se aplică și în UI.

Sub capotă, Swift Testing folosește același sistem de macro-uri ca Observation, descris în documentația oficială Apple Swift Testing. Macro-urile generează cod la compilare, deci nu există overhead la runtime, iar diagnosticele apar direct în Xcode atunci când o aserțiune eșuează.

Instalare și configurare în Xcode 16 și SwiftPM

În Xcode 16.2 sau mai nou, Swift Testing e preinstalat. Când creezi un nou target de tip „Unit Testing Bundle", checkbox-ul „Swift Testing" e selectat implicit, iar Xcode generează un fișier exemplu cu import Testing în loc de import XCTest. Pentru proiectele existente, e suficient să adaugi un fișier nou .swift și să folosești import Testing. Nu trebuie să schimbi nimic în configurația schemei.

Pentru pachete Swift Package Manager, fișierul Package.swift trebuie să declare un target de test standard. Nu există dependență separată. Iată o configurație minimă pentru Swift 6.0+:

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "PaymentsCore",
    platforms: [.iOS(.v17), .macOS(.v14)],
    products: [
        .library(name: "PaymentsCore", targets: ["PaymentsCore"])
    ],
    targets: [
        .target(name: "PaymentsCore"),
        .testTarget(
            name: "PaymentsCoreTests",
            dependencies: ["PaymentsCore"]
        )
    ]
)

Rulează testele din terminal cu swift test sau cu filtru pe tag: swift test --filter .tags/.smoke. În Xcode, scurtătura ⌘U execută toate testele, iar Test Navigator (⌘6) afișează suitele cu pictograma „beaker" pentru a le distinge vizual de testele XCTest.

Macro-urile @Test și @Suite în detaliu

În Swift Testing, un test e pur și simplu o funcție marcată cu @Test. Funcția poate fi globală, metodă de struct sau metodă de class, fără obligația de a moșteni dintr-o clasă bază. Mai jos vezi structura minimă, comparată cu echivalentul XCTest:

import Testing
@testable import PaymentsCore

@Test("Conversia EUR la RON folosește rata BNR")
func eurToRonUsesBNRRate() async throws {
    let converter = CurrencyConverter(rate: 4.97)
    let result = converter.convert(100, from: "EUR", to: "RON")
    #expect(result == 497.0)
}

@Suite("Validare IBAN")
struct IBANValidatorTests {
    let validator = IBANValidator()

    @Test func acceptsValidRomanianIBAN() {
        #expect(validator.isValid("RO49AAAA1B31007593840000"))
    }

    @Test func rejectsShortIBAN() {
        #expect(!validator.isValid("RO49"))
    }
}

@Suite grupează testele într-o unitate logică. Suitele pot fi struct, actor sau final class. Recomandarea oficială Apple este să folosești struct pentru izolare implicită, deoarece Swift Testing creează o nouă instanță pentru fiecare test, iar proprietățile stocate funcționează ca un setUp gratuit. Dacă ai stare partajată reală (de exemplu un mock costisitor de inițializat), folosește actor și marchează suita cu trait-ul .serialized pentru a evita data race-uri.

Numele descriptiv (string-ul din paranteză) este opțional, dar e afișat în Test Navigator și în rapoartele CI. Preferă propoziții scurte în loc de nume de funcții camelCase. Mi-am dat seama în timp că asta îmbunătățește serios lizibilitatea log-urilor pentru colegii care nu au scris testul.

#expect vs #require: când folosești fiecare

Diferența fundamentală: #expect înregistrează un eșec și permite testului să continue, în timp ce #require aruncă o eroare și oprește execuția imediat dacă condiția e falsă. Regula practică pe care o aplic: folosește #require când restul testului nu mai are sens dacă precondiția cade. De exemplu, când extragi o valoare opțională sau verifici că o resursă există.

@Test func parseValidJSONReturnsUser() throws {
    let data = Data(#"{"id":42,"name":"Ana"}"#.utf8)

    // Dacă decodificarea cade, restul aserțiunilor sunt inutile
    let user = try #require(try? JSONDecoder().decode(User.self, from: data))

    // Continuăm doar dacă user a fost decodat cu succes
    #expect(user.id == 42)
    #expect(user.name == "Ana")
}

Un alt avantaj puternic al lui #expect este că, dacă scrii #expect(a + b == c * 2) și aserțiunea eșuează, Xcode imprimă valorile efective ale lui a, b și c, nu doar mesajul „expected true". Asta înseamnă că rar mai ai nevoie să scrii mesaje custom. Pentru cazurile în care vrei totuși un comentariu, sintaxa este #expect(condition, "context util pentru debug").

Cum scriu teste parametrizate cu Swift Testing

Una dintre cele mai dorite funcții absente în XCTest este parametrizarea nativă. Swift Testing rezolvă asta cu argumentul arguments: pe @Test. Framework-ul rulează funcția o dată pentru fiecare element și raportează rezultatele separat, deci dacă 3 din 10 cazuri eșuează, vei vedea exact care.

@Test("Validator CNP acceptă formate corecte",
      arguments: [
          "1800101220011",  // bărbat născut 1980
          "2950505330044",  // femeie născută 1995
          "6010101110022"   // copil născut după 2000
      ])
func validCNPIsAccepted(_ cnp: String) {
    let validator = CNPValidator()
    #expect(validator.isValid(cnp), "CNP \(cnp) ar trebui acceptat")
}

@Test("Conversie temperatură Celsius -> Fahrenheit",
      arguments: zip(
          [0.0, 100.0, -40.0, 37.0],
          [32.0, 212.0, -40.0, 98.6]
      ))
func celsiusToFahrenheit(celsius: Double, expected: Double) {
    let result = TemperatureConverter.toFahrenheit(celsius)
    #expect(abs(result - expected) < 0.01)
}

Poți combina mai multe colecții folosind zip() sau produsul cartezian implicit dacă pasezi două argumente nezipate. Pentru date generate dinamic, definește o funcție care întoarce [Input] și pasează-o ca argument. Swift Testing o evaluează o singură dată per rulare. Reține totuși că, sub regimul Swift 6, fiecare tip de argument trebuie să fie Sendable, ceea ce se leagă direct de modelul de concurență prezentat în ghidul nostru despre concurența în Swift cu async/await și actors.

Cum testez cod async și callback-uri

Swift Testing tratează async ca cetățean de rang întâi. Marchezi pur și simplu funcția cu async throws și apelezi codul real cu await. Nu mai există XCTestExpectation, fulfill() sau wait(for:timeout:) pentru majoritatea scenariilor.

@Test func fetchUserFromAPIReturnsValidProfile() async throws {
    let client = APIClient(session: .mockedSuccess)
    let profile = try await client.fetchUser(id: 42)

    #expect(profile.id == 42)
    #expect(!profile.email.isEmpty)
}

Pentru API-uri vechi bazate pe closure (de exemplu callback-uri din SDK-uri non-async), folosește confirmation. Aceasta e înlocuitorul modern al lui XCTestExpectation și verifică faptul că un callback e apelat de un număr specificat de ori, în interval de timp:

@Test func subscriberReceivesThreeEvents() async {
    await confirmation("Primește exact 3 evenimente", expectedCount: 3) { confirm in
        let publisher = EventPublisher()
        publisher.onEvent = { _ in confirm() }
        publisher.emit(count: 3)
        try? await Task.sleep(for: .milliseconds(100))
    }
}

Dacă vrei să impui un timeout pe un test întreg, adaugă trait-ul .timeLimit(.minutes(1)) la @Test. Atenție: limitele sunt setate la granularitate de minute pentru a evita flakiness în CI-uri lente. Pentru micro-timeout-uri folosește Task.sleep manual în interiorul confirmării.

Traits, tags și organizarea suitelor

Traits sunt modificatori declarativi atașați la @Test și @Suite. Cele mai utile în 2026:

• .tags(.smoke, .integration), etichetare pentru filtrare la rulare
• .enabled(if: ProcessInfo.processInfo.environment["RUN_SLOW"] == "1"), execuție condiționată
• .disabled("Tracking bug #4521"), dezactivare cu justificare vizibilă în rapoarte
• .bug("https://github.com/org/app/issues/4521"), link direct la issue
• .timeLimit(.minutes(1)), timeout maxim
• .serialized, rulează testele dintr-o suită secvențial (default este paralel)

Tag-urile sunt definite o singură dată ca extensii pe Tag:

extension Tag {
    @Tag static var smoke: Self
    @Tag static var integration: Self
    @Tag static var slow: Self
}

@Test(.tags(.smoke))
func loginScreenLoads() { /* ... */ }

@Test(.tags(.integration, .slow))
func endToEndCheckout() async throws { /* ... */ }

Rulează doar smoke tests în CI rapid cu swift test --filter .tags/.smoke, iar suita completă o lași pentru rulările de noapte. În Xcode, Test Plans din 2026 acceptă filtrare pe tag-uri direct din UI, ceea ce elimină nevoia de scheme separate pentru fiecare grup. Pentru sfaturi avansate despre organizarea schemelor și a pașilor de build, consultă și ghidul nostru despre NavigationStack, care folosește același pattern modular în target-uri separate.

Cum migrez de la XCTest la Swift Testing

Da, poți migra incremental. Swift Testing și XCTest coexistă în același target fără conflict, ceea ce înseamnă că nu trebuie să rescrii toate testele într-un weekend. Strategia recomandată e migrarea pe verticală, fișier cu fișier, începând cu cele mai noi și mai mici suite. Iată maparea esențială:

XCTest	Swift Testing
class FooTests: XCTestCase	@Suite struct FooTests
func testBar()	@Test func bar()
XCTAssertEqual(a, b)	#expect(a == b)
XCTUnwrap(value)	try #require(value)
XCTAssertThrowsError	#expect(throws: MyError.self) { ... }
setUp() / tearDown()	init() / deinit (per test)
XCTSkip("motiv")	.disabled("motiv") trait
XCTestExpectation	confirmation { ... }
continueAfterFailure = false	folosește try #require

Apple oferă o unealtă oficială de migrare experimentală în Swift 6.1, dar pentru proiecte de dimensiune medie e mai sigur să faci migrarea manual. Vei avea ocazia să cureți aserțiuni redundante și să grupezi cazurile în teste parametrizate. Pentru a evita „big bang" în CI, păstrează ambele tipuri de teste într-un Test Plan până când acoperirea Swift Testing depășește 80%, apoi elimină XCTest.

Capcane comune și bune practici

Prima capcană pe care o întâlnesc echipele e folosirea final class pentru suite când o stare partajată nu e necesară. Asta dezactivează izolarea per-test pe care o oferă struct și introduce coupling implicit între aserțiuni care rulează în paralel. Default-ul corect e struct. Treci la actor sau final class doar când chiar ai nevoie.

A doua capcană: presupunerea că ordinea testelor e garantată. În Swift Testing, ordinea e nedeterministă și paralelizată, exact ca în TaskGroup. Dacă două teste depind unul de altul, designul e greșit. Folosește .serialized doar ca patch temporar și deschide un task pentru a desface dependențele.

A treia capcană: copierea aserțiunilor XCTest 1-la-1. #expect(a == b) nu necesită mesaj de eroare pentru că Swift Testing imprimă diferența. Mesajele lungi de tipul „expected X to equal Y" sunt redundante și fac codul mai zgomotos. Lasă macro-ul să-și facă treaba.

Bune practici concrete pentru 2026:

1. Scrie un test parametrizat oriunde ai mai mult de două aserțiuni similare consecutive.
2. Marchează cu .tags(.smoke) minimul de teste care confirmă că aplicația „compilează și pornește", apoi rulează-le la fiecare push.
3. Pentru cod async, folosește confirmation doar pentru callback-uri legacy. Pentru async/await modern, returnează direct valoarea și folosește #expect.
4. Inițializează mock-urile costisitoare în init() al suitei, nu la nivel de fișier. Asta menține izolarea între teste.
5. Adaugă .bug("URL") la testele care reproduc bug-uri raportate. Linkul apare automat în rapoartele Xcode Cloud.

Pentru context suplimentar despre cum aceste pattern-uri se leagă de stack-ul Apple modern, ghidul oficial Apple „Testing your apps in Xcode" oferă scenarii recomandate pentru integrarea în pipeline-uri CI/CD precum Xcode Cloud, GitHub Actions și Bitrise.

Întrebări frecvente

Pot folosi Swift Testing și XCTest în același target?

Da. Cele două framework-uri coexistă fără conflict în același test target. Un fișier folosește import Testing, altul import XCTest, iar Xcode rulează amândouă. Asta permite migrarea incrementală, fișier cu fișier, fără să blochezi releaseurile.

Ce versiune minimă de Xcode am nevoie pentru Swift Testing?

Xcode 16.0 are suport stabil, dar pentru toolingul complet (filtrare pe tag-uri în UI, integrare cu Xcode Cloud și diagnostice extinse) recomandarea în 2026 este Xcode 16.2 sau mai nou. Pentru linia de comandă, Swift 6.0 toolchain este suficient.

Care e diferența între #expect și #require în Swift Testing?

#expect înregistrează o eroare și permite testului să continue, în timp ce #require aruncă imediat și oprește execuția. Folosește #require pentru precondiții (de exemplu try #require(optional)) și #expect pentru verificări multiple independente.

Cum verific că o funcție aruncă o eroare specifică?

Folosește #expect(throws: MyError.invalidInput) { try sut.process(data) }. Poți pasa și tipul de eroare cu throws: MyError.self dacă valoarea exactă nu e relevantă, sau un closure pentru validări custom pe eroarea aruncată.

Swift Testing înlocuiește complet XCTest în 2026?

Pentru teste unitare și de integrare scrise în Swift, da. Apple recomandă oficial Swift Testing pentru proiectele noi. Pentru testele UI (XCUIApplication) și pentru cod Objective-C, XCTest rămâne soluția standard și continuă să fie suportat în Xcode 16+.