Registry / testing / office-addin-test-server

office-addin-test-server

JSON →
library2.0.4jsnpmunverified

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.

npm install office-addin-test-server
INSTALL
IMPORT
SIG · OFFICE-ADDIN-TEST-
O
office-addin-test-server
testingjavascriptv2.0.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer
import { startServer } from 'office-addin-test-server';
const startServer = require('office-addin-test-server').startServer;
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.
stopServer
import { stopServer } from 'office-addin-test-server';
import stopServer from 'office-addin-test-server/lib/stopServer';
Part of the core server management API. Ensure named import for clarity and compatibility.
TestServer
import { TestServer } from 'office-addin-test-server';
import TestServer from 'office-addin-test-server';
The primary class for programmatic server instantiation and control, used for advanced testing setups. Use named import.

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.

import { TestServer } from 'office-addin-test-server'; import * as path from 'path'; async function runTestServerExample() { const serverPort = 4201; // Choose an available port const resultsPath = path.join(__dirname, 'test-results.json'); console.log(`Starting Office Add-in Test Server on port ${serverPort}...`); const testServer = new TestServer(serverPort, resultsPath); try { await testServer.start(); console.log('Test server started. Waiting for results...'); // Simulate an add-in sending a test result after some time setTimeout(async () => { console.log('Simulating add-in sending a test result...'); // In a real scenario, the add-in would post to /results endpoint // e.g., fetch(`https://localhost:${serverPort}/results`, { method: 'POST', body: JSON.stringify({ passed: true, message: 'Simulated test passed' }) }); const mockResult = { testName: 'MyAddinFeature', status: 'passed', details: 'Functionality check' }; // You would typically process results directly from the server's internal mechanisms // For demonstration, we'll log what the server would process. console.log('Mock result processed by server:', mockResult); // In a real test runner, you'd retrieve results from `resultsPath` or server events console.log(`Results would be collected and saved to ${resultsPath}.`); await testServer.stop(); console.log('Test server stopped.'); }, 5000); } catch (error) { console.error('Failed to run test server example:', error); await testServer.stop(); // Ensure server is stopped even on error } } runTestServerExample();
Debug
Known issues
breakingOlder 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.
fix
Upgrade to a Microsoft 365 subscription and use the latest Office client applications for optimal compatibility and feature support.
affects: <=1.x
gotchaWhen 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.
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'`.
affects: >=1.0.0
gotchaFailing 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.
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.
affects: >=1.0.0
deprecatedDebugging 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.
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.
affects: >=2.0.0
gotchaClient-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.
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.
affects: >=1.0.0
Errors
Common errors & fixes
We can't open this add-in from localhost
The Office client is unable to trust the local development server, often due to untrusted SSL certificates or Windows loopback restrictions.
fix
Run `npx office-addin-dev-certs install` and ensure loopback exemption for WebView2 (`CheckNetIsolation LoopbackExempt -a -n='microsoft.win32webviewhost_cw5n1h2txyewy'` on Windows).
App error: This app could not be started.
General failure to load the add-in, potentially due to an invalid manifest, an issue with Office updates, or antivirus interference.
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.
Error loading add-ins in status bar
Problem with manifest validation or network access to the add-in's files.
fix
Check the manifest for errors, ensure correct time/date settings on your computer, and verify network access. Reinstall the add-in after verification.
Upgrade
Version history
2.0.4latest on npm
Audit
Dependencies
office-addin-debuggingoptionalOften used in conjunction to orchestrate add-in sideloading and debugging, which implicitly relies on a local development server.
office-addin-dev-certsoptionalRequired for generating and managing self-signed SSL certificates for local HTTPS development, crucial for Office Add-ins.
mochaoptionalFrequently used as the test framework to consume results collected by the test server.
Agent activity
2 hits · last 30 days
node
2
Resources
office-addin-test-server — npm install office-addin-test-server · libregistry