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
```