{"id":13706,"library":"office-addin-test-server","title":"Office Add-in Test Server","description":"The `office-addin-test-server` package provides a lightweight local web server specifically designed for testing Office Add-ins. It's a key component within the larger `OfficeDev/Office-Addin-Scripts` ecosystem, offering a framework for add-ins to send test results, which can then be consumed by test runners like Mocha to validate functionality. Currently stable at version 2.0.4, this package facilitates automated testing workflows by acting as a collection point for results from add-in runtime environments. Unlike general-purpose web servers, its differentiation lies in its tight integration with Office Add-in development, simplifying the process of capturing and processing test outcomes from within Office applications.","status":"active","version":"2.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/OfficeDev/Office-Addin-Scripts","tags":["javascript","Office","Office Add-in","typescript"],"install":[{"cmd":"npm install office-addin-test-server","lang":"bash","label":"npm"},{"cmd":"yarn add office-addin-test-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add office-addin-test-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Often used in conjunction to orchestrate add-in sideloading and debugging, which implicitly relies on a local development server.","package":"office-addin-debugging","optional":true},{"reason":"Required for generating and managing self-signed SSL certificates for local HTTPS development, crucial for Office Add-ins.","package":"office-addin-dev-certs","optional":true},{"reason":"Frequently used as the test framework to consume results collected by the test server.","package":"mocha","optional":true}],"imports":[{"note":"Primarily an ESM module. While CommonJS might technically work for some exports, ESM is the recommended and best-supported import method in modern TypeScript/Node.js projects.","wrong":"const startServer = require('office-addin-test-server').startServer;","symbol":"startServer","correct":"import { startServer } from 'office-addin-test-server';"},{"note":"Part of the core server management API. Ensure named import for clarity and compatibility.","wrong":"import stopServer from 'office-addin-test-server/lib/stopServer';","symbol":"stopServer","correct":"import { stopServer } from 'office-addin-test-server';"},{"note":"The primary class for programmatic server instantiation and control, used for advanced testing setups. Use named import.","wrong":"import TestServer from 'office-addin-test-server';","symbol":"TestServer","correct":"import { TestServer } from 'office-addin-test-server';"}],"quickstart":{"code":"import { TestServer } from 'office-addin-test-server';\nimport * as path from 'path';\n\nasync function runTestServerExample() {\n  const serverPort = 4201; // Choose an available port\n  const resultsPath = path.join(__dirname, 'test-results.json');\n\n  console.log(`Starting Office Add-in Test Server on port ${serverPort}...`);\n  const testServer = new TestServer(serverPort, resultsPath);\n\n  try {\n    await testServer.start();\n    console.log('Test server started. Waiting for results...');\n\n    // Simulate an add-in sending a test result after some time\n    setTimeout(async () => {\n      console.log('Simulating add-in sending a test result...');\n      // In a real scenario, the add-in would post to /results endpoint\n      // e.g., fetch(`https://localhost:${serverPort}/results`, { method: 'POST', body: JSON.stringify({ passed: true, message: 'Simulated test passed' }) });\n\n      const mockResult = { testName: 'MyAddinFeature', status: 'passed', details: 'Functionality check' };\n      // You would typically process results directly from the server's internal mechanisms\n      // For demonstration, we'll log what the server would process.\n      console.log('Mock result processed by server:', mockResult);\n\n      // In a real test runner, you'd retrieve results from `resultsPath` or server events\n      console.log(`Results would be collected and saved to ${resultsPath}.`);\n\n      await testServer.stop();\n      console.log('Test server stopped.');\n    }, 5000);\n\n  } catch (error) {\n    console.error('Failed to run test server example:', error);\n    await testServer.stop(); // Ensure server is stopped even on error\n  }\n}\n\nrunTestServerExample();\n","lang":"typescript","description":"This quickstart demonstrates how to programmatically start and stop the `office-addin-test-server` to receive simulated test results from an Office Add-in. It sets up a local server, waits for a mock result submission, and then gracefully shuts down the server. This pattern is foundational for automated testing of Office Add-ins."},"warnings":[{"fix":"Upgrade to a Microsoft 365 subscription and use the latest Office client applications for optimal compatibility and feature support.","message":"Older versions of Office (e.g., Office 2016 or perpetual licenses) might have compatibility issues or require specific configurations that are no longer standard for modern Microsoft 365 environments. Ensure your target Office version is supported for add-in development and testing.","severity":"breaking","affected_versions":"<=1.x"},{"fix":"Ensure `office-addin-dev-certs` is installed and run `npx office-addin-dev-certs install` to generate and trust development certificates. For Windows, enable loopbacks via PowerShell: `CheckNetIsolation LoopbackExempt -a -n='microsoft.win32webviewhost_cw5n1h2txyewy'`.","message":"When developing locally, particularly on Windows, you may encounter 'We can't open this add-in from localhost' errors due to self-signed certificate issues or loopback restrictions for WebView2. Office clients require HTTPS for add-ins.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always execute `npm run stop` (if using Yo Office templates) or `npx office-addin-debugging stop manifest.xml` after a testing session. Manually closing applications is not sufficient to clean up these registrations. Clear the Office cache if problems persist.","message":"Failing to properly stop the add-in server and remove registrations (e.g., with `npm run stop` or `npx office-addin-debugging stop`) can lead to stale add-in installations in the Windows registry or macOS special folders, causing debugging issues or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the latest Microsoft documentation for recommended debugging approaches for your specific Office host and runtime. This may involve using command-line flags or specific browser developer tools rather than integrated IDE debuggers.","message":"Debugging tools and capabilities have been systematically removed or restricted in newer Office clients (e.g., Mac App Store Office, New Outlook), making inspection and troubleshooting more challenging. Relying on older debugging patterns may lead to frustration.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Disable client-side caching in your development web server configuration. You may also need to clear your browser's cache or the Office cache directly.","message":"Client-side caching by browsers can lead to stale code being served during development. This can cause confusing behavior where code changes aren't reflected in the add-in.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.0.4':66 'act':74 'add':3,26,43,83,103,123 'add-in':2,25,42,82,102,122 'addin':10 'applic':118 'autom':70 'captur':110 'collect':77 'compon':32 'consum':53 'current':62 'design':21 'develop':105 'differenti':94 'ecosystem':37 'environ':86 'facilit':69 'framework':40 'function':61 'general':89 'general-purpos':88 'in':27,44 'integr':99 'javascript':119 'key':31 'larger':35 'lie':95 'lightweight':16 'like':57 'local':17 'mocha':58 'offer':38 'offic':1,9,24,101,117,120,121 'office-addin-test-serv':8 'officedev/office-addin-scripts':36 'outcom':114 'packag':13,68 'point':78 'process':108,112 'provid':14 'purpos':90 'result':48,80 'runner':56 'runtim':85 'send':46 'server':6,12,19,92 'simplifi':106 'specif':20 'stabl':63 'test':5,11,23,47,55,71,113 'tight':98 'typescript':125 'unlik':87 'valid':60 'version':65 'web':18,91 'within':33,116 'workflow':72","created_at":"2026-04-20T01:55:53.162120+00:00","updated_at":"2026-04-20T01:55:53.162120+00:00","problems":[{"fix":"Run `npx office-addin-dev-certs install` and ensure loopback exemption for WebView2 (`CheckNetIsolation LoopbackExempt -a -n='microsoft.win32webviewhost_cw5n1h2txyewy'` on Windows).","cause":"The Office client is unable to trust the local development server, often due to untrusted SSL certificates or Windows loopback restrictions.","error":"We can't open this add-in from localhost"},{"fix":"Verify that your add-in manifest is valid, ensure Office is up to date, and temporarily disable antivirus/firewall to rule out interference. Clear the Office cache.","cause":"General failure to load the add-in, potentially due to an invalid manifest, an issue with Office updates, or antivirus interference.","error":"App error: This app could not be started."},{"fix":"Check the manifest for errors, ensure correct time/date settings on your computer, and verify network access. Reinstall the add-in after verification.","cause":"Problem with manifest validation or network access to the add-in's files.","error":"Error loading add-ins in status bar"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/OfficeDev/Office-Addin-Scripts","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/office-addin-test-server","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}