Local Development and Debugging Setup
Teams Toolkit's F5 debug experience spins up your tab and bot locally, tunnels the bot endpoint publicly through dev tunnels (or ngrok in older setups) so Teams' cloud services can reach your machine, sideloads the app package into a test tenant automatically, and launches the Teams client or web app pointed at your local code with breakpoints attached in VS Code. Multi-target debugging lets you launch the same session against Teams desktop, Teams web, and Outlook simultaneously when your app also targets Outlook add-in surfaces, catching host-specific rendering differences early instead of after a store submission.
Cricket analogy: It's like a net session where the bowling machine (dev tunnel) simulates live match pace so a batter can practice against realistic conditions before facing an actual bowler in a real match — the tunnel simulates production networking before you go live.
Testing Tabs and SSO Flows
SSO must be tested inside an actual sideloaded Teams client, not a standalone browser tab, because authentication.getAuthToken() relies on the Teams client injecting context that a plain browser session doesn't have — testing only in a browser gives false confidence that SSO works. The Teams DevTools browser extension (accessible via Teams' developer preview settings) lets you inspect the live TeamsJS context object, app theme, and manifest values the running app actually received, which is invaluable when a tab behaves differently than expected and you need to confirm what context it's actually working with.
Cricket analogy: It's like practicing your technique against a bowling machine and assuming you're match-ready — you only really know if it works when you face a real bowler under match pressure, the way SSO only truly works when tested inside a real sideloaded Teams client.
Testing Bots and Message Extensions
Bot Framework Emulator lets you test a bot's conversational logic locally — including adaptive card rendering, action.submit payloads, and turn handling — against your bot's messaging endpoint before ever sideloading into Teams, catching logic errors faster than a full Teams round-trip would. For message extensions, test both the search command path (query typed into the compose box search box) and the action command path (invoked via the compose box's ... menu or message context menu) separately, since each triggers a different activity handler and a bug in one won't surface while testing the other.
Cricket analogy: It's like a bowler working on their action in the nets against a stationary batter before bowling live in a match — Bot Framework Emulator tests the bot's logic in a controlled setting before the higher-stakes environment of a real Teams conversation.
Debugging Issues in Production
Wire up Application Insights in both the bot and tab backend so you can trace a specific user's failed request by correlation ID across the Bot Framework Connector, your API, and downstream Graph calls, rather than guessing from user-reported symptoms alone. When a bug only reproduces in a specific customer's tenant, use a Microsoft 365 Developer Program test tenant (free, renewable, comes with sample data) to replicate tenant-specific configuration — conditional access policies, custom Graph permission grants, or multi-geo data residency — that your own dev tenant doesn't have.
Cricket analogy: It's like using ball-tracking technology (Hawk-Eye) to trace exactly where a delivery went wrong instead of relying on the umpire's memory — Application Insights traces a failed request by correlation ID instead of relying on a user's vague description.
import { TeamsActivityHandler, TurnContext } from 'botbuilder';
import { TelemetryClient } from 'applicationinsights';
const telemetry = new TelemetryClient(process.env.APPINSIGHTS_CONNECTION_STRING!);
export class TaskBot extends TeamsActivityHandler {
constructor() {
super();
this.onMessage(async (context: TurnContext, next) => {
const correlationId = context.activity.id;
try {
await this.handleTaskCommand(context);
} catch (err) {
telemetry.trackException({
exception: err as Error,
properties: { correlationId, conversationId: context.activity.conversation.id },
});
await context.sendActivity('Something went wrong handling that request.');
}
await next();
});
}
private async handleTaskCommand(context: TurnContext) {
// task creation logic
}
}The Microsoft 365 Developer Program gives you a free, renewable test tenant preloaded with sample users and data — use it to reproduce tenant-specific bugs (conditional access, custom permission grants) that your personal dev tenant won't have configured.
A tab that renders fine in a standalone browser tab can fail inside the real Teams client due to iframe sandboxing and Content-Security-Policy frame-ancestors restrictions — always do final verification by sideloading into an actual Teams client, not just localhost in a browser.
- Teams Toolkit's F5 debug experience tunnels your local bot endpoint and sideloads the app into a test tenant automatically.
- Test SSO inside a real sideloaded Teams client, not a standalone browser, since getAuthToken() relies on injected Teams context.
- Use the Teams DevTools browser extension to inspect the live TeamsJS context object during debugging.
- Bot Framework Emulator tests conversational logic and adaptive card rendering before a full Teams round-trip.
- Test message extension search and action commands separately — they trigger different activity handlers.
- Wire up Application Insights with correlation IDs to trace failed requests across the bot, API, and Graph calls.
- Use a Microsoft 365 Developer Program test tenant to reproduce tenant-specific configuration issues.
Practice what you learned
1. Why can't SSO be fully validated by testing a tab in a standalone browser tab alone?
2. What tool lets you test a bot's conversational logic and Adaptive Card rendering locally before sideloading into Teams?
3. Why should search commands and action commands in a message extension be tested separately?
4. What is the primary purpose of using correlation IDs with Application Insights telemetry in a Teams app?
5. Why might a tab render correctly in a standalone browser but fail inside the actual Teams client?
Was this page helpful?
You May Also Like
Teams App Best Practices
Practical guidelines for building performant, secure, and visually consistent Microsoft Teams applications that hold up in production.
Publishing to the Teams Store
How to prepare, validate, and submit a Microsoft Teams app for Teams Store publication through Partner Center.
Microsoft Teams Quick Reference
A condensed cheat sheet of core manifest fields, TeamsJS APIs, bot patterns, and Graph endpoints for Teams app development.
Related Reading
Related Study Notes in Microsoft Technologies
Browse all study notesWindows 10 / UWP Development Study Notes
.NET · 30 topics
Microsoft TechnologiesWindows Batch Scripting Study Notes
Batch · 30 topics
Microsoft TechnologiesMFC (Microsoft Foundation Classes) Study Notes
C++ · 30 topics
Microsoft TechnologiesSilverlight Study Notes
.NET · 30 topics
Microsoft TechnologiesXAML Study Notes
.NET · 30 topics
Microsoft TechnologiesWPF (Windows Presentation Foundation) Study Notes
.NET · 30 topics