0
# TestCafe
1
2
TestCafe is a Node.js-based end-to-end web testing framework that enables automated browser testing without WebDriver dependencies. It provides comprehensive browser automation, rich assertions, multi-browser support, and integrates seamlessly with CI/CD systems.
3
4
## Package Information
5
6
- **Package Name**: testcafe
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install -g testcafe` or `npm install --save-dev testcafe`
10
11
## Core Imports
12
13
```javascript
14
const createTestCafe = require('testcafe');
15
```
16
17
For ES modules:
18
19
```javascript
20
import createTestCafe from 'testcafe';
21
```
22
23
Test file imports:
24
25
```javascript
26
import { Selector, ClientFunction, RequestLogger, RequestMock, Role, t } from 'testcafe';
27
```
28
29
## Basic Usage
30
31
```javascript
32
import { Selector } from 'testcafe';
33
34
fixture('Getting Started')
35
.page('https://devexpress.github.io/testcafe/example');
36
37
test('My first test', async t => {
38
await t
39
.typeText('#developer-name', 'John Smith')
40
.click('#submit-button')
41
.expect(Selector('#article-header').innerText).eql('Thank you, John Smith!');
42
});
43
```
44
45
## Programmatic API Usage
46
47
```javascript
48
import createTestCafe from 'testcafe';
49
50
const testcafe = await createTestCafe('localhost', 1337, 1338);
51
const runner = testcafe.createRunner();
52
53
await runner
54
.src(['tests/fixture1.js', 'tests/fixture2.js'])
55
.browsers(['chrome', 'safari'])
56
.run();
57
58
await testcafe.close();
59
```
60
61
## Architecture
62
63
TestCafe is built around several key components:
64
65
- **Test Controller**: The `t` object providing browser actions and assertions
66
- **Selectors**: CSS/XPath selectors for DOM element identification
67
- **Client Functions**: JavaScript code execution in browser context
68
- **Request Hooks**: HTTP request/response interception and mocking
69
- **Roles**: User authentication and session management
70
- **Browser Providers**: Interfaces to various browser engines
71
- **Reporter System**: Customizable test result reporting
72
73
## Capabilities
74
75
### Browser Automation
76
77
Core browser interaction capabilities including clicks, typing, navigation, and element manipulation.
78
79
```javascript { .api }
80
// Test controller provides browser automation
81
interface TestController {
82
click(selector: string | Selector): Promise<TestController>;
83
typeText(selector: string | Selector, text: string): Promise<TestController>;
84
navigateTo(url: string): Promise<TestController>;
85
}
86
```
87
88
[Browser Automation](./browser-automation.md)
89
90
### Element Selection
91
92
Powerful selector system for identifying and interacting with DOM elements.
93
94
```javascript { .api }
95
function Selector(init: string | Function): SelectorAPI;
96
97
interface SelectorAPI {
98
(): Promise<NodeSnapshot>;
99
find(cssSelector: string): SelectorAPI;
100
withText(text: string | RegExp): SelectorAPI;
101
nth(index: number): SelectorAPI;
102
count: Promise<number>;
103
exists: Promise<boolean>;
104
}
105
```
106
107
[Element Selection](./element-selection.md)
108
109
### Assertions
110
111
Comprehensive assertion system for verifying application state and behavior.
112
113
```javascript { .api }
114
interface Assertion {
115
eql(expected: any): Promise<void>;
116
notEql(expected: any): Promise<void>;
117
ok(): Promise<void>;
118
notOk(): Promise<void>;
119
contains(expected: any): Promise<void>;
120
match(re: RegExp): Promise<void>;
121
}
122
```
123
124
[Assertions](./assertions.md)
125
126
### Request Interception
127
128
HTTP request and response monitoring and mocking capabilities.
129
130
```javascript { .api }
131
function RequestLogger(
132
requestFilterRuleInit?: string | RegExp | object | Function,
133
logOptions?: object
134
): RequestLogger;
135
136
function RequestMock(): RequestMock;
137
138
class RequestHook {
139
constructor(requestFilterRuleInit?: string | RegExp | object | Function);
140
onRequest(event: object): Promise<void>;
141
onResponse(event: object): Promise<void>;
142
}
143
```
144
145
[Request Interception](./request-interception.md)
146
147
### User Roles
148
149
Role-based authentication system for testing user workflows.
150
151
```javascript { .api }
152
function Role(loginUrl: string, initFn: Function, options?: object): Role;
153
154
interface Role {
155
anonymous: Role;
156
}
157
```
158
159
[User Roles](./user-roles.md)
160
161
### Client Functions
162
163
Execute custom JavaScript code in browser context and return results to test.
164
165
```javascript { .api }
166
function ClientFunction(fn: Function, options?: object): ClientFunction;
167
168
interface ClientFunction {
169
(): Promise<any>;
170
with(options: object): ClientFunction;
171
}
172
```
173
174
[Client Functions](./client-functions.md)
175
176
### Programmatic API
177
178
Create and configure TestCafe instances programmatically for advanced test execution control.
179
180
```javascript { .api }
181
function createTestCafe(
182
hostname?: string,
183
port1?: number,
184
port2?: number,
185
sslOptions?: object,
186
developmentMode?: boolean
187
): Promise<TestCafe>;
188
189
interface TestCafe {
190
createRunner(): Runner;
191
createBrowserConnection(): Promise<BrowserConnection>;
192
close(): Promise<void>;
193
}
194
```
195
196
[Programmatic API](./programmatic-api.md)
197
198
### Test Organization
199
200
Global functions for organizing tests into fixtures and defining test cases.
201
202
```javascript { .api }
203
/**
204
* Creates a test fixture (test suite)
205
* @param name - Fixture name
206
* @returns FixtureFunction for chaining configuration methods
207
*/
208
function fixture(name: string): FixtureFunction;
209
210
/**
211
* Creates a test case within a fixture
212
* @param name - Test name
213
* @param fn - Test implementation function
214
* @returns TestFunction for chaining configuration methods
215
*/
216
function test(name: string, fn: (t: TestController) => Promise<void>): TestFunction;
217
```
218
219
## Types
220
221
```javascript { .api }
222
interface NodeSnapshot {
223
tagName: string;
224
attributes: object;
225
boundingClientRect: object;
226
style: object;
227
innerText: string;
228
textContent: string;
229
namespaceURI: string;
230
id: string;
231
className: string;
232
classNames: string[];
233
value: any;
234
checked: boolean;
235
selected: boolean;
236
selectedIndex: number;
237
childElementCount: number;
238
childNodeCount: number;
239
hasChildNodes: boolean;
240
hasChildElements: boolean;
241
visible: boolean;
242
focused: boolean;
243
exists: boolean;
244
}
245
246
interface TestInfo {
247
name: string;
248
meta: object;
249
fixture: {
250
name: string;
251
meta: object;
252
path: string;
253
};
254
browser: {
255
name: string;
256
version: string;
257
platform: string;
258
headless: boolean;
259
userAgent: string;
260
};
261
}
262
263
interface FixtureFunction {
264
(name: string): FixtureFunction;
265
page(url: string | Function): FixtureFunction;
266
httpAuth(credentials: object): FixtureFunction;
267
beforeEach(fn: Function): FixtureFunction;
268
afterEach(fn: Function): FixtureFunction;
269
before(fn: Function): FixtureFunction;
270
after(fn: Function): FixtureFunction;
271
meta(key: string, value: string): FixtureFunction;
272
meta(data: object): FixtureFunction;
273
only: FixtureFunction;
274
skip: FixtureFunction;
275
disablePageReloads: FixtureFunction;
276
disablePageCaching: FixtureFunction;
277
clientScripts(scripts: string | object | Function | Array): FixtureFunction;
278
requestHooks(hooks: RequestHook | Array<RequestHook>): FixtureFunction;
279
}
280
281
interface TestFunction {
282
(name: string, fn: Function): TestFunction;
283
page(url: string | Function): TestFunction;
284
httpAuth(credentials: object): TestFunction;
285
before(fn: Function): TestFunction;
286
after(fn: Function): TestFunction;
287
meta(key: string, value: string): TestFunction;
288
meta(data: object): TestFunction;
289
only: TestFunction;
290
skip: TestFunction;
291
disablePageReloads: TestFunction;
292
disablePageCaching: TestFunction;
293
clientScripts(scripts: string | object | Function | Array): TestFunction;
294
requestHooks(hooks: RequestHook | Array<RequestHook>): TestFunction;
295
}
296
```