Testes unitários de Durable Functions e SDKs para Tarefas Duráveis

Testes unitários de orquestrações duradouras ajudam-no a verificar a lógica de negócio e a detetar erros cedo. As orquestrações coordenam múltiplas atividades e podem tornar-se complexas rapidamente, por isso os testes protegem contra regressões à medida que o seu fluxo de trabalho evolui.

Seleciona o separador que corresponde ao teu projeto: Durable Functions se usares Funções do Azure, ou Durable Task SDKs se usares o SDK standalone sem Funções do Azure.

Com o Durable Functions, pode testar orquestradores, atividades e funções cliente (trigger) ao simular os objetos de contexto fornecidos pelo framework e chamar as suas funções diretamente. Esta abordagem isola a sua lógica de negócio do runtime do Funções do Azure.

Aqui está um teste minimalista do orquestrador em C# para mostrar o padrão:

[Fact]
public async Task MyOrchestrator_CallsActivity()
{
    var contextMock = new Mock<TaskOrchestrationContext>();
    contextMock.Setup(x => x.CallActivityAsync<string>(
        It.IsAny<TaskName>(), It.IsAny<string>(), It.IsAny<TaskOptions>()))
        .ReturnsAsync("result");

    var result = await MyOrchestrator.Run(contextMock.Object);

    Assert.Equal("result", result);
}

O resto deste artigo aborda este padrão em detalhe para C# e Python.

Os Durable Task SDKs autónomos fornecem infraestrutura de teste incorporada que executa orquestrações em memória sem dependências externas. Regista orquestradores e atividades com um trabalhador de teste, agenda orquestrações através de um cliente de teste e verificas os resultados. Não é preciso mockagem para C# e JavaScript. Python utiliza uma abordagem baseada em geradores com injeção manual de resultados.

Aqui está um teste mínimo de C# para mostrar o padrão:

[Fact]
public async Task MyOrchestrator_Completes()
{
    await using var host = await DurableTaskTestHost.StartAsync(tasks =>
    {
        tasks.AddOrchestrator<MyOrchestrator>();
        tasks.AddActivity<MyActivity>();
    });

    string id = await host.Client.ScheduleNewOrchestrationInstanceAsync(nameof(MyOrchestrator));
    var result = await host.Client.WaitForInstanceCompletionAsync(id, getInputsAndOutputs: true);

    Assert.Equal(OrchestrationRuntimeStatus.Completed, result.RuntimeStatus);
}

O resto deste artigo aborda este padrão em detalhe para C#, Python e JavaScript.

Pré-requisitos

xUnit — estrutura de testes
Moq — framework de simulação
Familiaridade com o modelo de trabalhador isolado .NET

xUnit — estrutura de testes
O pacote NuGet Microsoft.DurableTask.InProcessTestHost (v1.0.0 ou posterior)

Funções do orquestrador de testes

As funções do orquestrador coordenam atividades, temporizadores e eventos externos. Normalmente contêm mais lógica de negócio e beneficiam mais dos testes unitários.

Simule o contexto de orquestração para controlar os valores de retorno das invocações de atividade. Depois liga diretamente ao teu orquestrador e verifica a saída.

Considere este orquestrador que chama uma atividade três vezes:

[Function(nameof(HelloCitiesOrchestration))]
public static async Task<List<string>> HelloCities(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    var outputs = new List<string>
    {
        await context.CallActivityAsync<string>(nameof(SayHello), "Tokyo"),
        await context.CallActivityAsync<string>(nameof(SayHello), "Seattle"),
        await context.CallActivityAsync<string>(nameof(SayHello), "London")
    };

    return outputs;
}

Use o Moq para simular TaskOrchestrationContext e definir os valores esperados de retorno para cada chamada de atividade.

Observação

O padrão It.Is<TaskName>(...) é obrigatório porque CallActivityAsync aceita uma estrutura TaskName, não uma string simples. Moq precisa da correspondência explícita de tipos.

[Fact]
public async Task HelloCities_ReturnsExpectedGreetings()
{
    var contextMock = new Mock<TaskOrchestrationContext>();

    // Mock each activity call to return a known value
    contextMock.Setup(x => x.CallActivityAsync<string>(
        It.Is<TaskName>(n => n.Name == nameof(SayHello)),
        It.Is<string>(n => n == "Tokyo"),
        It.IsAny<TaskOptions>())).ReturnsAsync("Hello Tokyo!");

    contextMock.Setup(x => x.CallActivityAsync<string>(
        It.Is<TaskName>(n => n.Name == nameof(SayHello)),
        It.Is<string>(n => n == "Seattle"),
        It.IsAny<TaskOptions>())).ReturnsAsync("Hello Seattle!");

    contextMock.Setup(x => x.CallActivityAsync<string>(
        It.Is<TaskName>(n => n.Name == nameof(SayHello)),
        It.Is<string>(n => n == "London"),
        It.IsAny<TaskOptions>())).ReturnsAsync("Hello London!");

    var result = await HelloCitiesOrchestration.HelloCities(contextMock.Object);

    Assert.Equal(3, result.Count);
    Assert.Equal("Hello Tokyo!", result[0]);
    Assert.Equal("Hello Seattle!", result[1]);
    Assert.Equal("Hello London!", result[2]);
}

Considere este orquestrador que encadeia três chamadas de atividade:

import azure.durable_functions as df

def my_orchestrator(context: df.DurableOrchestrationContext):
    result1 = yield context.call_activity("say_hello", "Tokyo")
    result2 = yield context.call_activity("say_hello", "Seattle")
    result3 = yield context.call_activity("say_hello", "London")
    return [result1, result2, result3]

Simula o contexto e usa-o orchestrator_generator_wrapper para processar o gerador.

Observação

O Azure Durable Functions SDK fornece orchestrator_generator_wrapper para simular o mecanismo de repetição que aciona os geradores de orquestração em Python. O SDK independente Durable Task não inclui esta utilidade, por isso o separador Durable Task SDKs usa chamadas manuais gen.send() em vez disso.

import unittest
from unittest.mock import Mock, call
from azure.durable_functions.testing import orchestrator_generator_wrapper

from function_app import my_orchestrator


def mock_activity(activity_name, input_value):
    mock_task = Mock()
    mock_task.result = f"Hello {input_value}!"
    return mock_task


class TestOrchestrator(unittest.TestCase):
    def test_chaining_orchestrator(self):
        # Extract the raw orchestrator function from the Azure Functions decorator wrapper
        func_call = my_orchestrator.build().get_user_function().orchestrator_function

        context = Mock()
        context.call_activity = Mock(side_effect=mock_activity)

        user_orchestrator = func_call(context)
        values = list(orchestrator_generator_wrapper(user_orchestrator))

        expected_calls = [
            call("say_hello", "Tokyo"),
            call("say_hello", "Seattle"),
            call("say_hello", "London"),
        ]
        self.assertEqual(context.call_activity.call_args_list, expected_calls)
        self.assertEqual(values[-1], ["Hello Tokyo!", "Hello Seattle!", "Hello London!"])

Uso DurableTaskTestHost para executar orquestrações em memória. Regista o teu orquestrador de produção e as classes de atividades, agenda uma orquestração e valida o resultado.

Dadas estas classes de produção:

class HelloCitiesOrchestrator : TaskOrchestrator<string, List<string>>
{
    public override async Task<List<string>> RunAsync(
        TaskOrchestrationContext context, string input)
    {
        var outputs = new List<string>
        {
            await context.CallActivityAsync<string>(nameof(SayHelloActivity), "Tokyo"),
            await context.CallActivityAsync<string>(nameof(SayHelloActivity), "Seattle"),
            await context.CallActivityAsync<string>(nameof(SayHelloActivity), "London")
        };
        return outputs;
    }
}

class SayHelloActivity : TaskActivity<string, string>
{
    public override Task<string> RunAsync(TaskActivityContext context, string name)
    {
        return Task.FromResult($"Hello {name}!");
    }
}

Registe-os diretamente no hospedeiro de teste:

[Fact]
public async Task HelloCities_ReturnsExpectedGreetings()
{
    await using var host = await DurableTaskTestHost.StartAsync(tasks =>
    {
        tasks.AddOrchestrator<HelloCitiesOrchestrator>();
        tasks.AddActivity<SayHelloActivity>();
    });

    string instanceId = await host.Client.ScheduleNewOrchestrationInstanceAsync(
        nameof(HelloCitiesOrchestrator));
    OrchestrationMetadata result = await host.Client.WaitForInstanceCompletionAsync(
        instanceId, getInputsAndOutputs: true);

    Assert.Equal(OrchestrationRuntimeStatus.Completed, result.RuntimeStatus);

    var output = result.ReadOutputAs<List<string>>();
    Assert.Equal(3, output.Count);
    Assert.Equal("Hello Tokyo!", output[0]);
    Assert.Equal("Hello Seattle!", output[1]);
    Assert.Equal("Hello London!", output[2]);
}

DurableTaskTestHost Executa um motor completo de orquestração em memória. Não são necessários serviços externos nem processos sidecar.

O SDK do Python Durable Task ainda não fornece um ambiente de teste incorporado como o C# e o JavaScript. Use o mocking padrão para testar a lógica do orquestrador. Simule o OrchestrationContext e acione o gerador enviando resultados simulados de atividade para cada yield.

Observação

Ao contrário do SDK Azure Durable Functions (que fornece orchestrator_generator_wrapper), o SDK Durable Task autónomo exige que avances manualmente o gerador com gen.send(). Isto dá-lhe controlo explícito sobre os resultados simulados da atividade.

from unittest.mock import Mock, call
from durabletask import task


def hello(ctx: task.ActivityContext, name: str) -> str:
    return f"Hello {name}!"


def hello_cities(ctx: task.OrchestrationContext, _):
    result1 = yield ctx.call_activity(hello, input="Tokyo")
    result2 = yield ctx.call_activity(hello, input="Seattle")
    result3 = yield ctx.call_activity(hello, input="London")
    return [result1, result2, result3]


def test_hello_cities():
    ctx = Mock(spec=task.OrchestrationContext)

    # Each call_activity returns a mock task; collect them to send results back
    mock_tasks = []
    def fake_call_activity(activity, *, input):
        t = Mock()
        t._input = input
        mock_tasks.append(t)
        return t

    ctx.call_activity = Mock(side_effect=fake_call_activity)

    # Start the generator
    gen = hello_cities(ctx, None)
    yielded = next(gen)  # first yield: call_activity(hello, input="Tokyo")

    # Send simulated results back for each yield
    try:
        yielded = gen.send("Hello Tokyo!")
        yielded = gen.send("Hello Seattle!")
        gen.send("Hello London!")
    except StopIteration as e:
        result = e.value

    # Verify the orchestrator called the right activities
    assert ctx.call_activity.call_count == 3
    assert result == ["Hello Tokyo!", "Hello Seattle!", "Hello London!"]

Esta abordagem testa o fluxo de controle do orquestrador sem depender das funcionalidades internas do SDK.

Usar TestOrchestrationWorker e TestOrchestrationClient para executar orquestrações em memória:

const {
    InMemoryOrchestrationBackend,
    TestOrchestrationClient,
    TestOrchestrationWorker,
    OrchestrationStatus,
} = require("@microsoft/durabletask-js");

test("helloCities returns expected greetings", async () => {
    const backend = new InMemoryOrchestrationBackend();
    const client = new TestOrchestrationClient(backend);
    const worker = new TestOrchestrationWorker(backend);

    const sayHello = async (_, name) => `Hello ${name}!`;

    const helloCities = async function* (ctx) {
        const outputs = [];
        outputs.push(yield ctx.callActivity(sayHello, "Tokyo"));
        outputs.push(yield ctx.callActivity(sayHello, "Seattle"));
        outputs.push(yield ctx.callActivity(sayHello, "London"));
        return outputs;
    };

    worker.addOrchestrator(helloCities);
    worker.addActivity(sayHello);
    await worker.start();

    const id = await client.scheduleNewOrchestration(helloCities);
    const state = await client.waitForOrchestrationCompletion(id, true, 10);

    expect(state.runtimeStatus).toEqual(OrchestrationStatus.COMPLETED);
    expect(JSON.parse(state.serializedOutput)).toEqual([
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!",
    ]);

    await worker.stop();
});

A infraestrutura de teste opera o motor de orquestração completo no mesmo processo. Não são necessários serviços de sidecar nem externos.

Funções de atividade de teste

As funções de atividade contêm o trabalho real — chamar APIs, processar dados ou interagir com sistemas externos. São o tipo de função mais simples de testar porque não têm um comportamento de repetição específico do framework.

As funções de atividade em Funções do Azure recebem uma entrada e, opcionalmente, uma FunctionContext. Teste-os como qualquer outra função:

[Function(nameof(SayHello))]
public static string SayHello(
    [ActivityTrigger] string name, FunctionContext executionContext)
{
    return $"Hello {name}!";
}

[Fact]
public void SayHello_ReturnsExpectedGreeting()
{
    var result = HelloCitiesOrchestration.SayHello("Tokyo", Mock.Of<FunctionContext>());
    Assert.Equal("Hello Tokyo!", result);
}

As funções de atividade no Funções do Azure são funções Python regulares. Teste-os diretamente. Para mais informações, veja Funções do Azure Python testes unitários.

def say_hello(name: str) -> str:
    return f"Hello {name}!"

def test_say_hello():
    result = say_hello("Tokyo")
    assert result == "Hello Tokyo!"

As funções de atividade recebem um objeto de contexto e uma entrada. O contexto fornece metadados como o ID de orquestração e o ID da tarefa, mas a maioria dos testes não precisa deles.

Usando a SayHelloActivity classe do exemplo do orquestrador, chame RunAsync diretamente com um contexto simulado:

[Fact]
public async Task SayHello_ReturnsExpectedGreeting()
{
    var activity = new SayHelloActivity();
    var contextMock = new Mock<TaskActivityContext>();

    var result = await activity.RunAsync(contextMock.Object, "Tokyo");

    Assert.Equal("Hello Tokyo!", result);
}

Quando usas DurableTaskTestHost, as atividades também são executadas como parte do teste de orquestração. Não precisas de testes de atividade separados a menos que a atividade tenha lógica complexa.

Teste a função de atividade diretamente — não é necessária qualquer configuração especial:

from durabletask import task


def hello(ctx: task.ActivityContext, name: str) -> str:
    return f"Hello {name}!"


def test_hello():
    ctx = Mock(spec=task.ActivityContext)
    result = hello(ctx, "Tokyo")
    assert result == "Hello Tokyo!"

Teste diretamente a função de atividade:

const sayHello = async (_, name) => `Hello ${name}!`;

test("sayHello returns expected greeting", async () => {
    const result = await sayHello(undefined, "Tokyo");
    expect(result).toBe("Hello Tokyo!");
});

Funções do cliente de teste

As funções de cliente (também chamadas funções de gatilho) iniciam orquestrações e gerenciam instâncias. Usam a vinculação durável do cliente para interagir com o motor de orquestração.

Considere este gatilho HTTP que inicia uma orquestração:

[Function("HelloCitiesOrchestration_HttpStart")]
public static async Task<HttpResponseData> HttpStart(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    [DurableClient] DurableTaskClient client,
    FunctionContext executionContext)
{
    string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
        nameof(HelloCitiesOrchestration));
    return await client.CreateCheckStatusResponseAsync(req, instanceId);
}

Mock DurableTaskClient para retornar um ID de instância conhecido.

[Fact]
public async Task HttpStart_ReturnsAccepted()
{
    var durableClientMock = new Mock<DurableTaskClient>("testClient");
    var functionContextMock = new Mock<FunctionContext>();
    var instanceId = "test-instance-id";

    durableClientMock
        .Setup(x => x.ScheduleNewOrchestrationInstanceAsync(
            It.IsAny<TaskName>(),
            It.IsAny<object>(),
            It.IsAny<StartOrchestrationOptions>(),
            It.IsAny<CancellationToken>()))
        .ReturnsAsync(instanceId);

    var mockRequest = CreateMockHttpRequest(functionContextMock.Object);

    var responseMock = new Mock<HttpResponseData>(functionContextMock.Object);
    responseMock.SetupGet(r => r.StatusCode).Returns(HttpStatusCode.Accepted);

    durableClientMock
        .Setup(x => x.CreateCheckStatusResponseAsync(
            It.IsAny<HttpRequestData>(),
            It.IsAny<string>(),
            It.IsAny<CancellationToken>()))
        .ReturnsAsync(responseMock.Object);

    var result = await HelloCitiesOrchestration.HttpStart(
        mockRequest, durableClientMock.Object, functionContextMock.Object);

    Assert.Equal(HttpStatusCode.Accepted, result.StatusCode);
}

Considere este gatilho HTTP que inicia uma orquestração:

@app.route(route="start")
@app.durable_client_input(client_name="client")
async def http_start(req: func.HttpRequest, client):
    instance_id = await client.start_new("my_orchestrator")
    return client.create_check_status_response(req, instance_id)

Simular o cliente persistente:

import asyncio
import unittest
import azure.functions as func
from unittest.mock import AsyncMock, Mock

from function_app import http_start


class TestClientFunction(unittest.TestCase):
    def test_http_start(self):
        # Extract the raw client function from the Azure Functions decorator wrapper
        func_call = http_start.build().get_user_function().client_function

        req = func.HttpRequest(
            method="GET",
            body=b"{}",
            url="/api/start",
        )

        client = Mock()
        client.start_new = AsyncMock(return_value="test-instance-id")
        client.create_check_status_response = Mock(return_value="check_status_response")

        result = asyncio.run(func_call(req, client))

        client.start_new.assert_called_once_with("my_orchestrator")
        client.create_check_status_response.assert_called_once_with(req, "test-instance-id")

Operações do cliente de teste

Com os SDKs de Tarefas Duráveis independentes, as operações do cliente (agendamento de orquestrações, consulta de estado, geração de eventos) utilizam o mesmo TestOrchestrationClient que já foi mostrado nos testes do orquestrador. Não existe uma função cliente separada — chama diretamente a API do cliente.

DurableTaskTestHost expõe host.Client, que é um DurableTaskClient totalmente funcional. Use-o para testar operações ao nível do cliente, como agendamento, consulta ou terminação de orquestrações:

[Fact]
public async Task Client_CanQueryOrchestrationStatus()
{
    await using var host = await DurableTaskTestHost.StartAsync(tasks =>
    {
        tasks.AddOrchestrator<HelloCitiesOrchestrator>();
        tasks.AddActivity<SayHelloActivity>();
    });

    string instanceId = await host.Client.ScheduleNewOrchestrationInstanceAsync(
        nameof(HelloCitiesOrchestrator));

    // Query status while the orchestration runs
    OrchestrationMetadata metadata = await host.Client.WaitForInstanceCompletionAsync(
        instanceId, getInputsAndOutputs: true);

    Assert.Equal(OrchestrationRuntimeStatus.Completed, metadata.RuntimeStatus);
    Assert.Equal(instanceId, metadata.InstanceId);
}

O Python Durable Task SDK ainda não fornece um cliente de teste incorporado. Testar a lógica ao nível do cliente (agendamento, consulta) simulando a TaskHubGrpcClient:

from unittest.mock import AsyncMock, Mock


def test_schedule_orchestration():
    client = Mock()
    client.schedule_new_orchestration = AsyncMock(return_value="test-id")

    # Call your application code that uses the client
    import asyncio
    instance_id = asyncio.run(client.schedule_new_orchestration("my_orchestrator"))

    assert instance_id == "test-id"
    client.schedule_new_orchestration.assert_called_once_with("my_orchestrator")

TestOrchestrationClient suporta as mesmas operações que o cliente de produção. Use-o para testar agendamento, consultas de estado e criação de eventos:

const {
    InMemoryOrchestrationBackend,
    TestOrchestrationClient,
    TestOrchestrationWorker,
    OrchestrationStatus,
} = require("@microsoft/durabletask-js");

test("client can schedule and query orchestration", async () => {
    const backend = new InMemoryOrchestrationBackend();
    const client = new TestOrchestrationClient(backend);
    const worker = new TestOrchestrationWorker(backend);

    const myOrchestrator = async function* (ctx) {
        return "done";
    };

    worker.addOrchestrator(myOrchestrator);
    await worker.start();

    const id = await client.scheduleNewOrchestration(myOrchestrator);
    const state = await client.waitForOrchestrationCompletion(id, true, 10);

    expect(state.runtimeStatus).toEqual(OrchestrationStatus.COMPLETED);
    expect(JSON.parse(state.serializedOutput)).toBe("done");

    await worker.stop();
});

Comentários

Esta página foi útil?

Last updated on 2026-04-28

Testes unitários de Durable Functions e SDKs para Tarefas Duráveis

Pré-requisitos

Funções do orquestrador de testes

Funções de atividade de teste

Funções do cliente de teste

Operações do cliente de teste

Conteúdo relacionado

Comentários

Recursos adicionais