Para fazer o Xcode destacar o teste que chamou um auxiliar compartilhado do XCTest, defina os parâmetros #filePath e #line como valores padrão no auxiliar e encaminhe ambos para as asserções. Este passo a passo mostra a correção, auxiliares aninhados e o equivalente no Swift Testing.

Por que o Xcode destaca o auxiliar?

Uma asserção compartilhada introduz outra localização no código-fonte. O teste chama seu auxiliar, e o auxiliar chama uma asserção do XCTest. Se essa asserção usar os argumentos de localização padrão, a localização informada será a da asserção dentro do auxiliar. A Apple documenta file: StaticString = #filePath e line: UInt = #line tanto em XCTAssertEqual quanto em XCTFail.

Capture a localização de quem chamou o auxiliar no limite dele e, em seguida, passe esses valores adiante. Os valores padrão de localização do código-fonte em Swift capturam o local da chamada; o projeto Swift explica esse comportamento em SE-0274: Nomes concisos de arquivos mágicos. A Apple também demonstra esse padrão exato de auxiliar do XCTest em Migrar para o Swift Testing, mostrando o Xcode atribuindo a falha à chamada do auxiliar.

Para quem desenvolve no Xcode em um Mac, a tarefa concreta é preservar verificações reutilizáveis e fazer com que cada falha leve de volta à entrada de teste relevante. Os exemplos abaixo usam apenas pequenos arrays de inteiros. Ao executá-los, não é preciso ter modelo do app, substituto de serviço, dependência baixada nem acesso à rede.

Adicione parâmetros de localização de quem chamou a um auxiliar do XCTest

Use um alvo de testes unitários existente para macOS. Se o projeto precisar de um, escolha File > New > Target, filtre por Test e selecione Unit Testing Bundle. Para adicionar um arquivo de teste, escolha File > New > New File From Template e selecione XCTest Unit Test. Estes são os caminhos documentados pela Apple em Adicionar testes ao projeto do Xcode.

Coloque este arquivo de teste completo no alvo de testes unitários. O segundo teste fornece deliberadamente um total esperado incorreto para que você possa inspecionar a localização da falha.

import XCTest

private func assertTotal(
    _ values: [Int],
    equals expected: Int,
    file: StaticString = #filePath,
    line: UInt = #line
) {
    let actual = values.reduce(0, +)
    XCTAssertEqual(
        actual,
        expected,
        "Unexpected total for \(values)",
        file: file,
        line: line
    )
}

final class TotalHelperTests: XCTestCase {
    func testMatchingTotal() {
        assertTotal([2, 3, 4], equals: 9)
    }

    func testDeliberatelyIncorrectTotal() {
        assertTotal([2, 3, 4], equals: 10)
    }
}

Os pontos essenciais são os tipos dos parâmetros, os valores padrão e o encaminhamento explícito. StaticString e UInt correspondem à assinatura da asserção do XCTest. Mantenha #filePath e #line diretamente nos valores padrão do auxiliar. Assim, o teste chama o auxiliar sem fornecer manualmente nenhum dos argumentos de localização. Consulte os parâmetros de XCTAssertEqual documentados.

O cálculo é ilustrativo: 2 + 3 + 4 é 9, então a primeira comparação corresponde e a segunda não. Esses casos aritméticos foram verificados localmente com Python. Não havia um executável Swift disponível no ambiente de pesquisa, então os exemplos Swift foram inspecionados, mas não foram compilados nem executados aqui.

Verifique a localização e o resultado do teste

Escolha Product > Test ou execute o teste individual usando o controle de reprodução ao lado da declaração. Depois, selecione o teste com falha no Test navigator e inspecione o diagnóstico. A Apple descreve esses controles e os detalhes da falha em Executar testes e interpretar resultados.

Neste exemplo, verifique dois resultados distintos: testDeliberatelyIncorrectTotal() falha, e o diagnóstico da asserção aponta para a chamada assertTotal([2, 3, 4], equals: 10). A atribuição ao chamador esperada segue o padrão de encaminhamento demonstrado pela Apple. Depois de conferir isso, altere 10 para 9 e execute os testes novamente; a incompatibilidade intencional deve ser removida da suíte de testes final.

Se o diagnóstico ainda apontar para dentro do auxiliar, inspecione a chamada final da asserção. Declarar parâmetros de localização não basta se o auxiliar omitir file: file ou line: line no ponto em que a falha é registrada.

Preserve a localização em todas as camadas de auxiliares

Auxiliares aninhados precisam do mesmo encaminhamento explícito. Suponha que um teste chame um auxiliar de domínio, que por sua vez chama um auxiliar de asserção de nível inferior. Se o auxiliar externo omitir os argumentos de localização, o auxiliar de nível inferior capturará o local dessa chamada intermediária.

Vale verificar este limite da linguagem: os valores padrão de localização do código-fonte não são propagados automaticamente por chamadas arbitrárias de auxiliares. SE-0285: Facilitar a transição para strings mágicas concisas discute explicitamente o comportamento não transitivo desses valores padrão.

O exemplo a seguir é um arquivo de teste alternativo completo. Ele demonstra um auxiliar que chama outro auxiliar, preservando a localização original do teste.

import XCTest

private func assertIntegerEqual(
    _ actual: Int,
    _ expected: Int,
    file: StaticString = #filePath,
    line: UInt = #line
) {
    XCTAssertEqual(actual, expected, file: file, line: line)
}

private func assertRowTotal(
    _ row: [Int],
    equals expected: Int,
    file: StaticString = #filePath,
    line: UInt = #line
) {
    assertIntegerEqual(
        row.reduce(0, +),
        expected,
        file: file,
        line: line
    )
}

final class NestedTotalHelperTests: XCTestCase {
    func testRowTotal() {
        assertRowTotal([2, 3, 4], equals: 9)
    }
}

Ao revisar uma cadeia maior de auxiliares, faça um exercício simples de rastreamento: comece na chamada do teste, siga cada auxiliar e confira se a mesma localização capturada chega à asserção. Capture os valores padrão no limite cuja localização deve aparecer no resultado; encaminhe os valores existentes pelas demais camadas. Evite ocultar a captura atrás de outra função usada como argumento padrão — a armadilha ilustrada pela SE-0285.

Registrar uma falha interrompe o teste que chamou o auxiliar?

A atribuição da falha e o fluxo de controle são decisões distintas. O valor padrão de continueAfterFailure do XCTest é true, então uma asserção com falha normalmente permite que a execução continue. Alterar o arquivo e a linha informados não muda essa propriedade. A Apple documenta esse comportamento em continueAfterFailure.

Se um auxiliar detectar uma condição que invalide o restante do trabalho dele, dê a esse auxiliar um caminho explícito de saída. Por exemplo, registre a falha com a localização encaminhada e depois retorne do auxiliar. Lembre-se de que retornar de um auxiliar devolve o controle a quem o chamou; planeje adequadamente o trabalho subsequente do chamador. O guia de migração da Apple ilustra uma falha incondicional seguida de um retorno.

Mantenha a primeira verificação síncrona e pequena. Confirme que um cálculo intencionalmente incorreto falha no ponto de chamada esperado antes de adicionar uma configuração mais elaborada ou um comportamento assíncrono. Essa sequência permite distinguir um defeito no encaminhamento da localização de outros problemas na execução dos testes.

Use uma localização de código-fonte compatível no Swift Testing

Para um auxiliar chamado por testes do Swift Testing, use #expect com um SourceLocation explícito. A Apple documenta sourceLocation como a localização à qual as expectativas e os problemas são atribuídos, e declara que uma condição falsa registra um problema para o teste em execução na tarefa atual. Consulte expect(_:_:sourceLocation:).

Este arquivo alternativo completo requer o Swift Testing, disponível no Xcode 16 e no Swift 6.0. Ele captura os quatro componentes da localização como valores padrão separados e, em seguida, constrói o inicializador de SourceLocation documentado.

import Testing

private func expectTotal(
    _ values: [Int],
    equals expected: Int,
    fileID: String = #fileID,
    filePath: String = #filePath,
    line: Int = #line,
    column: Int = #column
) {
    let location = SourceLocation(
        fileID: fileID,
        filePath: filePath,
        line: line,
        column: column
    )
    let actual = values.reduce(0, +)
    #expect(actual == expected, sourceLocation: location)
}

@Test func matchingTotal() {
    expectTotal([2, 3, 4], equals: 9)
}

@Test func deliberatelyIncorrectTotal() {
    expectTotal([2, 3, 4], equals: 10)
}

O inicializador exige um ID de arquivo não vazio e devidamente formatado, além de números positivos para linha e coluna. Capturar os componentes fornecidos pelo compilador evita inventar esses valores. Ao aninhar esses auxiliares, encaminhe os quatro argumentos capturados, assim como a versão do XCTest encaminha seus dois argumentos. Mais uma vez, corrija a expectativa deliberadamente 10 depois de verificar a atribuição.

O que muda quando o XCTest e o Swift Testing compartilham um auxiliar?

Os dois frameworks podem coexistir em um mesmo pacote de testes, mas um auxiliar que atravessa os limites entre frameworks exige tratamento atento à versão. O atual guia de migração da Apple documenta a interoperabilidade e seus valores padrão: toolchains anteriores ao Swift 6.4 usam none; o Swift 6.4 ou posterior usa, por padrão, limited para pacotes que declaram uma versão anterior das ferramentas e complete para pacotes que declaram a versão 6.4 ou posterior das ferramentas.

Modo de interoperabilidade Falha de asserção do XCTest dentro de um teste do Swift Testing
none O problema entre bibliotecas é ignorado
limited É reportada como aviso, com orientações para modernização
complete Mantém a severidade de falha, com orientações para modernização
strict É reportada usando fatalError

Esses modos explicam por que um auxiliar pode informar o texto correto e, ainda assim, deixar passar um teste do Swift Testing. A sessão de migração da WWDC26 da Apple mostra exatamente esse resultado e, em seguida, altera a configuração de interoperabilidade do plano de testes em Test Execution para Complete, preservando a severidade da falha. Confira sua toolchain instalada antes de depender desse recurso.

Em toolchains mais antigas, mantenha o registro de asserções nativo de cada framework e compartilhe o cálculo determinístico subjacente. Para configurações de interoperabilidade compatíveis, a Apple também demonstra substituir XCTFail de um auxiliar por Issue.record do Swift Testing. O encaminhamento da localização do código-fonte ainda precisa ser preservado durante essa migração.

Diagnostique o sintoma restante

O que você observa O que inspecionar em seguida
A falha aponta para dentro do auxiliar de asserção Confirme se a asserção recebe os argumentos de localização capturados
A falha aponta para dentro de um auxiliar externo Confirme se esse auxiliar externo encaminha a localização de quem o chamou
O teste do Swift Testing passa apesar de uma asserção do XCTest Confira o suporte da toolchain e o modo de interoperabilidade
O código é executado depois que uma asserção do XCTest falha Confira o fluxo de controle pretendido e continueAfterFailure
Nenhum teste de exemplo aparece na execução Confirme se o arquivo pertence ao alvo de testes unitários e se o plano de testes ativo o inclui

Para descobrir e selecionar testes, o guia de configuração de testes e o guia de execução de testes da Apple descrevem os alvos de teste e os planos ativos. Para uma execução entre frameworks, consulte as regras de interoperabilidade documentadas acima antes de alterar os argumentos de localização.

Um auxiliar compartilhado útil preserva três coisas: uma comparação significativa, um diagnóstico vinculado ao chamador pretendido e o resultado de teste desejado. Verifique esses aspectos com uma incompatibilidade deliberada, remova-a e continue encaminhando a localização capturada sempre que outra camada de auxiliar for introduzida.

Fontes