{"id":13705,"library":"office-addin-test-helpers","title":"Office Add-in Test Helpers","description":"The `office-addin-test-helpers` package provides essential utilities for automating the validation and testing of Office Add-ins. Part of the broader `Office-Addin-Scripts` monorepo maintained by Microsoft OfficeDev, this library offers programmatic access to functionalities like manifest verification, add-in registration, sideloading, and communication with a test server. It is commonly used in conjunction with the `office-addin-test-server` package and popular testing frameworks such as Mocha or Jest to facilitate integration and end-to-end testing of add-ins across various Office applications (Excel, Word, Outlook, etc.). The current stable version is 2.0.4. While the monorepo has different release cadences for its constituent packages, `office-addin-test-helpers` generally follows a steady update schedule, ensuring compatibility with the evolving Office Add-ins platform.","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-helpers","lang":"bash","label":"npm"},{"cmd":"yarn add office-addin-test-helpers","lang":"bash","label":"yarn"},{"cmd":"pnpm add office-addin-test-helpers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used in conjunction for integration testing, providing a local web server for test results.","package":"office-addin-test-server","optional":true},{"reason":"Recommended for unit testing Office JavaScript APIs by mocking Office objects, as the real APIs cannot run in a Node.js environment.","package":"office-addin-mock","optional":true},{"reason":"A popular JavaScript test framework often used with these helpers for structuring tests.","package":"mocha","optional":true},{"reason":"Another popular JavaScript test framework compatible with Office Add-in testing utilities.","package":"jest","optional":true}],"imports":[{"note":"Primarily designed for ESM, though CommonJS `require` might work for some versions/configs.","wrong":"const { verifyManifestFile } = require('office-addin-test-helpers');","symbol":"verifyManifestFile","correct":"import { verifyManifestFile } from 'office-addin-test-helpers';"},{"note":"This is a named export, not a default export. Used for programmatically sideloading an add-in for testing.","wrong":"import sideloadAddin from 'office-addin-test-helpers';","symbol":"sideloadAddin","correct":"import { sideloadAddin } from 'office-addin-test-helpers';"},{"note":"Used to send test results to a connected test server, often in end-to-end scenarios.","wrong":"require('office-addin-test-helpers').sendTestResults;","symbol":"sendTestResults","correct":"import { sendTestResults } from 'office-addin-test-helpers';"}],"quickstart":{"code":"import { verifyManifestFile, sideloadAddin, AppType, sendTestResults } from 'office-addin-test-helpers';\nimport * as path from 'path';\n\n// Assuming a manifest file exists at this path\nconst manifestPath = path.resolve(__dirname, './test-manifest.xml');\n\nasync function runTestScenario() {\n  console.log('Starting Office Add-in test scenario...');\n\n  try {\n    // 1. Verify the add-in manifest file\n    console.log('Verifying manifest file...');\n    const manifestValidationResult = await verifyManifestFile(manifestPath);\n    if (!manifestValidationResult.succeeded) {\n      throw new Error(`Manifest verification failed: ${manifestValidationResult.errors.join(', ')}`);\n    }\n    console.log('Manifest file verified successfully.');\n\n    // 2. Sideload the add-in (example for Excel)\n    console.log('Sideloading add-in...');\n    // Note: In a real scenario, you would start office-addin-test-server beforehand\n    // and provide actual Office host application to interact with.\n    // The sideloadAddin function typically requires an Office instance to attach to.\n    // This example simulates the call without actual Office interaction.\n    await sideloadAddin(manifestPath, AppType.Excel);\n    console.log('Add-in sideload command initiated (requires actual Office host).');\n\n    // 3. Simulate sending test results to a test server (e.g., office-addin-test-server)\n    console.log('Simulating sending test results...');\n    const testServerPort = 4201; // Default port for office-addin-test-server\n    const results = {\n      status: 'passed',\n      testName: 'Basic Add-in Functionality',\n      message: 'Add-in loaded and performed a basic operation.'\n    };\n    await sendTestResults(testServerPort, JSON.stringify(results));\n    console.log('Test results sent to test server:', results);\n\n    console.log('Office Add-in test scenario completed successfully.');\n  } catch (error) {\n    console.error('Error during Office Add-in test scenario:', error);\n    // In a real test, you would mark the test as failed here.\n    process.exit(1);\n  }\n}\n\nrunTestScenario();","lang":"typescript","description":"This quickstart demonstrates how to use `office-addin-test-helpers` to programmatically verify an add-in manifest, initiate add-in sideloading, and send simulated test results to a test server. It highlights the typical workflow for automating Office Add-in testing."},"warnings":[{"fix":"Review the package's changelog or the `Office-Addin-Scripts` repository's documentation for specific migration instructions for your version upgrade.","message":"Breaking changes may occur between major versions of `office-addin-test-helpers`. Always consult the official release notes and migration guides when upgrading from 1.x to 2.x to understand API changes and necessary code adjustments. While no explicit 'breaking changes' documentation for this specific package from 1.x to 2.x was found, it's a general best practice for major version increments within the `Office-Addin-Scripts` monorepo.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For unit testing client-side code that interacts with Office APIs, use the `office-addin-mock` library to create mock Office objects. This allows tests to run without an active Office application.","message":"Office JavaScript APIs cannot be directly unit tested in a Node.js environment because they require a webview control within an Office application. Attempting to call `Office` or `Excel` objects outside this context will lead to runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement a `finally` block or a teardown script in your test runner to explicitly call the unregistration functions, or ensure `npm run stop` is executed after each test run.","message":"When using `office-addin-debugging` or similar tools that register an add-in (e.g., via `sideloadAddin`), it's crucial to always run the `npm run stop` command (or equivalent unregistration logic) after testing. Manually closing the Office application or terminal does not remove these registrations, which can lead to subtle bugs and unexpected behavior in subsequent testing sessions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly clear the Office cache during development. For Windows, this typically involves deleting the contents of `%LOCALAPPDATA%\\Microsoft\\Office\\16.0\\Wef\\` or using the `office-addin-dev-certs uninstall` and `install` commands. For other platforms, refer to Microsoft's official documentation on clearing the Office cache.","message":"Stale code or outdated manifest issues can frequently occur during Office Add-in development and testing. This is often due to caching by Office applications or webview controls.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.0.4':111 'access':45 'across':98 'add':3,26,52,96,141,148 'add-in':2,25,51,95,140,147 'addin':10,34,72,125 'applic':101 'autom':18 'broader':31 'cadenc':118 'common':64 'communic':57 'compat':135 'conjunct':67 'constitu':121 'current':107 'differ':116 'end':90,92 'end-to-end':89 'ensur':134 'essenti':15 'etc':105 'evolv':138 'excel':102 'facilit':86 'follow':129 'framework':79 'function':47 'general':128 'helper':6,12,127 'in':27,97,142 'integr':87 'javascript':144 'jest':84 'librari':42 'like':48 'maintain':37 'manifest':49 'microsoft':39 'mocha':82 'monorepo':36,114 'offer':43 'offic':1,9,24,33,71,100,124,139,145,146 'office-addin-script':32 'office-addin-test-help':8,123 'office-addin-test-serv':70 'officedev':40 'outlook':104 'packag':13,75,122 'part':28 'platform':143 'popular':77 'programmat':44 'provid':14 'registr':54 'releas':117 'schedul':133 'script':35 'server':61,74 'sideload':55 'stabl':108 'steadi':131 'test':5,11,22,60,73,78,93,126 'typescript':150 'updat':132 'use':65 'util':16 'valid':20 'various':99 'verif':50 'version':109 'word':103","created_at":"2026-04-20T01:55:52.770839+00:00","updated_at":"2026-04-20T01:55:52.770839+00:00","problems":[{"fix":"Unit test Office API interactions using `office-addin-mock`. For integration/end-to-end tests, ensure the code runs within an actual Office Add-in task pane or content pane loaded by an Office application.","cause":"Attempting to run Office JavaScript API code in a Node.js environment or a browser context without the Office application's embedded webview.","error":"ReferenceError: Office is not defined"},{"fix":"Examine the error messages returned by `verifyManifestFile` carefully. Use a manifest validator or schema definitions (like the Office Add-in XML Schema) to correct errors in the manifest file.","cause":"The Office Add-in manifest XML file contains syntax errors, invalid schema, or incorrect values (e.g., missing IDs, invalid URLs).","error":"Manifest verification failed: [Error messages...]"},{"fix":"Ensure `office-addin-test-server` is started and running on the correct port before executing tests that require server communication. Verify firewall rules are not blocking the connection.","cause":"The `office-addin-test-server` is not running or is inaccessible on the expected port when `sendTestResults` or other server communication functions are called.","error":"Error: unable to connect to test server: [reason]"}],"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":"https://learn.microsoft.com/en-us/office/dev/add-ins/overview/testing-your-add-in","github":"https://github.com/OfficeDev/Office-Addin-Scripts","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/office-addin-test-helpers","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}}