We're thrilled to announce the launch of comprehensive testing utilities for the HubSpot UI Extensions SDK—a feature that developers have been requesting since we first launched the platform. Today, building reliable, well-tested UI extensions becomes significantly easier with our new testing framework, complete with full TypeScript type safety.
The Challenge
If you've built UI extensions before, you know they're powerful tools for customizing the HubSpot experience. But there's been one persistent challenge: testing them in an automated way has been difficult with traditional tools.
Unlike traditional React applications that render to the browser's DOM, UI extensions run in a secure, sandboxed environment that intentionally has no DOM access. This architecture provides security and performance benefits, but it also means popular testing libraries like React Testing Library won't work out of the box. These tools are designed to test applications that render to a real DOM, and without one, they have nothing to work with.
This has left developers in a difficult position: manually testing every change or building custom testing infrastructure from scratch. Neither option is ideal, especially as your extensions grow in complexity.
The Solution
Our new testing utilities solve this problem by providing a custom test renderer that produces a test-friendly tree representation of your rendered UI extension output. Instead of relying on a DOM, we create a lightweight tree structure that mirrors your rendered component hierarchy, making it easy to query, inspect, and interact with your rendered components. All functions that would typically call HubSpot services are automatically mocked for fast and reproducible tests.
The result is a testing experience that feels familiar and intuitive, with powerful querying capabilities, comprehensive mocking support, and utilities specifically designed for UI extensions. If you're using TypeScript (which we highly recommend), you'll benefit from complete type safety throughout your tests—from component props to mock configurations, the TypeScript compiler catches errors before you even run your tests, and your IDE provides intelligent autocomplete every step of the way.
Getting Started
The testing utilities are available now in the @hubspot/ui-extensions package. These utilities are compatible with any test runner—whether you prefer Jest, Mocha, or another testing framework; however, we recommend Vitest for its speed, modern features, and excellent developer experience.
Installation
First, install the UI Extensions SDK:
Then, install Vitest as a dev dependency:
Basic Example
The createRenderer() function is your entry point. It requires an extension point location (like 'crm.record.tab' or 'settings') and automatically configures appropriate mocks for that location's APIs.
Here's a simple example to get you started:
Key Features
1. Powerful Querying
Find components using flexible query methods:
2. Event Triggering
Test user interactions by triggering event handlers:
3. Async Testing Support
Wait for asynchronous updates with the built-in waitFor() utility:
4. Comprehensive Mocking
Test components that use HubSpot APIs without making actual service calls. The testing SDK automatically provides mocks for:
• React hooks (useCrmProperties(), useAssociations())
• Extension Point API (context, actions, runServerlessFunction())
Here's how easy it is to use mocks for HubSpot-provided React hooks. In your UI components, you continue to import and use the hooks as you normally would:
UserGreeting.tsx:
With the provided React hook mocks, you can now easily test your component—including all edge cases. Here's how you might test a failure scenario:
UserGreeting.test.tsx:
5. Debugging Tools
When tests don't behave as expected, use the built-in debugging utilities:
Complete Documentation
We've created comprehensive documentation to help you get the most out of the testing utilities:
- Overview Guide - Getting started and core concepts
- Mocking Guide - In-depth guide to mocking hooks and APIs
- API Reference - Detailed documentation for all methods and types
What This Means for You
With these new testing utilities, you can:
- Build with confidence - Catch bugs before they reach production
- Refactor safely - Make changes knowing your tests will catch regressions
- Document behavior - Tests serve as executable documentation for how your extensions work
- Move faster - Automated tests are faster than manual testing and run consistently every time
- Improve quality - Well-tested extensions are more reliable and maintainable
Get Started Today
The testing utilities are available now in the latest version of @hubspot/ui-extensions. Update your package and start writing tests:
We're excited to see what you build with these new testing capabilities. We welcome your feedback and suggestions—let us know what you think in the developer forums or reach out to our developer support team.
Happy testing! 🧪
