Como o novo framework de testes de integração assíncronos flexibiliza restrições de transação, permite chamadas HTTP reais e viabiliza asserções determinísticas contra serviços externos.
Durante mais de duas décadas, qualquer desenvolvedor que precisasse testar uma integração externa em Apex esbarrava na mesma regra rígida da máquina virtual do Salesforce: a execução de testes convencionais (@IsTest) proíbe expressamente chamadas HTTP ativas contra a rede externa. Para satisfazer a cobertura de código, a plataforma exigia a implementação de instâncias simuladas através da interface HttpCalloutMock ou de frameworks baseados no Stub API.
Embora os mocks funcionem perfeitamente para validar a lógica interna de parsing de um JSON pré-determinado, eles apresentam uma falha estrutural evidente: um teste unitário com mock apenas comprova que seu código sabe lidar com a resposta hipotética que você mesmo desenhou, mas nada garante que ele sobreviverá às mudanças reais de contrato, autenticações de rede ou instabilidades do endpoint em produção.
Com a publicação oficial das Release Notes do Salesforce Winter ’27, a engenharia da plataforma introduz um novo paradigma: os Apex Integration Tests (Developer Preview).
Diferente dos testes unitários tradicionais, os testes de integração flexibilizam as barreiras de rollback transacional, permitem a execução de chamadas HTTP reais sem mocks e introduzem o método nativo Test.commitTestOnly(), possibilitando que agentes do Agentforce e mecanismos do Data 360 processem registros em threads separadas durante a mesma esteira de testes.
Neste guia técnico, vamos dissecar o funcionamento desse novo framework, analisar suas restrições operacionais e implementar um teste ponta a ponta completo em scratch orgs.
1. Testes unitários vs. testes de integração: A mudança conceitual
Antes de escrever qualquer linha de código, o arquiteto precisa compreender que os Apex Integration Tests não foram criados para substituir a suite de testes unitários existente, mas para complementar a pirâmide de testes corporativa.
Matriz comparativa de comportamento
| Característica | Testes Unitários Clássicos (@IsTest) | Apex Integration Tests (Winter ’27) |
|---|---|---|
| Objetivo Principal | Isolar regras de negócio, triggers, flows e cálculos locais. | Validar a interoperabilidade real entre o Salesforce e serviços externos (REST, Agentforce, Data 360). |
| Chamadas HTTP Externas | Proibidas em tempo de execução (Exigem HttpCalloutMock). | Permitidas diretamente (Requisições reais sobre a rede externa). |
| Comportamento Transacional | Rollback obrigatório e automático de todas as operações DML ao final do teste. | Permite a persistência intermediária via Test.commitTestOnly(). |
| Visibilidade de Dados | Isolado por padrão (seeAllData=false). | Opera sobre os dados da org (seeAllData=true). |
| Ambiente de Execução | Todas as orgs (Scratch Orgs, Sandboxes e Produção durante deploy). | Exclusivo para Scratch Orgs (Execução assíncrona, 1 teste concorrente por org). |
2. O método test.committestonly(): Resolvendo o problema de concorrência
Em integrações complexas (especialmente com o Agentforce e Data 360), o serviço chamado atua em uma thread ou container separado daquele que está rodando o código Apex.
Em um teste unitário comum, como a transação está pendente em memória aguardando o rollback final, qualquer serviço externo que consultar a API REST do Salesforce receberá um erro de registro não encontrado (404 Not Found).
Para resolver esse impasse, o framework do Winter ’27 introduz:
apexTest.commitTestOnly();
Ao invocar essa instrução, o Apex força a gravação definitiva dos registros inseridos até aquele ponto na base de dados da scratch org. Quando o Agentforce ou a API externa for acionada no passo seguinte, ela encontrará os registros persistidos e conseguirá executar consultas e atualizações reais.
3. Implementando um teste de integração real ponta a ponta
Vamos construir uma classe de teste de integração que valida a comunicação entre o Salesforce e um serviço externo de autorização de crédito, acionando em seguida um agente do Agentforce para processar o caso.
Configuração da scratch org (project-scratch-def.json)
Para habilitar o Developer Preview dos testes de integração, a definição da scratch org deve declarar a feature correspondente:
{
"orgName": "OnlySalesforce Integration Testing Org",
"edition": "Developer",
"features": ["EnableApexIntegrationTesting", "DataCloud", "AgentforcePlatform"],
"settings": {
"lightningExperienceSettings": {
"enableLibreLightning": true
}
}
}Código da classe de teste: externalcreditserviceintegrationtest.cls
/*
* @description Teste de integração assíncrono que valida callouts HTTP reais
* e interação com o motor do Agentforce sem uso de mocks.
* Disponível no Salesforce Winter '27 (Developer Preview).
*/
@IsTest(isIntegration=true)
public with sharing class ExternalCreditServiceIntegrationTest {
@IsTest
static void testRealCreditVerificationAndAgentProcessing() {
// 1. Criação do registro de teste na Scratch Org
Account corporateAccount = new Account(
Name = 'Indústrias Metalúrgicas Globais S.A.',
AccountNumber = 'BR-98421-TAX',
AnnualRevenue = 5000000.00
);
insert corporateAccount;
// 2. Persistência definitiva dos dados para que threads externas enxerguem o registro
Test.commitTestOnly();
// 3. Execução da chamada HTTP real contra o endpoint corporativo (Sem HttpCalloutMock!)
HttpRequest request = new HttpRequest();
request.setEndpoint('https://api.gateway-sandbox.enterprise.com/v1/credit/verify');
request.setMethod('POST');
request.setHeader('Content-Type', 'application/json');
request.setHeader('X-API-Key', 'sec_test_live_token_2026');
Map<String, Object> requestPayload = new Map<String, Object>{
'accountNumber' => corporateAccount.AccountNumber,
'companyName' => corporateAccount.Name,
'requestedLimit' => 150000.00
};
request.setBody(JSON.serialize(requestPayload));
Http httpEngine = new Http();
HttpResponse response = httpEngine.send(request);
// 4. Asserções reais contra a resposta do gateway externo
Assert.isNotNull(response, 'A resposta HTTP do endpoint externo não pode ser nula.');
Assert.areEqual(200, response.getStatusCode(), 'O gateway externo de crédito deve responder com status 200 OK.');
Map<String, Object> responseBody = (Map<String, Object>) JSON.deserializeUntyped(response.getBody());
String creditStatus = (String) responseBody.get('status');
Assert.areEqual('APPROVED', creditStatus, 'O status retornado pelo parceiro financeiro deve ser APPROVED.');
// 5. Invocação real de ação do Agentforce utilizando os dados retornados
AIAgentSession testSession = new AIAgentSession(
AccountId__c = corporateAccount.Id,
Channel = 'IntegrationTest',
Status = 'Active'
);
insert testSession;
Test.commitTestOnly();
// Consulta a persistência final na scratch org
Account verifiedAccount = [
SELECT Id, Name, (SELECT Id, Status FROM AIAgentSessions__r)
FROM Account
WHERE Id = :corporateAccount.Id
LIMIT 1
];
Assert.areEqual(1, verifiedAccount.AIAgentSessions__r.size(), 'A sessão do Agentforce deve estar vinculada à conta após o commit.');
}
}4. Limitações e diretrizes operacionais no Winter ’27
Como os Apex Integration Tests operam em ambiente Developer Preview e interagem com a rede real, os arquitetos de software devem atentar-se às seguintes restrições de infraestrutura:
- Limite de Concorrência Estrito: Apenas um único teste de integração pode ser executado por organização por vez. Suítes de CI/CD devem enfileirar os testes de integração sequencialmente, reservando execuções paralelas apenas para os testes unitários padrão.
- Tempo Limite de 10 Minutos: Cada método de teste de integração possui um tempo limite máximo de execução de 10 minutos (600 segundos), acomodando a latência natural de redes externas e o processamento de modelos de IA.
- Ambiente Restrito a Scratch Orgs: O framework não pode ser executado em organizações de produção ou durante validações de pacotes gerenciados no deploy. O deploy para produção continuará validando a cobertura de código obrigatória de 75% baseada exclusivamente nos testes unitários convencionais.
- Isolamento de Dados em Scratch Orgs: Como os testes de integração realizam commits permanentes na scratch org, desenhe scripts de teardown ou crie scratch orgs descartáveis a cada ciclo de pipeline para evitar poluição de dados residuais entre execuções.
5. Como estruturar a pirâmide de testes no Salesforce em 2026
Com a convivência dos dois modelos de teste, a recomendação arquitetural para equipes maduras de engenharia é dividir a qualidade de software em três camadas bem delineadas:
- Camada Base (Testes Unitários Rápidos): Representa 85% da suíte. Utiliza
@IsTestcom mocks locais, roda em segundos e valida cálculos de regras de negócio, triggers, controllers de LWC e classes utilitárias. - Camada Intermediária (Apex Integration Tests): Representa 10% da suíte. Executada em scratch orgs no pipeline noturno ou antes de merges na branch principal, disparando callouts reais contra sandboxes de parceiros externos, validando contratos OpenAPI e testando ações do Agentforce.
- Camada de Topo (Agentforce Testing Center): Representa 5% da suíte. Avalia a acurácia semântica de respostas de linguagem natural geradas pelos agentes contra conjuntos estruturados de utterances em CSV.
Conclusão
A introdução dos Apex Integration Tests no Salesforce Winter ’27 fecha uma lacuna histórica na engenharia da plataforma. Ao permitir chamadas HTTP reais e a persistência intencional com Test.commitTestOnly(), a Salesforce entrega aos desenvolvedores o ferramental necessário para garantir que integrações corporativas complexas, fluxos agênticos e consultas ao Data 360 sejam validados contra a realidade dos serviços de produção, e não apenas contra simulações estáticas em código.
Sua organização já está desenhando pipelines em scratch orgs para experimentar os testes de integração reais do Winter ’27? Compartilhe suas dúvidas e estratégias de automação nos comentários abaixo ou conecte-se conosco no LinkedIn.