Ferramenta de Teste de Aplicativo do Teams
Observação
A Ferramenta de Teste de Aplicativo do Teams está disponível na versão de pré-lançamento mais recente do Kit de Ferramentas do Microsoft Teams. Verifique se você instala a versão de pré-lançamento mais recente do Kit de Ferramentas do Teams.
A Ferramenta de Teste de Aplicativo do Teams (Ferramenta de Teste) torna a depuração de aplicativos baseados em bots sem esforço. Você pode conversar com seu bot e ver suas mensagens e Cartões Adaptáveis conforme elas aparecem no Microsoft Teams. Você não precisa de uma conta de desenvolvedor do Microsoft 365, túnel ou aplicativo do Teams e registro de bot para usar a Ferramenta de Teste.
A imagem a seguir mostra um aplicativo de exemplo exibindo um Cartão Adaptável com uma lista de comandos na Ferramenta de Teste. Ele também fornece uma descrição dos comandos para que você possa testar seu aplicativo sem pesquisar manualmente seu código:
Veja a seguir as vantagens da Ferramenta de Teste:
Ambiente de área restrita: o ambiente de área restrita da Ferramenta de Teste emula o comportamento, a aparência e a experiência do usuário do Teams.
Túnel: um serviço de túnel externo não é necessário, pois a Ferramenta de Teste é executada em um servidor local com o qual o bot pode se comunicar.
Reduzir as dependências da conta: o locatário do Desenvolvedor do Microsoft 365 e as permissões de carregamento do aplicativo não são necessários para depurar o bot.
Iterações rápidas de loop interno: otimiza o processo de fazer alterações no design do aplicativo e na lógica do bot sem precisar reimplantar o bot na nuvem.
Simular dados e atividades: a Ferramenta de Teste facilita o teste de cenários complexos, como enviar uma mensagem de boas-vindas quando um novo membro ingressar no canal, usando dados simulados e gatilhos de atividade.
Confiável: a Ferramenta de Teste é confiável, pois o Cartão Adaptável do bot utiliza a mesma tecnologia de renderização que no Teams.
Integração com aplicativos de bot do Teams existentes: a Ferramenta de Teste se integra sem esforço aos aplicativos de bot do Teams existentes criados com o SDK do Bot Framework.
Suporte para diferentes escopos: a Ferramenta de Teste dá suporte a testes em escopos de chat pessoal, de equipe e de grupo.
Pré-requisitos
Verifique se você instala as seguintes ferramentas para criar e implantar seus bots na Ferramenta de Teste:
| Instalar | Para usar... | |
|---|---|---|
| Kit de ferramentas do Teams | Uma extensão do Microsoft Visual Studio Code que cria um scaffolding de projeto para seu aplicativo. Use a versão de pré-lançamento mais recente. | |
| Node.js | Ambiente de runtime do JavaScript de back-end. Para obter mais informações, consulte Node.js tabela de compatibilidade de versão para o tipo de projeto. | |
| Visual Studio Code | Ambientes de compilação JavaScript, TypeScript ou Estrutura do SharePoint (SPFx). Use a versão mais recente. |
Entender ferramenta de teste
A Ferramenta de Teste é um pacote npm que tem um comando da CLI chamado teamsapptester. Quando você executa teamsapptester start, ele abre um aplicativo Web em seu computador local que emula o cliente Web do Teams e o serviço Bot Framework. Este aplicativo Web não precisa de recursos de nuvem, pois usa dados simulados para simular as informações contextuais do Teams.
Para usar um bot do Teams na Ferramenta de Teste, você precisa fornecer:
- Ponto de extremidade da mensagem: um ponto de extremidade de mensagem de bot é a URL que vincula a Ferramenta de Teste e seu bot. Você pode atualizar o ponto de extremidade com a
BOT_ENDPOINTvariável de ambiente ou usar o valor padrão dehttp://localhost:3978/api/messages. - Arquivo de configuração (opcional): um arquivo de configuração informa a Ferramenta de Teste sobre suas informações contextuais personalizadas no Teams. O arquivo é nomeado .teamsapptesttool.yml na pasta raiz do projeto. Se o Teams não conseguir localizar esse arquivo, ele usará a configuração padrão. Para obter mais informações, consulte personalizar o contexto do Teams.
Experiência de ferramenta de teste no Kit de Ferramentas do Teams
A Ferramenta de Teste oferece uma experiência de depuração mais rápida para aplicativos bot quando comparada com o cliente do Teams.
Abra o Visual Studio Code.
Selecione o ícone Kit de
Ferramentas do Teams na Barra de Atividades Visual Studio Code.Selecione Criar um Novo Aplicativo.
Selecione Bot.
Selecione Bot de Chat de IA. Se você precisar de uma funcionalidade diferente para o bot, escolha uma opção diferente.
Selecione JavaScript.
Selecione Pasta Padrão.
Para alterar o local padrão, siga estas etapas:
Selecione Procurar.
Selecione o local para o workspace do projeto.
Selecione Selecionar Pasta.
Insira um nome adequado para seu aplicativo e selecione a chave Enter .
Uma caixa de diálogo é exibida, em que você precisa escolher sim ou não para confiar nos autores dos arquivos nesta pasta.
No painel esquerdo, selecione Executar e Depurar (
Ctrl+Shift+D) e selecione Depurar em Ferramenta de Teste (Versão Prévia) na lista suspensa.
A Ferramenta de Teste abre o bot em uma página da Web.
Gatilhos de atividade
Você pode simular uma atividade na Ferramenta de Teste usando gatilhos de atividade. Há dois tipos de gatilhos de atividade:
Gatilhos de atividade predefinidos
A Ferramenta de Teste fornece gatilhos de atividade predefinidos para testar as funcionalidades do bot.
| Categoria | Atividade | Manipulador |
|---|---|---|
| Atividade de atualização de instalação do gatilho | Instalar bot Desinstalar bot |
onInstallationUpdate onInstallationUpdateAdded onInstallationUpdate onInstallationUpdateRemove |
| Atividade de atualização de conversa de gatilho | Adicionar usuário Adicionar bot Adicionar canal |
onMembersAddedonTeamsMembersAddedEvent onTeamsChannelRenamedEvent |
| Remover usuário Remover bot Remover canal Remover equipe |
onMembersRemoved onTeamsMembersRemovedEvent onMembersRemoved onTeamsMembersRemovedEvent onTeamsChannelDeletedEvent onTeamsTeamDeletedEvent |
|
| Renomear canal Renomear equipe |
onTeamsChannelRenamedEvent onTeamsTeamRenamedEvent |
Observação
Todos os tipos de atividades não estão disponíveis em todos os escopos. Por exemplo, você não pode adicionar ou remover um canal em um chat pessoal ou um chat em grupo.
Os gatilhos de atividade predefinidos estão disponíveis no menu Simular uma Atividade na Ferramenta de Teste.
Para simular uma atividade Adicionar usuário , siga estas etapas:
Em Ferramenta de Teste, vá para Simular uma Atividade e selecione Adicionar usuário.
Uma janela pop-up aparece para visualizar o manipulador de atividades.
Selecione Enviar atividade.
O bot envia uma resposta.
Gatilhos de atividade personalizados
Você pode usar a atividade personalizada para personalizar gatilhos de atividade, como, reactionsAdded, para atender aos requisitos do seu aplicativo bot. A Ferramenta de Teste preenche automaticamente as propriedades necessárias da atividade. Você também pode modificar o tipo de atividade e adicionar mais propriedades.
Selecione Simular uma atividadepersonalizada de atividade.>
Adicione
messageReactionpara personalizar a atividade na propriedadetypee invocar a atividade personalizada.{ "type": "messageReaction", "reactionsAdded": [ { "type": "like" } ], "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47" }Selecione Enviar atividade.
O bot envia um
onReactionsAddedmanipulador em resposta.
Personalizar o contexto do Teams
O arquivo de configuração na pasta raiz do projeto permite personalizar informações de contexto do Teams, como chats, equipes e usuários. O arquivo fornece dados simulados para testar APIs do Bot Framework ou métodos do SDK do Construtor de Bots, como TeamsInfo.getTeamMembers.
Configuração padrão
A Ferramenta de Teste contém um arquivo de configuração interno 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 arquivo de configuração
Se o código do bot usar APIs do Bot Framework, você poderá modificar o arquivo de configuração para alterar a resposta à API. Consideremos um bot de notificação do Azure DevOps instalado em uma equipe que busca bugs inativos do Azure DevOps. Ele identifica os proprietários do bug inativo, busca seus endereços de email e envia notificações para seus chats pessoais diariamente.
Para testar esse bot de forma abrangente na Ferramenta de Teste, é crucial atualizar o arquivo de configuração para usar os endereços de email corretos dos proprietários dos bugs inativos.
Vá para o
.teamsapptesttool.ymlarquivo na pasta raiz do projeto.Vá para a
usersseção e atualize oname,userPrincipleNameeemaildo usuário 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.comSalve o arquivo e selecione F5 para depurar na Ferramenta de Teste.
Observação
Quando você edita o arquivo de configuração no Visual Studio Code, o Intellisense atualiza automaticamente os nomes da propriedade e avisa se você inserir valores inválidos.
É vital reconhecer que a atualização do arquivo de configuração tem três grandes impactos:
- Ele influencia as respostas obtidas das APIs do Conector do Bot Framework, por exemplo,
TeamsInfo.getPagedMembers(). - Ele forma os detalhes no conteúdo da atividade, por exemplo,
activity.recipient. - Isso afeta a interface do usuário na Ferramenta de Teste, por exemplo, nomes de chat em grupo.
Limitações
Os recursos de bot habilitados por meio do manifesto do aplicativo teams não estão disponíveis, pois a Ferramenta de Teste não o processa.
A Ferramenta de Teste não dá suporte a todos os tipos de cartões, exceto cartões adaptáveis.
A Ferramenta de Teste não dá suporte aos seguintes recursos do Cartão Adaptável:
A Ferramenta de Teste não dá suporte às seguintes experiências:
- Dispositivo móvel
- Reunião
A Ferramenta de Teste pode emular as seguintes experiências:
Recursos Depuração na Ferramenta de Teste Depurar seu aplicativo Teams localmente Mensagens básicas de envio/recebimento Disponível Disponível APIs do Bot Framework (TeamsInfo.getPagedMembers()...) Disponível (responda com dados simulados) Disponível Enviar eventos do Teams Disponível (atividade simulada) Disponível Indicador de digitação Não disponível Disponível Tab, Extensão de mensagem, Diálogos (conhecidos como módulos de tarefa no TeamsJS v1.x), SSO (logon único) e cartões não adaptáveis Não disponível Disponível
Depurar um aplicativo existente com a Ferramenta de Teste
Verifique se você tem um bot existente criado usando o Teams Toolkit. Para depurar seu bot com a Ferramenta de Teste, siga estas etapas:
Abra a pasta de projeto do bot existente no Teams Toolkit.
Vá para EXPLORER.vscode>.
Selecione launch.json e adicione o seguinte código no final do arquivo:
// .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 }, ] }Vá para tasks.json e adicione o seguinte código no final do arquivo:
{ "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" } }, ], }Em EXPLORER, crie um arquivo .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.jsonAcesse explorer>env.
Crie um arquivo .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=56150Se você tiver variáveis de ambiente personalizadas, defina seus valores em .env.testtool ou .env.testtool.user.
Adicione uma chave OpenAI ou uma chave e ponto de extremidade do Azure OpenAI 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/>Vá para package.json e adicione o seguinte código na
scriptspropriedade:"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", ... },No painel esquerdo, selecione Executar e Depurar (
Ctrl+Shift+D) e selecione Depurar na Ferramenta de Teste na lista suspensa.
A Ferramenta de Teste depura com êxito seu bot existente.
Perguntas frequentes
Como posso testar meu bot se a Ferramenta de Teste não dá suporte aos seus recursos?
Você sempre pode usar o cliente do Teams para testar os recursos que a Ferramenta de Teste não dá suporte. Selecione a opção Depuração no Teams (Edge) ou Depuração no Teams (Chrome) para testar seu aplicativo no cliente do Teams.
Como eu saberia se a Ferramenta de Teste não dá suporte a recursos no meu bot?
A Ferramenta de Teste mostra uma mensagem de aviso no painel de conversa e log quando detecta recursos sem suporte.
A Microsoft recomenda usar apenas a Ferramenta de Teste para testar aplicativos bot?
Não. Sempre recomendamos que os usuários testem seu aplicativo bot no cliente do Teams antes de mover o aplicativo para o ambiente de produção.
Exemplo de código
| Nome do exemplo | Descrição | Node.js |
|---|---|---|
| Aplicativo de exemplo de ferramenta de teste | Um aplicativo de bot de exemplo para explorar a Ferramenta de Teste. | View |
Guias passo a passo
Siga o guia passo a passo para depurar um bot de chat de IA usando a Ferramenta de Teste de Aplicativo do Teams.
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de