Registry / testing / office-addin-test-helpers

office-addin-test-helpers

JSON →
library2.0.4jsnpmunverified

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.

npm install office-addin-test-helpers
INSTALL
IMPORT
SIG · OFFICE-ADDIN-TEST-
O
office-addin-test-helpers
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.

verifyManifestFile
import { verifyManifestFile } from 'office-addin-test-helpers';
const { verifyManifestFile } = require('office-addin-test-helpers');
Primarily designed for ESM, though CommonJS `require` might work for some versions/configs.
sideloadAddin
import { sideloadAddin } from 'office-addin-test-helpers';
import sideloadAddin from 'office-addin-test-helpers';
This is a named export, not a default export. Used for programmatically sideloading an add-in for testing.
sendTestResults
import { sendTestResults } from 'office-addin-test-helpers';
require('office-addin-test-helpers').sendTestResults;
Used to send test results to a connected test server, often in end-to-end scenarios.

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.

import { verifyManifestFile, sideloadAddin, AppType, sendTestResults } from 'office-addin-test-helpers'; import * as path from 'path'; // Assuming a manifest file exists at this path const manifestPath = path.resolve(__dirname, './test-manifest.xml'); async function runTestScenario() { console.log('Starting Office Add-in test scenario...'); try { // 1. Verify the add-in manifest file console.log('Verifying manifest file...'); const manifestValidationResult = await verifyManifestFile(manifestPath); if (!manifestValidationResult.succeeded) { throw new Error(`Manifest verification failed: ${manifestValidationResult.errors.join(', ')}`); } console.log('Manifest file verified successfully.'); // 2. Sideload the add-in (example for Excel) console.log('Sideloading add-in...'); // Note: In a real scenario, you would start office-addin-test-server beforehand // and provide actual Office host application to interact with. // The sideloadAddin function typically requires an Office instance to attach to. // This example simulates the call without actual Office interaction. await sideloadAddin(manifestPath, AppType.Excel); console.log('Add-in sideload command initiated (requires actual Office host).'); // 3. Simulate sending test results to a test server (e.g., office-addin-test-server) console.log('Simulating sending test results...'); const testServerPort = 4201; // Default port for office-addin-test-server const results = { status: 'passed', testName: 'Basic Add-in Functionality', message: 'Add-in loaded and performed a basic operation.' }; await sendTestResults(testServerPort, JSON.stringify(results)); console.log('Test results sent to test server:', results); console.log('Office Add-in test scenario completed successfully.'); } catch (error) { console.error('Error during Office Add-in test scenario:', error); // In a real test, you would mark the test as failed here. process.exit(1); } } runTestScenario();
Debug
Known issues
breakingBreaking 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.
fix
Review the package's changelog or the `Office-Addin-Scripts` repository's documentation for specific migration instructions for your version upgrade.
affects: >=2.0.0
gotchaOffice 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.
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.
affects: >=1.0.0
gotchaWhen 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.
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.
affects: >=1.0.0
gotchaStale 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.
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.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: Office is not defined
Attempting to run Office JavaScript API code in a Node.js environment or a browser context without the Office application's embedded webview.
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.
Manifest verification failed: [Error messages...]
The Office Add-in manifest XML file contains syntax errors, invalid schema, or incorrect values (e.g., missing IDs, invalid URLs).
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.
Error: unable to connect to test server: [reason]
The `office-addin-test-server` is not running or is inaccessible on the expected port when `sendTestResults` or other server communication functions are called.
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.
Upgrade
Version history
2.0.4latest on npm
Audit
Dependencies
office-addin-test-serveroptionalCommonly used in conjunction for integration testing, providing a local web server for test results.
office-addin-mockoptionalRecommended for unit testing Office JavaScript APIs by mocking Office objects, as the real APIs cannot run in a Node.js environment.
mochaoptionalA popular JavaScript test framework often used with these helpers for structuring tests.
jestoptionalAnother popular JavaScript test framework compatible with Office Add-in testing utilities.
Agent activity
2 hits · last 30 days
node
2
Resources