Compartilhar via

Ferramenta de Teste de Aplicações do Teams

  • Artigo

Observação

A Ferramenta de Teste de Aplicações do Teams está disponível na versão de pré-lançamento mais recente do Microsoft Teams Toolkit. Certifique-se de que instala a versão de pré-lançamento mais recente do Teams Toolkit.

A Ferramenta de Teste de Aplicações do Teams (Ferramenta de Teste) facilita a depuração de aplicações baseadas em bots. Pode conversar com o seu bot e ver as respetivas mensagens e Cartões Ajustáveis tal como aparecem no Microsoft Teams. Não precisa de uma conta de programador do Microsoft 365, túnel ou registo de aplicações e bots do Teams para utilizar a Ferramenta de Teste.

A imagem seguinte mostra uma aplicação de exemplo a apresentar um Cartão Ajustável com uma lista de comandos na Ferramenta de Teste. Também fornece uma descrição dos comandos para que possa testar a sua aplicação sem procurar manualmente o seu código:

Captura de ecrã a mostrar o Cartão Ajustável da Ferramenta de Teste de Aplicações do Teams.

Seguem-se as vantagens da Ferramenta de Teste:

  • Ambiente sandbox: o ambiente sandbox da Ferramenta de Teste emula o comportamento, o aspeto e a experiência de utilizador do Teams.

  • Túnel: um serviço de túnel externo não é necessário, uma vez que a Ferramenta de Teste é executada num servidor local com o qual o bot pode comunicar.

  • Reduzir dependências de conta: o inquilino do Programador do Microsoft 365 e as permissões de carregamento da aplicação não são necessárias para depurar o bot.

  • Iterações rápidas do ciclo interno: otimiza o processo de efetuar alterações à estrutura da aplicação e à lógica do bot sem ter de reimplementar o bot na cloud.

  • Dados e atividades fictícios: a Ferramenta de Teste facilita o teste de cenários complexos, como enviar uma mensagem de boas-vindas quando um novo membro entra no canal, através de dados fictícios e acionadores de atividade.

  • Fiável: a Ferramenta de Teste é fiável, uma vez que o Cartão Ajustável do bot utiliza a mesma tecnologia de composição que no Teams.

  • Integração com aplicações de bot existentes do Teams: a Ferramenta de Teste integra-se facilmente com aplicações de bot do Teams existentes criadas com o SDK do Bot Framework.

  • Suporte para diferentes âmbitos: a Ferramenta de Teste suporta testes em âmbitos de chat pessoais, de equipa e de grupo.

Pré-requisitos

Certifique-se de que instala as seguintes ferramentas para criar e implementar os bots na Ferramenta de Teste:

  Instalar Para usar...
  Kit de ferramentas do Teams Uma extensão do Microsoft Visual Studio Code que cria um projeto estruturado para a sua aplicação. Utilize a versão de pré-lançamento mais recente.
  Node.js Ambiente de runtime do JavaScript de back-end. Para obter mais informações, veja Node.js tabela de compatibilidade de versões para o tipo de projeto.
  Visual Studio Code Ambientes de compilação JavaScript, TypeScript ou Estrutura do SharePoint (SPFx). Utilize a versão mais recente.

Compreender a Ferramenta de Teste

A Ferramenta de Teste é um pacote npm que tem um comando da CLI chamado teamsapptester. Quando executa teamsapptester starto , abre uma aplicação Web no seu computador local que emula o cliente Web do Teams e o serviço Bot Framework. Esta aplicação Web não precisa de recursos na cloud, uma vez que utiliza dados fictícios para simular as informações contextuais do Teams.

Para utilizar um bot do Teams na Ferramenta de Teste, tem de fornecer:

  • Ponto final da mensagem: um ponto final de mensagem de bot é o URL que liga a Ferramenta de Teste e o bot. Pode atualizar o ponto final com a BOT_ENDPOINT variável de ambiente ou utilizar o valor predefinido de http://localhost:3978/api/messages.
  • Ficheiro de configuração (Opcional): um ficheiro de configuração informa a Ferramenta de Teste sobre as suas informações contextuais personalizadas no Teams. O ficheiro tem o nome .teamsapptesttool.yml na pasta raiz do projeto. Se o Teams não conseguir localizar este ficheiro, utiliza a configuração predefinida. Para obter mais informações, veja Personalizar o contexto do Teams.

Experiência da Ferramenta de Teste no Teams Toolkit

A Ferramenta de Teste oferece uma experiência de depuração mais rápida para aplicações de bot em comparação com o cliente do Teams.

  1. Abra o Visual Studio Code.

  2. Selecione o ícone Do Teams Toolkit na Barra de Atividade do Visual Studio Code.

  3. Selecione Criar uma Nova Aplicação.

    Captura de ecrã a mostrar a localização da ligação Criar Novo Projeto na barra lateral do Teams Toolkit.

  4. Selecione Bot.

    Captura de ecrã a mostrar os modelos da aplicação Teams Toolkit.

  5. Selecione Bot de Chat de IA. Se precisar de uma funcionalidade diferente para o bot, escolha uma opção diferente.

    Captura de ecrã a mostrar a funcionalidade da aplicação a adicionar à sua nova aplicação.

  6. Selecione JavaScript.

    Captura de ecrã a mostrar a opção para selecionar a linguagem de programação.

  7. Selecione Pasta predefinida.

    Captura de ecrã a mostrar a seleção da localização predefinida.

    Para alterar a localização predefinida, siga estes passos:

    1. Selecione Procurar.

      Captura de ecrã a mostrar a seleção da opção de localização de procura.

    2. Selecione a localização da área de trabalho do projeto.

    3. Selecione Selecionar Pasta.

      Captura de ecrã a mostrar a pasta a selecionar.

  8. Introduza um nome adequado para a sua aplicação e, em seguida, selecione a tecla Enter .

    Captura de ecrã a mostrar onde introduzir o nome da aplicação.

    É apresentada uma caixa de diálogo onde tem de escolher sim ou não para confiar nos autores dos ficheiros nesta pasta.

    Captura de ecrã a mostrar a caixa de diálogo para confiar ou não nos autores dos ficheiros nesta pasta.

  9. No painel esquerdo, selecione Executar e Depurar (Ctrl+Shift+D) e selecione Depurar na Ferramenta de Teste (Pré-visualização) na lista pendente.

    Captura de ecrã a mostrar a opção para selecionar a depuração na ferramenta de teste.

  10. A Ferramenta de Teste abre o bot numa página Web.

    Captura de ecrã a mostrar o bot aberto na Ferramenta de Teste.

Acionadores de atividade

Pode simular uma atividade na Ferramenta de Teste através de acionadores de atividade. Existem dois tipos de acionadores de atividade:

  1. Acionadores de atividade predefinidos
  2. Acionadores de atividade personalizados

Acionadores de atividade predefinidos

A Ferramenta de Teste fornece acionadores de atividade predefinidos para testar as funcionalidades do bot.

Categoria Atividade Manipulador
Atividade de Atualização da Instalação do Acionador Instalar bot


Desinstalar bot		 onInstallationUpdate
onInstallationUpdateAdded

onInstallationUpdate
onInstallationUpdateRemove
Acionar Atividade de Atualização de Conversação Adicionar usuário

Adicionar bot

Adicionar canal		 onMembersAdded

onTeamsMembersAddedEvent

onTeamsChannelRenamedEvent
Remover usuário


Remover bot


Remover canal

Remover equipa		 onMembersRemoved
onTeamsMembersRemovedEvent

onMembersRemoved
onTeamsMembersRemovedEvent

onTeamsChannelDeletedEvent

onTeamsTeamDeletedEvent
Mudar o nome do canal

Mudar o nome da equipa		 onTeamsChannelRenamedEvent

onTeamsTeamRenamedEvent

Observação

Todos os tipos de atividades não estão disponíveis em todos os âmbitos. Por exemplo, não pode adicionar ou remover um canal numa conversa pessoal ou numa conversa de grupo.

Os acionadores de atividade predefinidos estão disponíveis no menu Simular uma Atividade na Ferramenta de Teste.

Para simular uma atividade Adicionar utilizador , siga estes passos:

  1. Na Ferramenta de Teste, aceda a Simular uma Atividade e selecione Adicionar utilizador.

    Captura de ecrã a mostrar a opção adicionar utilizador em simular uma atividade.

    É apresentada uma janela de pop-up para pré-visualizar o processador de atividades.

  2. Selecione Enviar atividade.

    Captura de ecrã a mostrar a opção para enviar atividade para adicionar utilizadores a atividades fictícias predefinidas.

    O bot envia uma resposta.

    Captura de ecrã a mostrar a resposta do utilizador de adição de atividade fictícia predefinida.

Acionadores de atividade personalizados

Pode utilizar a Atividade personalizada para personalizar acionadores de atividade, como, por exemplo, reactionsAdded, para se ajustar aos requisitos da sua aplicação de bot. A Ferramenta de Teste preenche automaticamente as propriedades necessárias da atividade. Também pode modificar o tipo de atividade e adicionar mais propriedades.

  1. Selecione Simular uma>Atividade Atividade Personalizada.

    Captura de ecrã a mostrar a lista de opções em simular uma atividade.

  2. Adicione messageReaction para personalizar a atividade na propriedade type e invocar a atividade personalizada.

    {
  "type": "messageReaction",
  "reactionsAdded": [
    {
      "type": "like"
    }
  ],
  "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47"
}

  3. Selecione Enviar atividade.

    Captura de ecrã a mostrar a opção para enviar atividade após a personalização na atividade fictícia.

    O bot envia um onReactionsAdded processador em resposta.

    Captura de ecrã a mostrar a resposta da atividade fictícia personalizada.

Personalizar o contexto do Teams

O ficheiro de configuração na pasta raiz do projeto permite-lhe personalizar informações de contexto do Teams, como conversas, equipas e utilizadores. O ficheiro fornece dados fictícios para testar as APIs do Bot Framework ou os métodos do SDK do Bot Builder, como TeamsInfo.getTeamMembers.

Configuração padrão

A Ferramenta de Teste contém um ficheiro de configuração incorporado na pasta raiz do projeto. 
# yaml-language-server: $schema=https://aka.ms/teams-app-test-tool-config/0.1.0/config.schema.json
# Visit https://aka.ms/teams-app-test-tool-config-guide for more details on this file.

# This configuration file customizes the Teams context information like chats, teams, and users.
# It contains mock data for testing Bot Framework APIs or Bot Builder SDK methods such as TeamsInfo.getTeamMembers().
# You can customize this file to change API response if your bot code uses these APIs.
version: "0.1.0"
tenantId: 00000000-0000-0000-0000-0000000000001
bot:
  id: 00000000-0000-0000-0000-00000000000011
  name: Test Bot
currentUser:
  id: user-id-0
  name: Alex Wilber
  userPrincipleName: alexw@example.com
  aadObjectId: 00000000-0000-0000-0000-0000000000020
  givenName: Alex
  surname: Wilber
  email: alexw@example.com
users:
  - id: user-id-1
    name: Megan Bowen
    userPrincipleName: meganb@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000021
    givenName: Megan
    surname: Bowen
    email: meganb@example.com
  - id: user-id-2
    name: Adele Vance
    userPrincipleName: adelev@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000022
    givenName: Adele
    surname: Vance
    email: adelev@example.com
  - id: user-id-3
    name: Isaiah Langer
    userPrincipleName: isaiah@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000023
    givenName: Isaiah
    surname: Langer
    email: isaiahl@example.com
  - id: user-id-4
    name: Patti Fernandez
    userPrincipleName: pattif@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000024
    givenName: Patti
    surname: Fernandez
    email: pattif@example.com
  - id: user-id-5
    name: Lynne Robbins
    userPrincipleName: lynner@example.com
    aadObjectId: 00000000-0000-0000-0000-0000000000025
    givenName: Lynne
    surname: Robbins
    email: lynner@example.com
personalChat:
  id: personal-chat-id
groupChat:
  id: group-chat-id
  name: Group Chat
team:
  id: team-id
  name: My Team
  aadGroupId: 00000000-0000-0000-0000-000000000031
  channels:
    - id: channel-announcements-id
      name: Announcements

Atualizar o ficheiro de configuração

Se o código do bot utilizar APIs do Bot Framework, pode modificar o ficheiro de configuração para alterar a resposta da API. Vamos considerar um bot de notificação do Azure DevOps instalado numa equipa que obtém erros inativos do Azure DevOps. Identifica os proprietários do erro inativo, obtém os respetivos endereços de e-mail e envia notificações para as respetivas conversas pessoais diariamente.

Para testar este bot de forma abrangente na Ferramenta de Teste, é fundamental atualizar o ficheiro de configuração para utilizar os endereços de e-mail corretos dos proprietários dos erros inativos.

  1. Aceda ao .teamsapptesttool.yml ficheiro na pasta raiz do projeto.

  2. Aceda à users secção e atualize o name, userPrincipleNamee email do utilizador necessário.

    users:
    - id: user-id-1
      name: Megan Bowen
      userPrincipleName: meganb@example.com
      aadObjectId: 00000000-0000-0000-0000-0000000000021
      givenName: Megan
      surname: Bowen
      email: some-real-user@real-domain.onmicrosoft.com

  3. Guarde o ficheiro e selecione F5 para depurar na Ferramenta de Teste.

Observação

Quando edita o ficheiro de configuração no Visual Studio Code, o Intellisense atualiza automaticamente os nomes das propriedades e avisa-o se introduzir valores inválidos.

É vital reconhecer que a atualização do ficheiro de configuração tem três impactos importantes:

  • Influencia as respostas obtidas a partir das APIs do Conector do Bot Framework, por exemplo, TeamsInfo.getPagedMembers().
  • Formatar os detalhes no payload da atividade, por exemplo, activity.recipient.
  • Afeta a interface de utilizador na Ferramenta de Teste, por exemplo, nomes de chat de grupo.

Limitações

  • As funcionalidades do bot ativadas através do manifesto da aplicação Teams não estão disponíveis, uma vez que a Ferramenta de Teste não o processa.

  • A Ferramenta de Teste não suporta todos os tipos de cartões, exceto Cartões Ajustáveis.

  • A Ferramenta de Teste não suporta as seguintes funcionalidades de Cartão Ajustável:

  • A Ferramenta de Teste não suporta as seguintes experiências:

    • Dispositivo móvel
    • Reunião

  • A Ferramenta de Teste pode emular as seguintes experiências:

    Recursos Depurar na Ferramenta de Teste Depurar seu aplicativo Teams localmente
    Envio/receção básicos de mensagens Disponível Disponível
    APIs do Bot Framework (TeamsInfo.getPagedMembers()...) Disponível (responder com dados fictícios) Disponível
    Enviar eventos do Teams Disponível (atividade fictícia) Disponível
    Indicador de escrita Não disponível Disponível
    Separador, Extensão de mensagem, Caixas de Diálogo (referidas como módulos de tarefas no TeamsJS v1.x), Início de sessão único (SSO) e Cartões Não Adaptáveis Não disponível Disponível

Depurar uma aplicação existente com a Ferramenta de Teste

Certifique-se de que tem um bot existente criado com o Teams Toolkit. Para depurar o bot com a Ferramenta de Teste, siga estes passos:

  1. Abra a pasta de projeto do bot existente no Teams Toolkit.

  2. Aceda a EXPLORER.vscode>.

  3. Selecione launch.json e adicione o seguinte código no final do ficheiro:

    // .vscode/launch.json 

{ 
    ... 
    "compounds": [ 
        ... 
        { 
            "name": "Debug in Test Tool", 
            "configurations": [ 
                "Attach to Local Service" 
            ], 
            "preLaunchTask": "Start Teams App (Test Tool)", 
            "presentation": { 
                "group": "1-local", 
                "order": 1 
            }, 
            "stopAll": true 
        }, 
    ] 
}

  4. Aceda a tasks.json e adicione o seguinte código no final do ficheiro:

        { 
      "label": "Start Test Tool", 
      "type": "shell", 
      "command": "npm run dev:teamsfx:launch-testtool", 
      "isBackground": true, 
      "options": { 
        "env": { 
          "PATH": "${workspaceFolder}/devTools/teamsapptester/node_modules/.bin:${env:PATH}" 
        } 
      }, 
      "windows": { 
        "options": { 
          "env": { 
            "PATH": "${workspaceFolder}/devTools/teamsapptester/node_modules/.bin;${env:PATH}" 
          } 
        } 
      }, 
      "problemMatcher": { 
        "pattern": [ 
          { 
            "regexp": "^.*$", 
            "file": 0, 
            "location": 1, 
            "message": 2 
          } 
        ], 
        "background": { 
          "activeOnStart": true, 
          "beginsPattern": ".*", 
          "endsPattern": "Listening on" 
        } 
      }, 
      "presentation": { 
        "panel": "dedicated", 
        "reveal": "silent" 
      } 
    }, 
  ],
}

  5. Em EXPLORADOR, crie um ficheiro .localConfigs.testtool e adicione o seguinte código:

    // .localConfigs.testTool
# A gitignored place holder file for local runtime configurations when debug in test tool
BOT_ID=
BOT_PASSWORD=
TEAMSFX_NOTIFICATION_STORE_FILENAME=.notification.testtoolstore.json

  6. Aceda a EXPLORADOR>env.

  7. Crie um ficheiro .env.testtool e adicione o seguinte código:

    // .env.testtool
# This file includes environment variables that can be committed to git. It's gitignored by default because it represents your local development environment
# Built-in environment variables
TEAMSFX_ENV=testtool
# Environment variables used by test tool
TEAMSAPPTESTER_PORT=56150

  8. Se tiver variáveis de ambiente personalizadas, defina os respetivos valores em .env.testtool ou .env.testtool.user.

  9. Adicione uma chave OpenAI ou a chave OpenAI do Azure e o ponto final em .env.testtool.user.

    # SECRET_OPENAI_API_KEY=***********
SECRET_AZURE_OPENAI_API_KEY=***********
SECRET_AZURE_OPENAI_ENDPOINT=<https://your-openai-service-name.openai.azure.com/>

  10. Aceda a package.json e adicione o seguinte código na scripts propriedade :

    "scripts": {
    ... 
    "dev:teamsfx:testtool": "env-cmd --silent -f .localConfigs.testTool npm run dev", 
    "dev:teamsfx:launch-testtool": "env-cmd --silent -f env/.env.testtool teamsapptester start", 
    ... 
},

  11. No painel esquerdo, selecione Executar e Depurar (Ctrl+Shift+D) e selecione Depurar na Ferramenta de Teste na lista pendente.

    Captura de ecrã a mostrar a opção para selecionar a depuração na ferramenta de teste.

A Ferramenta de Teste depura com êxito o bot existente.

Perguntas frequentes

Como posso testar o meu bot se a Ferramenta de Teste não suportar as respetivas funcionalidades?

Pode sempre utilizar o cliente do Teams para testar as funcionalidades que a Ferramenta de Teste não suporta. Selecione a opção Depurar no Teams (Edge) ou Depurar no Teams (Chrome) para testar a sua aplicação no cliente do Teams.
 

Como saberia se a Ferramenta de Teste não suporta funcionalidades no meu bot?

A Ferramenta de Teste mostra uma mensagem de aviso na conversação e no painel de registo quando deteta funcionalidades não suportadas.

Captura de ecrã a mostrar a mensagem de aviso de uma funcionalidade não suportada.
 

A Microsoft recomenda utilizar apenas a Ferramenta de Teste para testar aplicações de bot?

Não. Recomendamos sempre que os utilizadores testem a respetiva aplicação de bot no cliente do Teams antes de moverem a aplicação para o ambiente de produção.
 

Exemplo de código

Nome do exemplo Descrição Node.js
Aplicação de Exemplo da Ferramenta de Teste Uma aplicação de bot de exemplo para explorar a Ferramenta de Teste. View

Guias passo a passo

Siga o guia passo a passo para depurar um chatbot de IA com a Ferramenta de Teste de Aplicações do Teams.

Confira também