Ferramenta de Teste de Aplicações do Teams

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:

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:

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.

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.

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.

   

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

2. Selecione Enviar atividade.

   

   O bot envia uma resposta.

   

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.

   

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.

   

   O bot envia um onReactionsAdded processador em resposta.

   

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

# 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.

É 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:

  • Pesquisa typeahead
  • Menção do utilizador
  • Descrição geral
  • Largura total

• 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.

    

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

Perguntas frequentes

Exemplo de código

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

• Descrição Geral do Teams Toolkit
• Instalar o Teams Toolkit
• Criar bots para o Teams
• Cartão Adaptável
• Bot Framework SDK