Por que código acoplado ao CLLocationManager quebra qualquer pipeline de testes
Serviços que conversam direto com hardware costumam ser o primeiro ponto em que uma suite de testes unitários começa a ficar lenta ou imprevisível. No iOS, o CLLocationManager é um exemplo clássico. Quando um ViewModel ou um Presenter instancia o gerenciador nativo no construtor e chama startUpdatingLocation() diretamente, você perde o controle sobre três variáveis ao mesmo tempo: o estado de permissão do sistema operacional, o tempo até o primeiro callback chegar e a qualidade da coordenada devolvida.
Em um projeto financeiro que usava geolocalização para validar transações fora do padrão e localizar pontos de atendimento, os testes desse módulo quebravam quase toda semana no servidor de CI. Ora o simulador exibia o alerta de permissão e travava o runner, ora o arquivo GPX configurado no esquema demorava mais do que o timeout da expectativa do XCTest. Quando precisávamos testar o cenário de permissão negada ou precisão reduzida do iOS 14+, ninguém conseguia automatizar de verdade; o time dependia de teste manual em aparelho físico antes de cada release.
O caminho para transformar esse código em algo determinístico e rápido passa por isolar o CoreLocation atrás de uma fronteira de domínio usando Inversão de Dependência. Em vez de o seu código de negócio importar CoreLocation e lidar com CLLocation, ele conversa apenas com protocolos e structs simples do próprio domínio.
Princípio de isolamento de hardware: regras de negócio, Interactors e ViewModels nunca devem importar CoreLocation. Eles devem consumir um serviço próprio que entrega coordenadas limpas e erros de domínio bem definidos.
A armadilha silenciosa da conformidade direta em CLLocationManager
Muita gente tenta resolver o problema criando um protocolo com exatamente os mesmos nomes de propriedades do CLLocationManager e adicionando uma extensão direta de conformidade. Esse atalho esconde um bug sério no Swift moderno que já vi derrubar aplicativo em homologação.
Se você declara var authorizationStatus: CLAuthorizationStatus { get } no protocolo e escreve extension CLLocationManager: LocationProviderProtocol implementando uma propriedade computada com o mesmo nome chamando self.authorizationStatus para o iOS 14+, o compilador resolve a chamada para a própria propriedade da extensão, gerando recursão infinita e stack overflow em runtime.
Há duas formas seguras de evitar isso: nomear a propriedade do protocolo de maneira distinta (por exemplo, currentAuthorizationStatus) ou usar um pequeno adaptador por composição que encapsula uma instância privada de CLLocationManager. Eu prefiro o adaptador por composição porque ele também permite controlar o ciclo de vida da instância, encapsular diferenças de versão do iOS e evitar conformidades retroativas em tipos da Apple, que o Swift 6 inclusive sinaliza com avisos de compilação.
Desenhando uma fronteira limpa entre CoreLocation e o domínio
Vamos dividir a arquitetura em três peças pequenas: os modelos puros de domínio, o protocolo que representa a camada de hardware e o serviço responsável por aplicar filtros de qualidade e gerenciar o ciclo de vida do GPS. Repare que apenas o adaptador e o serviço importam CoreLocation:
import Foundation
import CoreLocation
// 1. Modelos puros de domínio (podem viver em um módulo sem CoreLocation)
public struct GeoCoordinate: Equatable, Sendable {
public let latitude: Double
public let longitude: Double
public let horizontalAccuracy: Double
public let timestamp: Date
public init(latitude: Double, longitude: Double, horizontalAccuracy: Double, timestamp: Date) {
self.latitude = latitude
self.longitude = longitude
self.horizontalAccuracy = horizontalAccuracy
self.timestamp = timestamp
}
}
public enum LocationServiceError: Error, Equatable, Sendable {
case permissionDenied
case permissionRestricted
case servicesDisabled
case inaccurateReading
case underlyingFailure(String)
}
public enum LocationAuthorization: Equatable, Sendable {
case notDetermined
case denied
case restricted
case authorized(fullAccuracy: Bool)
}
// 2. Contrato de baixo nível para o gerenciador de hardware
public protocol LocationEngineDelegate: AnyObject {
func engineDidChangeAuthorization(_ status: LocationAuthorization)
func engineDidReceiveCoordinates(_ coordinates: [GeoCoordinate])
func engineDidFail(with error: Error)
}
public protocol LocationEngine: AnyObject {
var delegate: LocationEngineDelegate? { get set }
var currentAuthorization: LocationAuthorization { get }
var isLocationServicesEnabled: Bool { get }
func requestWhenInUseAuthorization()
func startUpdatingLocation()
func stopUpdatingLocation()
}
// 3. Adaptador concreto encapsulando o CLLocationManager real
public final class AppleLocationEngine: NSObject, LocationEngine, CLLocationManagerDelegate {
private let manager: CLLocationManager
public weak var delegate: LocationEngineDelegate?
public init(manager: CLLocationManager = CLLocationManager(), accuracy: CLLocationAccuracy = kCLLocationAccuracyHundredMeters) {
self.manager = manager
super.init()
self.manager.desiredAccuracy = accuracy
self.manager.delegate = self
}
public var isLocationServicesEnabled: Bool {
CLLocationManager.locationServicesEnabled()
}
public var currentAuthorization: LocationAuthorization {
let isFull = manager.accuracyAuthorization == .fullAccuracy
switch manager.authorizationStatus {
case .notDetermined:
return .notDetermined
case .restricted:
return .restricted
case .denied:
return .denied
case .authorizedWhenInUse, .authorizedAlways:
return .authorized(fullAccuracy: isFull)
@unknown default:
return .denied
}
}
public func requestWhenInUseAuthorization() {
manager.requestWhenInUseAuthorization()
}
public func startUpdatingLocation() {
manager.startUpdatingLocation()
}
public func stopUpdatingLocation() {
manager.stopUpdatingLocation()
}
public func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
delegate?.engineDidChangeAuthorization(currentAuthorization)
}
public func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
let mapped = locations.map { location in
GeoCoordinate(
latitude: location.coordinate.latitude,
longitude: location.coordinate.longitude,
horizontalAccuracy: location.horizontalAccuracy,
timestamp: location.timestamp
)
}
delegate?.engineDidReceiveCoordinates(mapped)
}
public func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
delegate?.engineDidFail(with: error)
}
} Com essa separação, o LocationService concentra as regras que realmente importam no dia a dia: checar se o usuário negou permissão antes de ligar o GPS, descartar coordenadas cacheadas antigas (o iOS frequentemente entrega uma posição antiga de minutos atrás no primeiro callback) e ignorar leituras com horizontalAccuracy < 0, que segundo a própria documentação da Apple indicam coordenada inválida.
public final class LocationService: LocationEngineDelegate {
private let engine: LocationEngine
private let now: () -> Date
private let maxAgeSeconds: TimeInterval
private let maxAcceptedAccuracy: Double
private var pendingCompletion: ((Result<GeoCoordinate, LocationServiceError>) -> Void)?
public init(
engine: LocationEngine = AppleLocationEngine(),
maxAgeSeconds: TimeInterval = 15,
maxAcceptedAccuracy: Double = 150,
now: @escaping () -> Date = Date.init
) {
self.engine = engine
self.maxAgeSeconds = maxAgeSeconds
self.maxAcceptedAccuracy = maxAcceptedAccuracy
self.now = now
self.engine.delegate = self
}
public func fetchCurrentCoordinate(completion: @escaping (Result<GeoCoordinate, LocationServiceError>) -> Void) {
guard engine.isLocationServicesEnabled else {
completion(.failure(.servicesDisabled))
return
}
pendingCompletion = completion
switch engine.currentAuthorization {
case .notDetermined:
engine.requestWhenInUseAuthorization()
case .denied:
finish(with: .failure(.permissionDenied))
case .restricted:
finish(with: .failure(.permissionRestricted))
case .authorized:
engine.startUpdatingLocation()
}
}
public func engineDidChangeAuthorization(_ status: LocationAuthorization) {
guard pendingCompletion != nil else { return }
switch status {
case .authorized:
engine.startUpdatingLocation()
case .denied:
finish(with: .failure(.permissionDenied))
case .restricted:
finish(with: .failure(.permissionRestricted))
case .notDetermined:
break
}
}
public func engineDidReceiveCoordinates(_ coordinates: [GeoCoordinate]) {
guard pendingCompletion != nil else { return }
let valid = coordinates.last { coord in
let age = abs(now().timeIntervalSince(coord.timestamp))
return coord.horizontalAccuracy >= 0
&& coord.horizontalAccuracy <= maxAcceptedAccuracy
&& age <= maxAgeSeconds
}
guard let coordinate = valid else { return }
engine.stopUpdatingLocation()
finish(with: .success(coordinate))
}
public func engineDidFail(with error: Error) {
engine.stopUpdatingLocation()
finish(with: .failure(.underlyingFailure(error.localizedDescription)))
}
private func finish(with result: Result<GeoCoordinate, LocationServiceError>) {
let callback = pendingCompletion
pendingCompletion = nil
callback?(result)
}
} Injetar a closure now: () -> Date parece um detalhe menor, mas elimina outra fonte clássica de instabilidade nos testes. Assim conseguimos simular um timestamp de dois minutos atrás sem depender do relógio real da máquina. Se o seu projeto já usa async/await e CheckedContinuation ou AsyncStream, a mesma camada LocationService pode expor um método assíncrono por cima desse fluxo, seguindo os cuidados de isolamento descritos em concorrência moderna em Swift com async/await e Actors.
Escrevendo testes unitários rápidos e determinísticos
Com o protocolo LocationEngine em mãos, o dublê de testes (Spy) tem menos de trinta linhas e consegue exercitar exatamente os caminhos críticos que antes exigiam aparelho na mão: permissão negada, coordenada velha descartada e desligamento do GPS após a primeira leitura válida. Essa mesma filosofia de isolar infraestrutura externa também aparece nos testes de rede que abordo em ambientes herméticos de teste com mock servers.
import XCTest
@testable import AppLocation
final class LocationEngineSpy: LocationEngine {
weak var delegate: LocationEngineDelegate?
var currentAuthorization: LocationAuthorization = .authorized(fullAccuracy: true)
var isLocationServicesEnabled = true
private(set) var requestAuthCount = 0
private(set) var startUpdatingCount = 0
private(set) var stopUpdatingCount = 0
func requestWhenInUseAuthorization() { requestAuthCount += 1 }
func startUpdatingLocation() { startUpdatingCount += 1 }
func stopUpdatingLocation() { stopUpdatingCount += 1 }
func simulateLocations(_ coordinates: [GeoCoordinate]) {
delegate?.engineDidReceiveCoordinates(coordinates)
}
func simulateAuthorizationChange(_ status: LocationAuthorization) {
currentAuthorization = status
delegate?.engineDidChangeAuthorization(status)
}
}
final class LocationServiceTests: XCTestCase {
func test_fetchCoordinate_whenPermissionDenied_returnsErrorWithoutStartingGPS() {
let spy = LocationEngineSpy()
spy.currentAuthorization = .denied
let sut = LocationService(engine: spy)
var received: Result<GeoCoordinate, LocationServiceError>?
sut.fetchCurrentCoordinate { received = $0 }
XCTAssertEqual(received, .failure(.permissionDenied))
XCTAssertEqual(spy.startUpdatingCount, 0)
}
func test_fetchCoordinate_ignoresStaleAndInvalidReadingsUntilFreshFixArrives() {
let fixedNow = Date(timeIntervalSince1970: 1_700_000_000)
let spy = LocationEngineSpy()
let sut = LocationService(engine: spy, maxAgeSeconds: 15, maxAcceptedAccuracy: 100, now: { fixedNow })
var received: Result<GeoCoordinate, LocationServiceError>?
sut.fetchCurrentCoordinate { received = $0 }
let stale = GeoCoordinate(
latitude: -23.5505,
longitude: -46.6333,
horizontalAccuracy: 20,
timestamp: fixedNow.addingTimeInterval(-60)
)
let invalid = GeoCoordinate(
latitude: -23.5505,
longitude: -46.6333,
horizontalAccuracy: -1,
timestamp: fixedNow
)
spy.simulateLocations([stale, invalid])
XCTAssertNil(received)
XCTAssertEqual(spy.stopUpdatingCount, 0)
let fresh = GeoCoordinate(
latitude: -23.5614,
longitude: -46.6559,
horizontalAccuracy: 35,
timestamp: fixedNow.addingTimeInterval(-2)
)
spy.simulateLocations([fresh])
XCTAssertEqual(received, .success(fresh))
XCTAssertEqual(spy.stopUpdatingCount, 1)
}
} Esses dois testes rodam em menos de cinco milissegundos em qualquer runner Linux ou macOS sem abrir alerta de permissão e sem depender de simulador carregado com arquivo GPX.
Evoluindo a abstração para async/await e CLLocationUpdate
Quem mantém projetos com deployment target mínimo no iOS 17 já pode experimentar a API moderna CLLocationUpdate.liveUpdates(), que entrega um AsyncSequence sem exigir herança de NSObject nem implementação de delegate. Ainda assim, o princípio de isolamento continua exatamente o mesmo: você não deve chamar CLLocationUpdate.liveUpdates() direto dentro de uma View SwiftUI ou de um ViewModel.
A vantagem da fronteira que construímos acima aparece justamente nesse momento de transição de SDK. Você pode criar um novo adaptador ModernLocationEngine usando CLLocationUpdate para aparelhos no iOS 17+ e manter o AppleLocationEngine para clientes em versões anteriores, trocando apenas a implementação injetada no ponto de montagem do aplicativo. Nenhum teste de domínio quebra e nenhuma tela precisa saber qual geração de API da Apple está rodando por baixo.
Também vale um cuidado específico ao expor métodos async throws por cima do LocationService: sempre proteja o cancelamento de tarefas com withTaskCancellationHandler. Se o usuário sai da tela de busca de agências enquanto o GPS ainda tenta obter sinal dentro de um prédio, o handler de cancelamento chama stopUpdatingLocation() imediatamente, evitando que o hardware fique ligado à toa em segundo plano.
Armadilhas reais de CoreLocation em produção
Mesmo com bons testes unitários, existem comportamentos específicos do framework da Apple que pegam engenheiros experientes de surpresa. Reuni os quatro casos que mais geram chamados em produção:
| Armadilha no CoreLocation | Sintoma observado em produção | Prevenção recomendada |
|---|---|---|
Instanciar CLLocationManager em fila background sem RunLoop ativo | Callbacks do delegate nunca disparam e a tela fica em loading infinito | Criar o adaptador sempre na main thread (@MainActor) |
Chamar CLLocationManager.locationServicesEnabled() na main thread em excesso | Aviso de UI unresponsiveness no Xcode e travamento breve no cold start | Avaliar o estado assincronamente ou reagir ao delegate locationManagerDidChangeAuthorization |
| Ignorar precisão reduzida (Reduced Accuracy, iOS 14+) | Coordenada deslocada em vários quilômetros quebra validação antifraude ou busca de lojas | Verificar accuracyAuthorization e pedir precisão temporária apenas quando o fluxo exigir |
Esquecer de chamar stopUpdatingLocation() em erro ou cancelamento de tela | Ícone azul de GPS preso na barra superior e dreno rápido de bateria | Chamar stopUpdatingLocation() no sucesso, no erro, no timeout e no deinit |
Quando abstrair e checklist de revisão de PR
Vale criar toda essa camada de protocolo e adaptador sempre que a localização influenciar regra de negócio, telemetria antifraude, elegibilidade de oferta ou roteamento de telas. Já em um protótipo descartável ou em uma tela puramente visual que apenas centraliza um MKMapView usando showsUserLocation = true sem nenhuma lógica condicional, abstrair o gerenciador adiciona código sem retorno real.
Na revisão de PR de qualquer funcionalidade que toque geolocalização, confira estes pontos antes de aprovar:
- O arquivo de ViewModel, Presenter ou Interactor não contém
import CoreLocation. - A descrição de privacidade
NSLocationWhenInUseUsageDescriptionnoInfo.plistexplica em português claro por que o recurso precisa da localização. - Coordenadas com
horizontalAccuracy < 0ou timestamp antigo são filtradas antes de seguir para a camada de rede. - Existe timeout explícito caso o aparelho esteja sem sinal de satélite ou Wi-Fi, evitando que o usuário fique preso em um spinner eterno.
- O teste unitário cobre pelo menos os estados
notDetermined,denied, leitura inválida e limpeza do GPS após a entrega do resultado.
