0
# inferno-test-utils
1

2
A comprehensive suite of testing utilities specifically designed for Inferno applications, providing functions for traversing, searching, and validating rendered component trees with support for finding DOM elements and VNodes by various criteria.
3

4
## Package Information
5

6
- **Package Name**: inferno-test-utils
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Version**: 9.0.3
10

11
### Installation
12

13
```bash
14
npm install inferno --save
15
npm install inferno-test-utils --save-dev
16
```
17

18
## Core Imports
19

20
### ESM (ES Modules)
21
```javascript
22
import {
23
  // Type checkers
24
  isVNode,
25
  isVNodeOfType,
26
  isDOMVNode,
27
  isDOMVNodeOfType,
28
  isClassVNode,
29
  isClassVNodeOfType,
30
  isFunctionalVNode,
31
  isFunctionalVNodeOfType,
32
  isComponentVNode,
33
  isComponentVNodeOfType,
34
  isTextVNode,
35
  isDOMElement,
36
  isDOMElementOfType,
37
  isRenderedClassComponent,
38
  isRenderedClassComponentOfType,
39
  
40
  // Tree traversal
41
  findAllInRenderedTree,
42
  findAllInVNodeTree,
43
  
44
  // Search functions (multiple results)
45
  scryRenderedDOMElementsWithClass,
46
  scryRenderedDOMElementsWithTag,
47
  scryRenderedVNodesWithType,
48
  scryVNodesWithType,
49
  
50
  // Find functions (single result)
51
  findRenderedDOMElementWithClass,
52
  findRenderedDOMElementWithTag,
53
  findRenderedVNodeWithType,
54
  findVNodeWithType,
55
  
56
  // Rendering utilities
57
  renderIntoContainer,
58
  getTagNameOfVNode,
59
  Wrapper,
60
  
61
  // Jest integration
62
  vNodeToSnapshot,
63
  renderToSnapshot
64
} from 'inferno-test-utils';
65
```
66

67
### CommonJS
68
```javascript
69
const {
70
  // Type checkers
71
  isVNode,
72
  isVNodeOfType,
73
  isDOMVNode,
74
  isDOMVNodeOfType,
75
  isClassVNode,
76
  isClassVNodeOfType,
77
  isFunctionalVNode,
78
  isFunctionalVNodeOfType,
79
  isComponentVNode,
80
  isComponentVNodeOfType,
81
  isTextVNode,
82
  isDOMElement,
83
  isDOMElementOfType,
84
  isRenderedClassComponent,
85
  isRenderedClassComponentOfType,
86
  
87
  // Tree traversal
88
  findAllInRenderedTree,
89
  findAllInVNodeTree,
90
  
91
  // Search functions (multiple results)
92
  scryRenderedDOMElementsWithClass,
93
  scryRenderedDOMElementsWithTag,
94
  scryRenderedVNodesWithType,
95
  scryVNodesWithType,
96
  
97
  // Find functions (single result)
98
  findRenderedDOMElementWithClass,
99
  findRenderedDOMElementWithTag,
100
  findRenderedVNodeWithType,
101
  findVNodeWithType,
102
  
103
  // Rendering utilities
104
  renderIntoContainer,
105
  getTagNameOfVNode,
106
  Wrapper,
107
  
108
  // Jest integration
109
  vNodeToSnapshot,
110
  renderToSnapshot
111
} = require('inferno-test-utils');
112
```
113

114
## Basic Usage
115

116
### Setting up a test environment
117
```javascript
118
import { render } from 'inferno';
119
import { renderIntoContainer, findRenderedDOMElementWithClass } from 'inferno-test-utils';
120

121
// Create a test component
122
function TestComponent() {
123
  return <div className="test-component">Hello World</div>;
124
}
125

126
// Render into container for testing
127
const renderedTree = renderIntoContainer(<TestComponent />);
128

129
// Find elements in the rendered tree
130
const element = findRenderedDOMElementWithClass(renderedTree, 'test-component');
131
console.log(element.textContent); // "Hello World"
132
```
133

134
### Type checking VNodes
135
```javascript
136
import { createElement } from 'inferno-create-element';
137
import { isVNode, isDOMVNode, isClassVNode } from 'inferno-test-utils';
138

139
const domVNode = createElement('div');
140
const classVNode = createElement(MyComponent);
141

142
console.log(isVNode(domVNode)); // true
143
console.log(isDOMVNode(domVNode)); // true
144
console.log(isClassVNode(classVNode)); // true
145
```
146

147
## Architecture
148

149
The inferno-test-utils package is organized into several functional areas that work together to provide comprehensive testing capabilities:
150

151
### Core Dependencies
152

153
The package relies on several key Inferno ecosystem packages:
154

155
- **inferno**: Core rendering and VNode types
156
- **inferno-shared**: Shared utility functions (type checking, error handling)
157
- **inferno-vnode-flags**: VNode flag constants that identify component types and states
158

159
### VNode Flag System
160

161
The package uses Inferno's VNode flag system to efficiently identify component types:
162

163
- `VNodeFlags.Element` - DOM elements (div, span, etc.)
164
- `VNodeFlags.ComponentClass` - Class-based components  
165
- `VNodeFlags.ComponentFunction` - Functional components
166
- `VNodeFlags.Text` - Text nodes
167
- `VNodeFlags.Component` - Generic component flag
168

169
These flags enable fast type checking without expensive instanceof operations.
170

171
### Functional Areas
172

173
1. **Type Checkers** - Functions to identify VNode and DOM element types using VNode flags
174
2. **Tree Traversal** - Recursive functions to traverse component trees using predicate-based filtering
175
3. **Element Finders** - Higher-level search functions that combine traversal with specific criteria
176
4. **Rendering Utilities** - Functions to render components into test containers and extract metadata
177
5. **Jest Integration** - Snapshot generation that converts VNode trees to Jest-compatible format
178

179
## Capabilities
180

181
### Type Checking
182

183
Comprehensive type checking utilities for identifying VNodes, DOM elements, and component types with both generic and type-specific checkers.
184

185
```javascript { .api }
186
// VNode type checking
187
function isVNode(obj: any): obj is VNode
188
function isVNodeOfType(obj: VNode, type: unknown): boolean
189
function isDOMVNode(vNode: any): vNode is VNode
190
function isDOMVNodeOfType(obj: VNode, type: string): boolean
191
function isFunctionalVNode(obj: VNode): obj is VNode
192
function isFunctionalVNodeOfType(obj: VNode, type: Function): boolean
193
function isClassVNode(obj: VNode): obj is VNode
194
function isClassVNodeOfType(obj: VNode, type: Inferno.ComponentClass<unknown> | Inferno.StatelessComponent<unknown>): boolean
195
function isComponentVNode(obj: VNode): obj is VNode
196
function isComponentVNodeOfType(obj: VNode, type: Function): boolean
197
function isTextVNode(obj: VNode): obj is VNode
198

199
// DOM element type checking
200
function isDOMElement(obj: any): boolean
201
function isDOMElementOfType(obj: any, type: string): boolean
202

203
// Rendered component type checking
204
function isRenderedClassComponent(obj: any): boolean
205
function isRenderedClassComponentOfType(obj: any, type: Inferno.ComponentClass<unknown> | Inferno.StatelessComponent<unknown>): boolean
206
```
207

208
[Type Checking API](./type-checking.md)
209

210
### Tree Traversal and Search
211

212
Powerful tree traversal functions for finding elements in rendered trees and VNode trees with predicate-based filtering.
213

214
```javascript { .api }
215
// Tree traversal
216
function findAllInRenderedTree(renderedTree: any, predicate: (vNode: VNode) => boolean): VNode[] | any
217
function findAllInVNodeTree(vNodeTree: VNode, predicate: (vNode: VNode) => boolean): any
218

219
// Multiple result search (scry functions)
220
function scryRenderedDOMElementsWithClass(renderedTree: any, classNames: string | string[]): Element[]
221
function scryRenderedDOMElementsWithTag(renderedTree: any, tagName: string): Element[]
222
function scryRenderedVNodesWithType(renderedTree: any, type: unknown): VNode[]
223
function scryVNodesWithType(vNodeTree: VNode, type: unknown): VNode[]
224

225
// Single result search (find functions - throw on multiple matches)
226
function findRenderedDOMElementWithClass(renderedTree: any, classNames: string | string[]): Element
227
function findRenderedDOMElementWithTag(renderedTree: any, tagName: string): Element
228
function findRenderedVNodeWithType(renderedTree: any, type: unknown): VNode
229
function findVNodeWithType(vNodeTree: VNode, type: unknown): VNode
230
```
231

232
[Tree Traversal and Search API](./tree-traversal.md)
233

234
### Rendering Utilities
235

236
Utilities for rendering components into test environments and extracting useful information from VNodes.
237

238
```javascript { .api }
239
// Rendering
240
function renderIntoContainer(input: boolean | VNode | InfernoChild | InfernoFragment | null | undefined): Component<any, any> | VNode
241

242
// Utility functions
243
function getTagNameOfVNode(vNode: VNode): string | undefined
244

245
// Test wrapper component
246
class Wrapper<P, S> extends Component<P, S> {
247
  public render(): InfernoNode
248
}
249
```
250

251
[Rendering Utilities API](./rendering.md)
252

253
### Jest Integration
254

255
Native Jest snapshot testing support with functions to convert VNodes to Jest-compatible snapshots.
256

257
```javascript { .api }
258
// Snapshot functions
259
function vNodeToSnapshot(vNode: VNode): InfernoSnapshot
260
function renderToSnapshot(input: VNode): InfernoSnapshot
261
```
262

263
[Jest Integration API](./jest-integration.md)
264

265
## Types
266

267
```typescript
268
// Jest snapshot interface
269
interface InfernoSnapshot {
270
  type: string;
271
  props: Record<string, any>;
272
  children: null | InfernoTestRendererNode[];
273
  $$typeof?: symbol | string;
274
}
275

276
type InfernoTestRendererNode = InfernoSnapshot | string;
277

278
// Inferno types (from inferno package)
279
interface VNode {
280
  flags: number;
281
  type: any;
282
  props: any;
283
  children: any;
284
  key: any;
285
  ref: any;
286
  className: string | null;
287
  dom: Element | null;
288
  childFlags: number;
289
}
290

291
interface Component<P = {}, S = {}> {
292
  props: P;
293
  state: S;
294
  context: any;
295
  render(): InfernoNode;
296
  setState(partial: Partial<S>, callback?: () => void): void;
297
}
298

299
type InfernoNode = VNode | string | number | boolean | null | undefined | InfernoFragment;
300
type InfernoChild = InfernoNode | Array<InfernoNode>;
301
type InfernoFragment = {} | InfernoChild[];
302

303
type ComponentClass<P = {}> = new (props: P, context?: any) => Component<P, any>;
304
type StatelessComponent<P = {}> = (props: P, context?: any) => InfernoNode;
305
```
306

307
## Error Handling
308

309
Functions that expect single results (prefixed with `find`) will throw descriptive errors when:
310
- No matches are found
311
- Multiple matches are found when expecting exactly one match
312
- Invalid input types are provided
313

314
Example error messages:
315
- `"Did not find exactly one match (found 3) for class: inner"`
316
- `"findAllInVNodeTree(vNodeTree, predicate) vNodeTree must be a VNode instance"`
317

318
## Dependencies
319

320
- **inferno**: Core Inferno library for rendering and VNode types
321
- **inferno-shared**: Shared utilities (type checking functions, error handling)
322
- **inferno-vnode-flags**: VNode flag constants (VNodeFlags) for component type identification and child flag constants (ChildFlags) for tree traversal optimization