• Home
Name Date Size #Lines LOC

..--

coverage_signal_handler/12-May-2024-7351

hamock/12-May-2024-1,4111,101

jsunit/12-May-2024-4,6163,434

uitest/12-May-2024-19,39416,068

CODEOWNERSD12-May-2024602 1413

LICENSED12-May-20249.9 KiB177150

OAT.xmlD12-May-20243.8 KiB6112

README_en.mdD12-May-202448.1 KiB1,110866

README_zh.mdD12-May-202467.6 KiB1,5711,259

bundle.jsonD12-May-20241.3 KiB5756

README_en.md

1# arkXtest
2
3## Introduction
4arkXtest, the automated test framework of OpenHarmony, consists of the JS unit test framework (JsUnit) and UI test framework (UiTest).
5
6JsUnit provides APIs for writing test cases for system or application interfaces, executing unit test cases, and generating test reports.
7
8UiTest provides simple and easy-to-use APIs for locating and operating UI components, helping users to develop automatic test scripts based on UI operations.
9
10## Directory Structure
11
12```
13arkXtest
14  |-----jsunit  Unit test framework
15  |-----uitest UI test framework
16```
17## Constraints
18The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
19
20## JsUnit Features
21
22| No.  | Feature    | Description                                                    |
23| ---- | -------- | ------------------------------------------------------------ |
24| 1    | Basic process support| Provides APIs for writing and executing test cases.                                    |
25| 2    | Assertion library  | Provides APIs for checking whether the actual value of a test case is the same as the expected value.                        |
26| 3    | Mock| Provides APIs for mocking functions to return the specified value or perform the specified action.|
27| 4    | Data driving| Provides APIs for reusing a test script with different input data.|
28
29### How to Use
30
31####  Basic Process Support
32
33Test cases use the common syntax in the industry. **describe** defines a test suite, and **it** specifies a test case.
34
35| No.  | API        | Description                                                    |
36| ---- | ---------- | ------------------------------------------------------------ |
37| 1    | describe   | Defines a test suite. This API supports two parameters: test suite name and test suite function.      |
38| 2    | beforeAll  | Presets an action, which is performed only once before all test cases of the test suite start. This API supports only one parameter: preset action function.|
39| 3    | beforeEach | Presets an action, which is performed before each unit test case starts. The number of execution times is the same as the number of test cases defined by **it**. This API supports only one parameter: preset action function.|
40| 4    | afterEach  | Presets a clear action, which is performed after each unit test case ends. The number of execution times is the same as the number of test cases defined by **it**. This API supports only one parameter: clear action function.|
41| 5    | afterAll   | Presets a clear action, which is performed after all test cases of the test suite end. This API supports only one parameter: clear action function.|
42| 6    | it         | Defines a test case. This API supports three parameters: test case name, filter parameter, and test case function.|
43| 7    | expect     | Defines a variety of assertion methods, which are used to declare expected Boolean conditions.                            |
44
45The sample code is as follows:
46
47```javascript
48import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium'
49import demo from '@ohos.bundle'
50
51export default async function abilityTest() {
52  describe('ActsAbilityTest', function () {
53    it('String_assertContain_success', 0, function () {
54      let a = 'abc'
55      let b = 'b'
56      expect(a).assertContain(b)
57      expect(a).assertEqual(a)
58    })
59    it('getBundleInfo_0100', 0, async function () {
60      const NAME1 = "com.example.MyApplicationStage"
61      await demo.getBundleInfo(NAME1,
62        demo.BundleFlag.GET_BUNDLE_WITH_ABILITIES | demo.BundleFlag.GET_BUNDLE_WITH_REQUESTED_PERMISSION)
63        .then((value) => {
64          console.info(value.appId)
65        })
66        .catch((err) => {
67          console.info(err.code)
68        })
69    })
70  })
71}
72```
73
74
75
76####  Assertion Library
77
78Available APIs:
79
80
81| No.  | API              | Description                                                  |
82| :--- | :--------------- | ------------------------------------------------------------ |
83| 1    | assertClose      | Checks whether the proximity between the actual value and the expected value (0) is the expected value (1). |
84| 2    | assertContain    | Checks whether the actual value contains the expected value. |
85| 3    | assertEqual      | Checks whether the actual value is equal to the expected value. |
86| 4    | assertFail       | Throws an error.                                             |
87| 5    | assertFalse      | Check whether the actual value is **false**.                 |
88| 6    | assertTrue       | Checks whether the actual value is **true**.                 |
89| 7    | assertInstanceOf | Checks whether the actual value is of the type specified by the expected value,basic types are supported. |
90| 8    | assertLarger     | Checks whether the actual value is greater than the expected value. |
91| 9    | assertLess       | Checks whether the actual value is less than the expected value. |
92| 10   | assertNull       | Checks whether the actual value is null.                     |
93| 11   | assertThrowError | Checks whether the error thrown by the actual value is the expected value. |
94| 12   | assertUndefined  | Checks whether the actual value is **undefined**.            |
95
96The sample code is as follows:
97
98```javascript
99import { describe, it, expect } from '@ohos/hypium'
100export default async function abilityTest() {
101  describe('assertClose', function () {
102    it('assertBeClose_success', 0, function () {
103      let a = 100
104      let b = 0.1
105      expect(a).assertClose(99, b)
106    })
107    it('assertBeClose_fail', 0, function () {
108      let a = 100
109      let b = 0.1
110      expect(a).assertClose(1, b)
111    })
112    it('assertBeClose_fail', 0, function () {
113      let a = 100
114      let b = 0.1
115      expect(a).assertClose(null, b)
116    })
117    it('assertBeClose_fail', 0, function () {
118      expect(null).assertClose(null, 0)
119    })
120    it('assertInstanceOf_success', 0, function () {
121      let a = 'strTest'
122      expect(a).assertInstanceOf('String')
123    })
124  })
125}
126```
127
128
129#### Mock
130
131##### Constraints
132
133JsUnit provides the mock capability since npm [1.0.1](https://repo.harmonyos.com/#/en/application/atomService/@ohos%2Fhypium). You must modify the npm version in **package.info** of the source code project before using the mock capability.
134
135-  **Available APIs**
136
137| No. | API | Description|
138| --- | --- | --- |
139| 1 | mockFunc(obj: object, f: function())| Mocks a function in the object of a class. The parameters **obj** and **f** must be passed in. This API supports asynchronous functions. <br>**NOTE**: This API does not focus on the implementation of the original function. Therefore, it does not matter whether the original function is implemented synchronously or asynchronously.|
140| 2 | when(mockedfunc: function)| Checks whether the input function is mocked and marked. A function declaration is returned.|
141| 3 | afterReturn(x: value)| Sets an expected return value, for example, a string or promise.|
142| 4 | afterReturnNothing() | Sets the expected return value to **undefined**, that is, no value will be returned.|
143| 5 | afterAction(x: action)| Sets the expected return value to be an action executed by a function.|
144| 6 | afterThrow(x: msg)| Sets an exception to throw and the error message.|
145| 7 | clear() | Restores the mocked object after the test case is complete (restores the original features of the object).|
146| 8 | any | Returns the expected value if a parameter of any type (except **undefined** and **null**) is passed in. This API must be called by **ArgumentMatchers.any**.|
147| 9 | anyString | Returns the expected value if a string is passed in. This API must be called by **ArgumentMatchers.anyString**.|
148| 10 | anyBoolean | Returns the expected value if a Boolean value is passed in. This API must be called by **ArgumentMatchers.anyBoolean**.|
149| 11 | anyFunction | Returns the expected value if a function is passed in. This API must be called by **ArgumentMatchers.anyFunction**.|
150| 12 | anyNumber | Returns the expected value if a number is passed in. This API must be called by **ArgumentMatchers.anyNumber**.|
151| 13 | anyObj | Returns the expected value if an object is passed in. This API must be called by **ArgumentMatchers.anyObj**.|
152| 14 | matchRegexs(Regex) | Returns the expected value if a regular expression is passed in. This API must be called by **ArgumentMatchers.matchRegexs(Regex)**.|
153| 15 | verify(methodName, argsArray) | Verifies whether a function and its parameters are processed as expected. This API returns a **VerificationMode**, which is a class that provides the verification mode. This class provides functions such as **times(count)**, **once()**, **atLeast(x)**, **atMost(x)**, and **never()**.|
154| 16 | times(count) | Verifies whether the function was executed the specified number of times.|
155| 17 | once() | Verifies whether the function was executed only once.|
156| 18 | atLeast(count) | Verifies whether the function was executed at least **count** times.|
157| 19 | atMost(count) | Verifies whether the function was executed at most **count** times.|
158| 20 | never | Verifies whether the function has never been executed.|
159| 21 | ignoreMock(obj, method) | Restores the mocked function in the object. This API is valid for mocked functions.|
160| 22 | clearAll() | Clears all data and memory after the test cases are complete.|
161
162-  **Examples**
163
164You can refer to the following examples to import the mock module and write test cases.
165
166- **NOTICE**<br>
167You must import **MockKit** and **when**. You can import other assertion APIs based on the test cases.
168Example: `import {describe, expect, it, MockKit, when} from '@ohos/hypium'`
169
170Example 1: Use **afterReturn**.
171
172```javascript
173import {describe, expect, it, MockKit, when} from '@ohos/hypium';
174
175export default function ActsAbilityTest() {
176    describe('ActsAbilityTest', function () {
177        it('testMockfunc', 0, function () {
178            console.info("it1 begin");
179
180            // 1. Create a MockKit object.
181            let mocker = new MockKit();
182
183            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
184            class ClassName {
185                constructor() {
186                }
187
188                method_1(arg) {
189                    return '888888';
190                }
191
192                method_2(arg) {
193                    return '999999';
194                }
195            }
196
197            let claser = new ClassName();
198
199            // 3. Mock method_1 of the ClassName class.
200            let mockfunc = mocker.mockFunc(claser, claser.method_1);
201            when(mockfunc)('test').afterReturn('1');
202
203            // 4. Assert whether the mocked function is implemented as expected.
204            // The operation is successful if 'test' is passed in.
205            expect(claser.method_1('test')).assertEqual('1'); // The operation is successful.
206
207            // The operation fails if 'abc' is passed in.
208            //expect(claser.method_1('abc')).assertEqual('1'); // The operation fails.
209        });
210    });
211}
212```
213- **NOTICE**<br>
214In `when(mockfunc)('test').afterReturn('1');`, `('test')` is the value to pass in the mocked function. Currently, only one parameter is supported. `afterReturn('1')` is the expected return value. The expected value is returned only when `('test')` is passed in.
215
216Example 2: Use **afterReturnNothing**.
217
218```javascript
219import {describe, expect, it, MockKit, when} from '@ohos/hypium';
220
221export default function ActsAbilityTest() {
222    describe('ActsAbilityTest', function () {
223        it('testMockfunc', 0, function () {
224            console.info("it1 begin");
225
226            // 1. Create a MockKit object.
227            let mocker = new MockKit();
228
229            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
230            class ClassName {
231                constructor() {
232                }
233
234                method_1(arg) {
235                    return '888888';
236                }
237
238                method_2(arg) {
239                    return '999999';
240                }
241            }
242
243            let claser = new ClassName();
244
245            // 3. Mock method_1 of the ClassName class.
246            let mockfunc = mocker.mockFunc(claser, claser.method_1);
247
248            // 4. Set the action to be performed when the test case ends. For example, set it to afterReturnNothing(), which returns no value.
249            when(mockfunc)('test').afterReturnNothing();
250
251            // 5. Assert whether the mocked function is implemented as expected. Use the assertion APIs corresponding to Step 4.
252            // The operation is successful if 'test' is passed in.
253            // The mocked claser.method_1 does not return '888888'. Instead, afterReturnNothing() takes effect, that is, no value is returned.
254            expect(claser.method_1('test')).assertUndefined(); // The operation is successful.
255
256            // The operation fails if '123' is passed in.
257            // expect(method_1(123)).assertUndefined();// The operation fails.
258        });
259    });
260}
261```
262
263Example 3: Set the parameter type to **any**, that is, allow any parameter value except **undefine** and **null**.
264
265
266- **NOTICE**<br>
267The **ArgumentMatchers** class, for example, **ArgumentMatchers.any**, must be imported.
268
269```javascript
270import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
271
272export default function ActsAbilityTest() {
273    describe('ActsAbilityTest', function () {
274        it('testMockfunc', 0, function () {
275            console.info("it1 begin");
276
277            // 1. Create a MockKit object.
278            let mocker = new MockKit();
279
280            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
281            class ClassName {
282                constructor() {
283                }
284
285                method_1(arg) {
286                    return '888888';
287                }
288
289                method_2(arg) {
290                    return '999999';
291                }
292            }
293
294            let claser = new ClassName();
295
296            // 3. Mock method_1 of the ClassName class.
297            let mockfunc = mocker.mockFunc(claser, claser.method_1);
298            // Set the parameter matcher and expected return value as required.
299            when(mockfunc)(ArgumentMatchers.any).afterReturn('1');
300
301            // 4. Assert whether the mocked function is implemented as expected.
302            // The operation is successful if a string is passed in.
303            expect(claser.method_1('test')).assertEqual('1'); // The operation is successful.
304            // The operation is successful if a number (for example '123') is passed in.
305            expect(claser.method_1(123)).assertEqual('1'); // The operation is successful.
306            // The operation is successful if a Boolean value (for example 'true') is passed in.
307            expect(claser.method_1(true)).assertEqual('1');// The operation is successful.
308
309            // The operation fails if an empty value is passed in.
310            //expect(claser.method_1()).assertEqual('1');// The operation fails.
311        });
312    });
313}
314```
315
316Example 4: Set the parameter type to **anyString**.
317
318```javascript
319import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
320
321export default function ActsAbilityTest() {
322    describe('ActsAbilityTest', function () {
323        it('testMockfunc', 0, function () {
324            console.info("it1 begin");
325
326            // 1. Create a MockKit object.
327            let mocker = new MockKit();
328
329            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
330            class ClassName {
331                constructor() {
332                }
333
334                method_1(arg) {
335                    return '888888';
336                }
337
338                method_2(arg) {
339                    return '999999';
340                }
341            }
342
343            let claser = new ClassName();
344
345            // 3. Mock method_1 of the ClassName class.
346            let mockfunc = mocker.mockFunc(claser, claser.method_1);
347            // Set the following parameters as required.
348            when(mockfunc)(ArgumentMatchers.anyString).afterReturn('1');
349
350            // 4. Assert whether the mocked function is implemented as expected.
351            // The operation is successful if a string is passed in.
352            expect(claser.method_1('test')).assertEqual('1'); // The operation is successful.
353            expect(claser.method_1('abc')).assertEqual('1'); // The operation is successful.
354
355            // The operation fails if a number or a Boolean value is passed in.
356            //expect(claser.method_1(123)).assertEqual('1'); // The operation fails.
357            //expect(claser.method_1(true)).assertEqual('1'); // The operation fails.
358        });
359    });
360}
361```
362
363Example 5: Set the parameter type to **matchRegexs (Regex)**.
364```javascript
365import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
366
367export default function ActsAbilityTest() {
368    describe('ActsAbilityTest', function () {
369        it('testMockfunc', 0, function () {
370            console.info("it1 begin");
371
372            // 1. Create a MockKit object.
373            let mocker = new MockKit();
374
375            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
376            class ClassName {
377                constructor() {
378                }
379
380                method_1(arg) {
381                    return '888888';
382                }
383
384                method_2(arg) {
385                    return '999999';
386                }
387            }
388
389            let claser = new ClassName();
390
391            // 3. Mock method_1 of the ClassName class.
392            let mockfunc = mocker.mockFunc(claser, claser.method_1);
393            // Set a regular expression to match, for example, /123456/.
394            when(mockfunc)(ArgumentMatchers.matchRegexs(/123456/)).afterReturn('1');
395
396            // 4. Assert whether the mocked function is implemented as expected.
397            // The operation is successful if a string, for example, '1234567898', is passed in.
398            expect(claser.method_1('1234567898')).assertEqual('1'); // The operation is successful.
399            // The string '1234567898' matches the regular expression /123456/.
400
401            // The operation fails if '1234' is passed in.
402            //expect(claser.method_1('1234').assertEqual('1'); // The operation fails because '1234' does not match the regular expression /123456/.
403        });
404    });
405}
406```
407
408Example 6: Use **verify()**.
409```javascript
410import {describe, expect, it, MockKit, when} from '@ohos/hypium';
411
412export default function ActsAbilityTest() {
413    describe('ActsAbilityTest', function () {
414        it('testMockfunc', 0, function () {
415            console.info("it1 begin");
416
417            // 1. Create a MockKit object.
418            let mocker = new MockKit();
419
420            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
421            class ClassName {
422                constructor() {
423                }
424
425                method_1(...arg) {
426                    return '888888';
427                }
428
429                method_2(...arg) {
430                    return '999999';
431                }
432            }
433
434            let claser = new ClassName();
435
436            // 3. Mock method_1 and method_2 of the ClassName class.
437            mocker.mockFunc(claser, claser.method_1);
438            mocker.mockFunc(claser, claser.method_2);
439
440            // 4. Call the following methods.
441            claser.method_1('abc', 'ppp');
442            claser.method_1('abc');
443            claser.method_1('xyz');
444            claser.method_1();
445            claser.method_1('abc', 'xxx', 'yyy');
446            claser.method_1();
447            claser.method_2('111');
448            claser.method_2('111', '222');
449
450            //5. Verify the mocked functions.
451            mocker.verify('method_1', []).atLeast(3); // The result is "failed".
452            // Verify whether 'method_1' with an empty parameter list was executed at least three times.
453            // The result is "failed" because 'method_1' with an empty parameter list was executed only twice in Step 4.
454            //mocker.verify('method_2',['111']).once(); // The result is "success".
455            //mocker.verify('method_2',['111',,'222']).once(); // The result is "success".
456        });
457    });
458}
459```
460
461Example 7: Use **ignoreMock(obj, method)**.
462```javascript
463import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
464
465export default function ActsAbilityTest() {
466    describe('ActsAbilityTest', function () {
467        it('testMockfunc', 0, function () {
468            console.info("it1 begin");
469
470            // 1. Create a MockKit object.
471            let mocker = new MockKit();
472
473            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
474            class ClassName {
475                constructor() {
476                }
477
478                method_1(...arg) {
479                    return '888888';
480                }
481
482                method_2(...arg) {
483                    return '999999';
484                }
485            }
486
487            let claser = new ClassName();
488
489            // 3. Mock method_1 and method_2 of the ClassName class.
490            let func_1 = mocker.mockFunc(claser, claser.method_1);
491            let func_2 = mocker.mockFunc(claser, claser.method_2);
492
493            // 4. Modify the mocked functions.
494            when(func_1)(ArgumentMatchers.anyNumber).afterReturn('4');
495            when(func_2)(ArgumentMatchers.anyNumber).afterReturn('5');
496
497            // 5. Call the following methods.
498            console.log(claser.method_1(123)); // The return value is 4, which is the same as the expected value in Step 4.
499            console.log(claser.method_2(456)); // The return value is 5, which is the same as the expected value in Step 4.
500
501            // 6. Restore method_1 using ignoreMock().
502            mocker.ignoreMock(claser, claser.method_1);
503            // Call claser.method_1 and check the execution result.
504            console.log(claser.method_1(123)); // The return value is 888888, which is the same as that returned by the original function.
505            // Test with assertions.
506            expect(claser.method_1(123)).assertEqual('4'); // The return value is "failed", which meets the expected value of ignoreMock().
507            claser.method_2(456); // The return value is 5, which is the same as the expected value in Step 4 because method_2 is not restored.
508        });
509    });
510}
511```
512
513Example 8: Use **clear()**.
514
515```javascript
516import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
517
518export default function ActsAbilityTest() {
519    describe('ActsAbilityTest', function () {
520        it('testMockfunc', 0, function () {
521            console.info("it1 begin");
522
523            // 1. Create a MockKit object.
524            let mocker = new MockKit();
525
526            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
527            class ClassName {
528                constructor() {
529                }
530
531                method_1(...arg) {
532                    return '888888';
533                }
534
535                method_2(...arg) {
536                    return '999999';
537                }
538            }
539            let claser = new ClassName();
540
541            // 3. Mock method_1 and method_2 of the ClassName class.
542            let func_1 = mocker.mockFunc(claser, claser.method_1);
543            let func_2 = mocker.mockFunc(claser, claser.method_2);
544
545            // 4. Modify the mocked functions.
546            when(func_1)(ArgumentMatchers.anyNumber).afterReturn('4');
547            when(func_2)(ArgumentMatchers.anyNumber).afterReturn('5');
548
549            // 5. Call the following methods.
550            //expect(claser.method_1(123)).assertEqual('4'); // The return value is the same as the expected value.
551            //expect(claser.method_2(456)).assertEqual('5'); // The return value is the same as the expected value.
552
553            // 6. Clear the mock operation.
554            mocker.clear(claser);
555            // Call claser.method_1 and check the execution result.
556            expect(claser.method_1(123)).assertEqual('4'); // The return value is "failed", which meets the expectation.
557            expect(claser.method_2(456)).assertEqual('5'); // The return value is "failed", which meets the expectation.
558        });
559    });
560}
561```
562
563
564Example 9: Use **afterThrow(msg)**.
565
566```javascript
567import {describe, expect, it, MockKit, when} from '@ohos/hypium';
568
569export default function ActsAbilityTest() {
570    describe('ActsAbilityTest', function () {
571        it('testMockfunc', 0, function () {
572            console.info("it1 begin");
573
574            // 1. Create a MockKit object.
575            let mocker = new MockKit();
576
577            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
578            class ClassName {
579                constructor() {
580                }
581
582                method_1(arg) {
583                    return '888888';
584                }
585            }
586
587            let claser = new ClassName();
588
589            // 3. Mock method_1 of the ClassName class.
590            let mockfunc = mocker.mockFunc(claser, claser.method_1);
591
592            // 4. Set the action to be performed when the test case ends. For example, set it to afterReturnNothing(), which returns no value.
593            when(mockfunc)('test').afterThrow('error xxx');
594
595            // 5. Execute the mocked function, capture the exception, and use assertEqual() to check whether message meets the expectation.
596            try {
597                claser.method_1('test');
598            } catch (e) {
599                expect(e).assertEqual('error xxx'); // The execution is successful.
600            }
601        });
602    });
603}
604```
605
606Example 10: Mock asynchronous functions.
607
608```javascript
609import {describe, expect, it, MockKit, when} from '@ohos/hypium';
610
611export default function ActsAbilityTest() {
612    describe('ActsAbilityTest', function () {
613        it('testMockfunc', 0, function () {
614            console.info("it1 begin");
615
616            // 1. Create a MockKit object.
617            let mocker = new MockKit();
618
619            // 2. Define the ClassName class, which contains two functions, and then create a claser object.
620            class ClassName {
621                constructor() {
622                }
623
624                async method_1(arg) {
625                    return new Promise((res, rej) => {
626                        // Perform asynchronous operations.
627                        setTimeout(function () {
628                            console.log ('Execute');
629                            res('Pass data');
630                        }, 2000);
631                    });
632                }
633            }
634
635            let claser = new ClassName();
636
637            // 3. Mock method_1 of the ClassName class.
638            let mockfunc = mocker.mockFunc(claser, claser.method_1);
639
640            // 4. Set the action to be performed after the test case ends. For example, set it to afterRetrun(), which returns a custom promise.
641            when(mockfunc)('test').afterReturn(new Promise((res, rej) => {
642                console.log("do something");
643                res('success something');
644            }));
645
646            // 5. Execute the mocked function, that is, execute the promise.
647            claser.method_1('test').then(function (data) {
648                // Code for data processing
649                console.log('result : ' + data);
650            });
651        });
652    });
653}
654```
655
656Example 11: Mock a system function.
657
658```javascript
659export default function ActsAbilityTest() {
660    describe('ActsAbilityTest', function () {
661        it('test_systemApi', 0, function () {
662            // 1. Create a MockKit object.
663            let mocker = new MockKit();
664            // 2. Mock the app.getInfo() function.
665            let mockf = mocker.mockFunc(app, app.getInfo);
666            when(mockf)('test').afterReturn('1');
667            // The operation is successful.
668            expect(app.getInfo('test')).assertEqual('1');
669        });
670    });
671}
672```
673
674
675Example 12: Verify **times(count)**.
676
677```javascript
678import { describe, expect, it, MockKit, when } from '@ohos/hypium'
679
680export default function ActsAbilityTest() {
681    describe('ActsAbilityTest', function () {
682        it('test_verify_times', 0, function () {
683            // 1. Create a MockKit object.
684            let mocker = new MockKit();
685            // 2. Define the class to be mocked.
686            class ClassName {
687                constructor() {
688                }
689
690                method_1(...arg) {
691                    return '888888';
692                }
693            }
694            // 3. Create an object of the class.
695            let claser = new ClassName();
696            // 4. Mock a function, for example, method_1, of the object.
697            let func_1 = mocker.mockFunc(claser, claser.method_1);
698            // 5. Set the expected value to be returned by the mocked function.
699            when(func_1)('123').afterReturn('4');
700
701            // 6. Execute the function several times, with parameters set as follows:
702            claser.method_1('123', 'ppp');
703            claser.method_1('abc');
704            claser.method_1('xyz');
705            claser.method_1();
706            claser.method_1('abc', 'xxx', 'yyy');
707            claser.method_1('abc');
708            claser.method_1();
709            // 7. Check whether method_1 with the parameter of 'abc' was executed twice.
710            mocker.verify('method_1', ['abc']).times(2);
711        });
712    });
713}
714```
715
716
717Example 13: Verify **atLeast(count)**.
718
719```javascript
720import { describe, expect, it, MockKit, when } from '@ohos/hypium'
721
722export default function ActsAbilityTest() {
723    describe('ActsAbilityTest', function () {
724        it('test_verify_atLeast', 0, function () {
725            // 1. Create a MockKit object.
726            let mocker = new MockKit();
727            // 2. Define the class to be mocked.
728            class ClassName {
729                constructor() {
730                }
731
732                method_1(...arg) {
733                    return '888888';
734                }
735            }
736
737            // 3. Create an object of the class.
738            let claser = new ClassName();
739            // 4. Mock a function, for example, method_1, of the object.
740            let func_1 = mocker.mockFunc(claser, claser.method_1);
741            // 5. Set the expected value to be returned by the mocked function.
742            when(func_1)('123').afterReturn('4');
743            // 6. Execute the function several times, with parameters set as follows:
744            claser.method_1('123', 'ppp');
745            claser.method_1('abc');
746            claser.method_1('xyz');
747            claser.method_1();
748            claser.method_1('abc', 'xxx', 'yyy');
749            claser.method_1();
750            // 7. Check whether method_1 with an empty value was executed at least twice.
751            mocker.verify('method_1', []).atLeast(2);
752        });
753    });
754}
755```
756
757#### Data Driving
758
759##### Constraints
760
761JsUnit provides the following data driving capability since [Hypium 1.0.2](https://repo.harmonyos.com/#/en/application/atomService/@ohos%2Fhypium):
762
763- Passes parameters for the specified test suite and test case.
764- Specifies the number of times that the test suite and test case are executed.
765
766The execution times of test cases and the parameters passed in each time are determined by the settings in **data.json**. The file content is as follows:
767
768>**NOTE**<br>The **data.json** file is in the same directory as the **.test.js** or **.test.ets** file.
769
770```json
771{
772	"suites": [{
773		"describe": ["actsAbilityTest"],
774		"stress": 2,
775		"params": {
776			"suiteParams1": "suiteParams001",
777			"suiteParams2": "suiteParams002"
778		},
779		"items": [{
780			"it": "testDataDriverAsync",
781			"stress": 2,
782			"params": [{
783				"name": "tom",
784				"value": 5
785			}, {
786				"name": "jerry",
787				"value": 4
788			}]
789		}, {
790			"it": "testDataDriver",
791			"stress": 3
792		}]
793	}]
794}
795```
796
797Parameter description:
798
799|      | Name| Description                                 | Mandatory|
800| :--- | :--------- | :------------------------------------ | ---- |
801| 1    | "suite"    | Test suite configuration.                        | Yes  |
802| 2    | "items"    | Test case configuration.                      | Yes  |
803| 3    | "describe" | Test suite name.                        | Yes  |
804| 4    | "it"       | Test case name.                      | Yes  |
805| 5    | "params"   | Parameters to be passed to the test suite or test case.| No  |
806| 6    | "stress"   | Number of times that the test suite or test case is executed.    | No  |
807
808The sample code is as follows:
809
810Import the **data.json** file to the **app.js** or **app.ets** file in the **TestAbility** directory, and set parameters before executing the **Hypium.hypiumTest()** method.
811
812```javascript
813import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
814import { Hypium } from '@ohos/hypium'
815import testsuite from '../test/List.test'
816import data from '../test/data.json';
817
818...
819Hypium.setData(data);
820Hypium.hypiumTest(abilityDelegator, abilityDelegatorArguments, testsuite)
821...
822```
823
824```javascript
825import {describe, beforeAll, beforeEach, afterEach, afterAll, it, expect} from '@ohos/hypium';
826
827export default function abilityTest() {
828    describe('actsAbilityTest', function () {
829        it('testDataDriverAsync', 0, async function (done, data) {
830            console.info('name: ' + data.name);
831            console.info('value: ' + data.value);
832            done();
833        });
834
835        it('testDataDriver', 0, function () {
836            console.info('stress test');
837        });
838    });
839}
840```
841
842### How to Use
843
844JsUnit is released as an npm (hypium) package at the [service component official website](https://repo.harmonyos.com/#/en/application/atomService/@ohos%2Fhypium). You can download Deveco Studio, configure dependencies in the application project, and use JsUnit. For details about how to create a test project and execute test scripts, see the [OpenHarmony Test Framework](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001267284568).
845
846## UiTest Features
847
848| No.  | Feature       | Description                                                    |
849| ---- | ----------- | ------------------------------------------------------------ |
850| 1    | UiDriver    | Provides the UI test entry. It provides APIs for locating a component, checking whether a component exists, and injecting a key.|
851| 2    | By          | Describes the attributes (such as text, ID, and type) of UI components. `UiDriver` locates the component based on the attributes described by `By`.|
852| 3    | UiComponent | Provides the UI component object, which provides APIs for obtaining component attributes, clicking a component, and scrolling to search for a component.|
853| 4    | UiWindow    | Provides the window object, which provides APIs for obtaining window attributes, dragging a window, and adjusting the window size.|
854
855Import the following to the test script:
856
857```typescript
858import {UiDriver,BY,UiComponent,Uiwindow,MatchPattern} from '@ohos.uitest'
859```
860
861> **NOTICE**<br>
862> - All APIs provided by the `By` class are synchronous. You can use `builder` to call the APIs in chain mode to construct component filtering conditions.
863> - All the APIs provided by the `UiDriver` and `UiComponent` classes are asynchronous (in `Promise` mode), and `await` must be used.
864> - All UI test cases must be written in the asynchronous syntax and comply with the asynchronous test case specifications of JsUnit.
865
866
867
868Import the `By`, `UiDriver`, and `UiComponent` classes to the test case file, and then call the APIs to write test cases.
869
870```javascript
871import {describe, beforeAll, beforeEach, afterEach, afterAll, it, expect} from '@ohos/hypium'
872import {BY, UiDriver, UiComponent, MatchPattern} from '@ohos.uitest'
873
874export default async function abilityTest() {
875  describe('uiTestDemo', function() {
876    it('uitest_demo0', 0, async function() {
877      // create UiDriver
878      let driver = await UiDriver.create()
879      // find component by text
880      let button = await driver.findComponent(BY.text('hello').enabled(true))
881      // click component
882      await button.click()
883      // get and assert component text
884      let content = await button.getText()
885      expect(content).assertEquals('clicked!')
886    })
887  })
888}
889```
890
891### Using UiDriver
892
893As the main entry to UiTest, the `UiDriver` class provides APIs for component matching/search, key injection, coordinate clicking/swiping, and screenshot.
894
895| No.  | API                                                          | Description                |
896| ---- | ------------------------------------------------------------ | ------------------------ |
897| 1    | create():Promise<UiDriver>                                   | Creates a **UiDriver** object. This API is a static method.|
898| 2    | findComponent(b:By):Promise<UiComponent>                     | Searches for a component.          |
899| 3    | pressBack():Promise<void>                                    | Presses the BACK button.            |
900| 4    | click(x:number, y:number):Promise<void>                      | Clicks a specific point based on the given coordinates.      |
901| 5    | swipe(x1:number, y1:number, x2:number, y2:number):Promise<void> | Swipes based on the given coordinates.      |
902| 6    | assertComponentExist(b:By):Promise<void>                     | Asserts that the component matching the given attributes exists on the current page.    |
903| 7    | delayMs(t:number):Promise<void>                              | Delays this **UiDriver** object for the specified duration.                  |
904| 8    | screenCap(s:path):Promise<void>                              | Captures the current screen.                  |
905| 9    | findWindow(filter: WindowFilter): Promise<UiWindow>          | Searches for a window.          |
906
907**assertComponentExist()** is an assertion API, which is used to assert that the target component exists on the current page. If the component does not exist, a JS exception will be thrown, causing the test case to fail.
908
909```javascript
910import {BY,UiDriver,UiComponent} from '@ohos.uitest'
911
912export default async function abilityTest() {
913  describe('UiTestDemo', function() {
914    it('Uitest_demo0', 0, async function(done) {
915      try{
916        // create UiDriver
917        let driver = await UiDriver.create()
918        // assert text 'hello' exists on current Ui
919        await assertComponentExist(BY.text('hello'))
920      } finally {
921        done()
922      }
923    })
924  })
925}
926```
927
928For details about the APIs of `UiDriver`, see [@ohos.uitest.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.UiTest.d.ts) and [UiDriver](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-uitest.md#uidriver).
929
930### Using By
931
932UiTest provides a wide range of UI component feature description APIs in the `By` class to filter and match components. The APIs provided by `By` exhibit the following features:
933
934- Allow one or more attributes as the match conditions. For example, you can specify both the text and id attributes to find a component.
935- Provide a variety of match patterns (`EQUALS`, `CONTAINS`, `STARTS_WITH`, and `ENDS_WITH`) for component attributes.
936- Support relative positioning for components. APIs such as `isBefore` and `isAfter` can be used to specify the features of adjacent components to assist positioning.
937
938| No.  | API                                | Description                                        |
939| ---- | ---------------------------------- | ------------------------------------------------ |
940| 1    | id(i:number):By                    | Specifies the component ID.                                    |
941| 2    | text(t:string, p?:MatchPattern):By | Specifies the component text. You can specify the match pattern.                  |
942| 3    | type(t:string)):By                 | Specifies the component type.                                  |
943| 4    | enabled(e:bool):By                 | Specifies the component state, which can be enabled or disabled.                              |
944| 5    | clickable(c:bool):By               | Specifies the clickable status of the component.                            |
945| 6    | focused(f:bool):By                 | Specifies the focused status of the component.                              |
946| 7    | scrollable(s:bool):By              | Specifies the scrollable status of the component.                            |
947| 8    | selected(s:bool):By                | Specifies the selected status of the component.                              |
948| 9    | isBefore(b:By):By                  | Specifies the attributes of the component that locates before the target component.|
949| 10   | isAfter(b:By):By                   | Specifies the attributes of the component that locates after the target component.|
950
951The `text` attribute supports match patterns `MatchPattern.EQUALS`, `MatchPattern.CONTAINS`, `MatchPattern.STARTS_WITH`, and `MatchPattern.ENDS_WITH`. The default match pattern is `MatchPattern.EQUALS`.
952
953For details about the APIs of `By`, see [@ohos.uitest.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.UiTest.d.ts) and [By](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-uitest.md#by).
954
955#### Absolute Positioning of a Component
956
957Example 1: Search for component `Id_button`.
958
959```javascript
960let button = await driver.findComponent(BY.id(Id_button))
961```
962
963 Example 2: Search for component `Id_button` in the `enabled` state. Use this API when the component cannot be located based on a single attribute.
964
965```javascript
966let button = await driver.findComponent(BY.id(Id_button).enabled(true))
967```
968
969Use `By.id(x).enabled(y)` to specify multiple attributes of the target component.
970
971Example 3: Search for the component whose text contains `hello`. Use this API when the component attribute values cannot be completely determined.
972
973```javascript
974let txt = await driver.findComponent(BY.text("hello", MatchPattern.CONTAINS))
975```
976
977`By.text()` passes the second parameter `MatchPattern.CONTAINS` to specify the matching rule. The default rule is `MatchPattern.EQUALS`, that is, the text attribute of the target component must be equal to the specified value.
978
979####  Relative Positioning of a Component
980
981Example 1: Search for the switch component `ResourceTable.Id_switch` following the text component `Item3_3`.
982
983```javascript
984let switch = await driver.findComponent(BY.id(Id_switch).isAfter(BY.text("Item3_3")))
985```
986
987Use `By.isAfter` to specify the attributes of the feature component located before the target component for relative positioning. Generally, a feature component is a component that has a globally unique feature (for example, a unique ID or a unique text).
988
989Similarly, you can use `By.isBefore` to specify the attributes of the feature component located after the target component to implement relative positioning.
990
991### Using UiComponent
992
993The `UiComponent` class represents a UI component, which can be located by using `UiDriver.findComponent(by)`. It provides APIs for obtaining component attributes, clicking a component, scrolling to search for a component, and text injection.
994
995`UiComponent` provides the following APIs:
996
997| No.  | API                               | Description                                      |
998| ---- | --------------------------------- | ---------------------------------------------- |
999| 1    | click():Promise<void>             | Clicks the component.                                  |
1000| 2    | inputText(t:string):Promise<void> | Inputs text into the component. This API is applicable to text box components.          |
1001| 3    | scrollSearch(s:By):Promise<bool>  | Scrolls on this component to search for the target component. This API is applicable to the **List** components.|
1002| 4    | getText():Promise<string>         | Obtains the component text.                                |
1003| 5    | getId():Promise<number>           | Obtains the component ID.                                  |
1004| 6    | getType():Promise<string>         | Obtains the component type.                                |
1005| 7    | isEnabled():Promise<bool>         | Obtains the component state, which can be enabled or disabled.                            |
1006
1007For details about the APIs of `UiComponent`, see [@ohos.uitest.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.UiTest.d.ts) and [UiComponent](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-uitest.md#uicomponent).
1008
1009Example 1: Click a component.
1010
1011```javascript
1012let button = await driver.findComponent(BY.id(Id_button))
1013await button.click()
1014```
1015
1016Example 2: After obtaining component attributes, use **assert()** to make assertion.
1017
1018```javascript
1019let component = await driver.findComponent(BY.id(Id_title))
1020expect(component !== null).assertTrue()
1021```
1022
1023Example 3: Scroll on the **List** component to locate the child component with text `Item3_3`.
1024
1025```javascript
1026let list = await driver.findComponent(BY.id(Id_list))
1027let found = await list.scrollSearch(BY.text("Item3_3"))
1028expect(found).assertTrue()
1029```
1030
1031Example 4: Input text in a text box.
1032
1033```javascript
1034let editText = await driver.findComponent(BY.type('InputText'))
1035await editText.inputText("user_name")
1036```
1037### Using UiWindow
1038
1039The `UiWindow` class represents a UI window, which can be located by using `UiDriver.findWindow(by)`. You can use the instance provided by this class to obtain window attributes, drag a window, and adjust the window size.
1040
1041`UiWindow` provides the following APIs:
1042
1043| No.  | API                                                          | Description                                          |
1044| ---- | ------------------------------------------------------------ | -------------------------------------------------- |
1045| 1    | getBundleName(): Promise<string>                             | Obtains the bundle name of the window.                            |
1046| 2    | getTitle(): Promise<string>                                  | Obtains the window title.                                |
1047| 3    | focus(): Promise<bool>                                       | Gives focus to the current window.                            |
1048| 4    | moveTo(x: number, y: number): Promise<bool>;                 | Moves the current window to the specified position. This API is applicable to the windows that can be moved.|
1049| 5    | resize(wide: number, height: number, direction: ResizeDirection): Promise<bool> | Adjusts the window size. This API is applicable to the windows that can be resized.        |
1050| 6    | split(): Promise<bool>                                       | Splits the current window. This API is applicable to the windows that support split-screen mode.  |
1051| 7    | close(): Promise<bool>                                       | Closes the current window.                                    |
1052
1053For details about the APIs of `UiWindow`, see [@ohos.uitest.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.UiTest.d.ts) and [UiWindow](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-uitest.md#uiwindow9).
1054
1055Example 1: Obtain the window attributes.
1056
1057```javascript
1058let window = await driver.findWindow({actived: true})
1059let bundelName = await window.getBundleName()
1060```
1061
1062Example 2: Move the window.
1063
1064```javascript
1065let window = await driver.findWindow({actived: true})
1066await window.moveTo(500,500)
1067```
1068
1069Example 3: Close the window.
1070
1071```javascript
1072let window = await driver.findWindow({actived: true})
1073await window.close()
1074```
1075
1076### How to Use
1077
1078  Download Deveco Studio, create a test project, and call the APIs provided by UiTest to perform related tests. For details about how to create a test project and execute test scripts, see [OpenHarmony Test Framework](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001267284568).
1079  Run the following command to enable UiTest:
1080
1081>```shell
1082> hdc_std shell param set persist.ace.testmode.enabled 1
1083>```
1084### Building UiTest
1085
1086> UiTest is not built with OpenHarmony 3.1 Release and needs to be manually built.
1087
1088If you want to modify UiTest code and verify the modification, use the following commands.
1089
1090#### Building UiTest
1091
1092```shell
1093./build.sh --product-name rk3568 --build-target uitestkit
1094```
1095#### Sending UiTest
1096
1097```shell
1098hdc_std target mount
1099hdc_std shell mount -o rw,remount /
1100hdc_std file send uitest /system/bin/uitest
1101hdc_std file send libuitest.z.so /system/lib/module/libuitest.z.so
1102hdc_std shell chmod +x /system/bin/uitest
1103```
1104
1105### Version Information
1106
1107| Version | Description                                                  |
1108| :------ | :----------------------------------------------------------- |
1109| 3.2.2.1 | 1. Added the APIs for obtaining and setting the screen orientation and flinging.<br>2. Added the window processing logic for unsupported scenarios. |
1110

README_zh.md

1# 自动化测试框架使用介绍
2
3## 简介
4 OpenHarmony自动化测试框架代码部件仓arkXtest,包含单元测试框架(JsUnit)和Ui测试框架(UiTest)。
5
6 单元测试框架(JsUnit)提供单元测试用例执行能力,提供用例编写基础接口,生成对应报告,用于测试系统或应用接口。
7
8 Ui测试框架(UiTest)通过简洁易用的API提供查找和操作界面控件能力,支持用户开发基于界面操作的自动化测试脚本。
9
10## 目录
11
12```
13arkXtest
14  |-----jsunit  单元测试框架
15  |-----uitest  Ui测试框架
16```
17## 约束限制
18本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
19
20## 单元测试框架功能特性
21
22| No.  | 特性     | 功能说明                                                     |
23| ---- | -------- | ------------------------------------------------------------ |
24| 1    | 基础流程 | 支持编写及异步执行基础用例。                                 |
25| 2    | 断言库   | 判断用例实际期望值与预期值是否相符。                         |
26| 3    | Mock能力 | 支持函数级mock能力,对定义的函数进行mock后修改函数的行为,使其返回指定的值或者执行某种动作。 |
27| 4    | 数据驱动 | 提供数据驱动能力,支持复用同一个测试脚本,使用不同输入数据驱动执行。 |
28| 5    | 专项能力 | 支持测试套与用例筛选、随机执行、压力测试、超时设置、遇错即停模式等。 |
29
30### 使用说明
31
32####  基础流程
33
34测试用例采用业内通用语法,describe代表一个测试套, it代表一条用例。
35
36| No.  | API               | 功能说明                                                     |
37| ---- | ----------------- | ------------------------------------------------------------ |
38| 1    | describe          | 定义一个测试套,支持两个参数:测试套名称和测试套函数。       |
39| 2    | beforeAll         | 在测试套内定义一个预置条件,在所有测试用例开始前执行且仅执行一次,支持一个参数:预置动作函数。 |
40| 3    | beforeEach        | 在测试套内定义一个单元预置条件,在每条测试用例开始前执行,执行次数与it定义的测试用例数一致,支持一个参数:预置动作函数。 |
41| 4    | afterEach         | 在测试套内定义一个单元清理条件,在每条测试用例结束后执行,执行次数与it定义的测试用例数一致,支持一个参数:清理动作函数。 |
42| 5    | afterAll          | 在测试套内定义一个清理条件,在所有测试用例结束后执行且仅执行一次,支持一个参数:清理动作函数。 |
43| 6    | beforeItSpecified | 在测试套内定义一个单元预置条件,仅在指定测试用例开始前执行,支持两个参数:单个用例名称或用例名称数组、预置动作函数。 |
44| 7    | afterItSpecified  | 在测试套内定义一个单元清理条件,仅在指定测试用例结束后执行,支持两个参数:单个用例名称或用例名称数组、清理动作函数 |
45| 8    | it                | 定义一条测试用例,支持三个参数:用例名称,过滤参数和用例函数。 |
46| 9    | expect            | 支持bool类型判断等多种断言方法。                             |
47| 10   | getDescribeName   | 获取当前正在执行测试套的名称                                 |
48| 11   | getItName         | 获取当前正在执行测试用例的名称                               |
49| 12   | getItAttribute    | 获取当前正在执行测试用例的级别、粒度、测试类型               |
50
51示例代码:
52
53```javascript
54 import { describe, it, expect, beforeItSpecified, afterItSpecified, SysTestKit, TestType, Size, Level} from '@ohos/hypium';
55 import demo from '@ohos.bundle'
56 import { BusinessError } from '@ohos.base';
57 export default function abilityTest() {
58  describe('ActsAbilityTest', () => {
59    beforeItSpecified(['String_assertContain_success'], () => {
60      const num:number = 1
61      expect(num).assertEqual(1)
62    })
63    afterItSpecified(['String_assertContain_success'], async (done: Function) => {
64      const str:string = 'abc'
65      setTimeout(()=>{
66        try {
67          expect(str).assertContain('d')
68        } catch (error) {
69          console.error(`error message ${JSON.stringify(error)}`)
70        }
71        done()
72      }, 1000)
73    })
74    it('getCurrentRunningSuiteName', 0, () => {
75        let suiteName: string = SysTestKit.getDescribeName();
76        expect(suiteName).assertEqual('ActsAbilityTest')
77    })
78    it('getCurrentRunningItInfo',TestType.SAFETY | Size.SMALLTEST, () => {
79      let itName: string = SysTestKit.getItName();
80      let itAttr: TestType | Size | Level = SysTestKit.getItAttribute()
81      expect(itName).assertEqual('getCurrentRunningItInfo')
82      expect(itAttr).assertEqual(TestType.SAFETY | Size.SMALLTEST)
83    })
84    it('String_assertContain_success', 0, () => {
85      let a: string = 'abc'
86      let b: string = 'b'
87      expect(a).assertContain(b)
88      expect(a).assertEqual(a)
89    })
90    it('getBundleInfo_0100', 0, async () => {
91      const NAME1 = "com.example.myapplication0009921"
92      await demo.getBundleInfo(NAME1,
93        demo.BundleFlag.GET_BUNDLE_WITH_ABILITIES | demo.BundleFlag.GET_BUNDLE_WITH_REQUESTED_PERMISSION)
94        .then((value: BundleInfo) => {
95          console.info(value.appId)
96        })
97        .catch((err:BusinessError) => {
98          console.info(err.code.toString())
99        })
100    })
101  })
102}
103
104 interface BundleInfo {
105   name: string;
106   appId: string
107 }
108```
109
110同时,@since1.0.6 测试套describe支持嵌套定义 。
111
112约束限制:describe仅支持两层嵌套定义,且内层的describe-“innerDescribe”不支持“数据驱动”、“专项能力”特性。
113
114示例代码:
115
116```javascript
117import { describe, it, expect } from '@ohos/hypium';
118
119export default async function nestedDescribeTest() {
120  describe('outerDescribe', () => {
121    describe('innerDescribe', () => {
122      it('innerIt', 0, () =>{
123        let a: string = 'abc'
124        expect(a).assertEqual(a)
125      })
126    })
127    it('outerIt', 0, () => {
128      let a: string = 'abc'
129      expect(a).assertEqual(a)
130    })
131  })
132}
133```
134
135####  断言库
136
137断言功能列表:
138
139
140| No.  | API                | 功能说明                                                     |
141| :--- | :------------------| ------------------------------------------------------------ |
142| 1    | assertClose        | 检验actualvalue和expectvalue(0)的接近程度是否是expectValue(1)。 |
143| 2    | assertContain      | 检验actualvalue中是否包含expectvalue。                       |
144| 3    | assertEqual        | 检验actualvalue是否等于expectvalue[0]。                      |
145| 4    | assertFail         | 抛出一个错误。                                               |
146| 5    | assertFalse        | 检验actualvalue是否是false。                                 |
147| 6    | assertTrue         | 检验actualvalue是否是true。                                  |
148| 7    | assertInstanceOf   | 检验actualvalue是否是expectvalue类型,支持基础类型。                |
149| 8    | assertLarger       | 检验actualvalue是否大于expectvalue。                         |
150| 9    | assertLess         | 检验actualvalue是否小于expectvalue。                         |
151| 10   | assertNull         | 检验actualvalue是否是null。                                  |
152| 11   | assertThrowError   | 检验actualvalue抛出Error内容是否是expectValue。              |
153| 12   | assertUndefined    | 检验actualvalue是否是undefined。                             |
154| 13   | assertNaN          | @since1.0.4 检验actualvalue是否是一个NAN                     |
155| 14   | assertNegUnlimited | @since1.0.4 检验actualvalue是否等于Number.NEGATIVE_INFINITY |
156| 15   | assertPosUnlimited | @since1.0.4 检验actualvalue是否等于Number.POSITIVE_INFINITY |
157| 16   | assertDeepEquals   | @since1.0.4 检验actualvalue和expectvalue是否完全相等   |
158| 17   | assertPromiseIsPending | @since1.0.4 判断promise是否处于Pending状态。             |
159| 18   | assertPromiseIsRejected | @since1.0.4 判断promise是否处于Rejected状态。           |
160| 19   | assertPromiseIsRejectedWith | @since1.0.4 判断promise是否处于Rejected状态,并且比较执行的结果值。 |
161| 20   | assertPromiseIsRejectedWithError | @since1.0.4 判断promise是否处于Rejected状态并有异常,同时比较异常的类型和message值。       |
162| 21   | assertPromiseIsResolved | @since1.0.4 判断promise是否处于Resolved状态。           |
163| 22   | assertPromiseIsResolvedWith | @since1.0.4 判断promise是否处于Resolved状态,并且比较执行的结果值。 |
164| 23   | not                | @since1.0.4 断言取反,支持上面所有的断言功能                     |
165
166示例代码:
167
168```javascript
169import { describe, it, expect } from '@ohos/hypium';
170export default function abilityTest() {
171  describe('ActsAbilityTest', () => {
172    it('assertBeClose_success', 0, () => {
173      let a:number = 100
174      let b:number = 0.1
175      expect(a).assertClose(99, b)
176    })
177    it('assertInstanceOf_success', 0, () => {
178      let a: string = 'strTest'
179      expect(a).assertInstanceOf('String')
180    })
181    it('assertNaN_success',0, () => {
182      expect(Number.NaN).assertNaN(); // true
183    })
184    it('assertNegUnlimited_success',0, () => {
185      expect(Number.NEGATIVE_INFINITY).assertNegUnlimited(); // true
186    })
187    it('assertPosUnlimited_success',0, () => {
188      expect(Number.POSITIVE_INFINITY).assertPosUnlimited(); // true
189    })
190    it('not_number_true',0, () => {
191      expect(1).not().assertLargerOrEqual(2)
192    })
193    it('not_number_true_1',0,() => {
194      expect(3).not().assertLessOrEqual(2);
195    })
196    it('not_NaN_true',0, () => {
197      expect(3).not().assertNaN();
198    })
199    it('not_contain_true',0,() => {
200      let a: string = "abc";
201      let b: string = "cdf"
202      expect(a).not().assertContain(b);
203    })
204    it('not_large_true',0, () => {
205      expect(3).not().assertLarger(4);
206    })
207    it('not_less_true',0, () => {
208      expect(3).not().assertLess(2);
209    })
210    it('not_undefined_true',0, () => {
211      expect(3).not().assertUndefined();
212    })
213    it('deepEquals_null_true',0, () => {
214      // Defines a variety of assertion methods, which are used to declare expected boolean conditions.
215      expect(null).assertDeepEquals(null)
216    })
217    it('deepEquals_array_not_have_true',0, () => {
218      // Defines a variety of assertion methods, which are used to declare expected boolean conditions.
219      const a: Array<number>= []
220      const b: Array<number> = []
221      expect(a).assertDeepEquals(b)
222    })
223    it('deepEquals_map_equal_length_success',0, () => {
224      // Defines a variety of assertion methods, which are used to declare expected boolean conditions.
225      const a: Map<number, number> =  new Map();
226      const b: Map<number, number> =  new Map();
227      a.set(1,100);
228      a.set(2,200);
229      b.set(1, 100);
230      b.set(2, 200);
231      expect(a).assertDeepEquals(b)
232    })
233    it("deepEquals_obj_success_1", 0, () => {
234      const a: SampleTest = {x:1};
235    const b: SampleTest = {x:1};
236  expect(a).assertDeepEquals(b);
237})
238it("deepEquals_regExp_success_0", 0, () => {
239      const a: RegExp = new RegExp("/test/");
240      const b: RegExp = new RegExp("/test/");
241      expect(a).assertDeepEquals(b)
242    })
243it('test_isPending_pass_1', 0, () => {
244      let p: Promise = new Promise<void>(() =>{
245      });
246      expect(p).assertPromiseIsPending();
247    });
248it('test_isRejected_pass_1', 0, () => {
249  let info: PromiseInfo = {
250  res:"no"
251}
252let p: Promise = Promise.reject(info);
253expect(p).assertPromiseIsRejected();
254});
255it('test_isRejectedWith_pass_1', 0, () => {
256  let info: PromiseInfo = {
257  res:"reject value"
258}
259let p: Promise = Promise.reject(info);
260expect(p).assertPromiseIsRejectedWith(info);
261});
262it('test_isRejectedWithError_pass_1', 0, () => {
263  let p1: Promise = Promise.reject(new TypeError('number'));
264  expect(p1).assertPromiseIsRejectedWithError(TypeError);
265});
266it('test_isResolved_pass_1', 0, () => {
267  let info: PromiseInfo = {
268  res:"result value"
269}
270let p: Promise = Promise.resolve(info);
271expect(p).assertPromiseIsResolved();
272});
273it('test_isResolvedTo_pass_1', 0, () => {
274  let info: PromiseInfo = {
275  res:"result value"
276}
277let p: Promise = Promise.resolve(info);
278expect(p).assertPromiseIsResolvedWith(info);
279});
280})
281}
282interface SampleTest {
283  x: number;
284}
285interface PromiseInfo {
286  res: string
287}
288```
289
290
291#### Mock能力
292
293##### 约束限制
294
295单元测试框架Mock能力从npm包[1.0.1版本](https://repo.harmonyos.com/#/cn/application/atomService/@ohos%2Fhypium)开始支持,需修改源码工程中package.info中配置依赖npm包版本号后使用。
296
297-  **接口列表:**
298
299| No. | API | 功能说明 |
300| --- | --- | --- |
301| 1 | mockFunc(obj: object, f:function()) | mock某个类的对象obj的函数f,那么需要传两个参数:obj和f,支持使用异步函数(说明:对mock而言原函数实现是同步或异步没太多区别,因为mock并不关注原函数的实现)。 |
302| 2 | when(mockedfunc:function) | 对传入后方法做检查,检查是否被mock并标记过,返回的是一个方法声明。 |
303| 3 | afterReturn(x:value) | 设定预期返回一个自定义的值value,比如某个字符串或者一个promise。 |
304| 4 | afterReturnNothing() | 设定预期没有返回值,即 undefined。 |
305| 5 | afterAction(x:action) | 设定预期返回一个函数执行的操作。 |
306| 6 | afterThrow(x:msg) | 设定预期抛出异常,并指定异常msg。 |
307| 7 | clear() | 用例执行完毕后,进行数据mocker对象的还原处理(还原之后对象恢复被mock之前的功能)。 |
308| 8 | any | 设定用户传任何类型参数(undefined和null除外),执行的结果都是预期的值,使用ArgumentMatchers.any方式调用。 |
309| 9 | anyString | 设定用户传任何字符串参数,执行的结果都是预期的值,使用ArgumentMatchers.anyString方式调用。 |
310| 10 | anyBoolean | 设定用户传任何boolean类型参数,执行的结果都是预期的值,使用ArgumentMatchers.anyBoolean方式调用。 |
311| 11 | anyFunction | 设定用户传任何function类型参数,执行的结果都是预期的值,使用ArgumentMatchers.anyFunction方式调用。 |
312| 12 | anyNumber | 设定用户传任何数字类型参数,执行的结果都是预期的值,使用ArgumentMatchers.anyNumber方式调用。 |
313| 13 | anyObj | 设定用户传任何对象类型参数,执行的结果都是预期的值,使用ArgumentMatchers.anyObj方式调用。 |
314| 14 | matchRegexs(Regex) | 设定用户传任何正则表达式类型参数Regex,执行的结果都是预期的值,使用ArgumentMatchers.matchRegexs(Regex)方式调用。 |
315| 15 | verify(methodName, argsArray) | 验证methodName(函数名字符串)所对应的函数和其参数列表argsArray的执行行为是否符合预期,返回一个VerificationMode:一个提供验证模式的类,它有times(count)、once()、atLeast(x)、atMost(x)、never()等函数可供选择。 |
316| 16 | times(count) | 验证行为调用过count次。 |
317| 17 | once() | 验证行为调用过一次。 |
318| 18 | atLeast(count) | 验证行为至少调用过count次。 |
319| 19 | atMost(count) | 验证行为至多调用过count次。 |
320| 20 | never | 验证行为从未发生过。 |
321| 21 | ignoreMock(obj, method) | 使用ignoreMock可以还原obj对象中被mock后的函数,对被mock后的函数有效。 |
322| 22 | clearAll() | 用例执行完毕后,进行数据和内存清理。 |
323
324-  **使用示例:**
325
326用户可以通过以下方式进行引入mock模块进行测试用例编写:
327
328- **须知:**
329使用时候必须引入的mock能力模块: MockKit,when
330根据自己用例需要引入断言能力api
331例如:`import { describe, expect, it, MockKit, when} from '@ohos/hypium'`
332
333**示例1:afterReturn 的使用**
334
335```javascript
336import {describe, expect, it, MockKit, when} from '@ohos/hypium';
337
338export default function ActsAbilityTest() {
339  describe('ActsAbilityTest', () => {
340    it('testMockfunc', 0, () => {
341      console.info("it1 begin");
342
343      //1.创建一个mock能力的对象MockKit
344      let mocker: MockKit = new MockKit();
345
346      //2.定类ClassName,里面两个函数,然后创建一个对象claser
347      class ClassName {
348        constructor() {
349        }
350
351        method_1(arg: string) {
352          return '888888';
353        }
354
355        method_2(arg: string) {
356          return '999999';
357        }
358}
359
360let claser: ClassName = new ClassName();
361
362//3.进行mock操作,比如需要对ClassName类的method_1函数进行mock
363let mockfunc: Function = mocker.mockFunc(claser, claser.method_1);
364when(mockfunc)('test').afterReturn('1');
365
366//4.对mock后的函数进行断言,看是否符合预期
367//执行成功案例,参数为'test'
368expect(claser.method_1('test')).assertEqual('1'); //执行通过
369
370//执行失败案例,参数为 'abc'
371//expect(claser.method_1('abc')).assertEqual('1');//执行失败
372});
373});
374}
375```
376- **须知:**
377`when(mockfunc)('test').afterReturn('1');`
378这句代码中的`('test')`是mock后的函数需要传递的匹配参数,目前支持一个参数
379`afterReturn('1')`是用户需要预期返回的结果。
380有且只有在参数是`('test')`的时候,执行的结果才是用户自定义的预期结果。
381
382**示例2: afterReturnNothing 的使用**
383
384```javascript
385import {describe, expect, it, MockKit, when} from '@ohos/hypium';
386
387export default function ActsAbilityTest() {
388  describe('ActsAbilityTest', () => {
389    it('testMockfunc', 0, () => {
390      console.info("it1 begin");
391
392      //1.创建一个mock能力的对象MockKit
393      let mocker: MockKit = new MockKit();
394
395      //2.定类ClassName,里面两个函数,然后创建一个对象claser
396      class ClassName {
397        constructor() {
398        }
399
400        method_1(arg: string) {
401          return '888888';
402        }
403
404        method_2(arg: string) {
405          return '999999';
406        }
407}
408
409let claser: ClassName = new ClassName();
410
411//3.进行mock操作,比如需要对ClassName类的method_1函数进行mock
412let mockfunc: Function = mocker.mockFunc(claser, claser.method_1);
413
414//4.根据自己需求进行选择 执行完毕后的动作,比如这里选择afterReturnNothing();即不返回任何值
415when(mockfunc)('test').afterReturnNothing();
416
417//5.对mock后的函数进行断言,看是否符合预期,注意选择跟第4步中对应的断言方法
418//执行成功案例,参数为'test',这时候执行原对象claser.method_1的方法,会发生变化
419// 这时候执行的claser.method_1不会再返回'888888',而是设定的afterReturnNothing()生效//不返回任何值;
420expect(claser.method_1('test')).assertUndefined(); //执行通过
421
422// 执行失败案例,参数传为 123
423// expect(method_1(123)).assertUndefined();//执行失败
424});
425});
426}
427```
428
429**示例3: 设定参数类型为any ,即接受任何参数(undefine和null除外)的使用**
430
431
432- **须知:**
433需要引入ArgumentMatchers类,即参数匹配器,例如:ArgumentMatchers.any
434
435```javascript
436import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
437
438export default function ActsAbilityTest() {
439  describe('ActsAbilityTest', () => {
440    it('testMockfunc', 0, () => {
441      console.info("it1 begin");
442
443      //1.创建一个mock能力的对象MockKit
444      let mocker: MockKit = new MockKit();
445
446      //2.定类ClassName,里面两个函数,然后创建一个对象claser
447      class ClassName {
448        constructor() {
449        }
450
451        method_1(arg: string) {
452          return '888888';
453        }
454
455        method_2(arg: string) {
456          return '999999';
457        }
458}
459
460let claser: ClassName = new ClassName();
461
462//3.进行mock操作,比如需要对ClassName类的method_1函数进行mock
463let mockfunc: Function = mocker.mockFunc(claser, claser.method_1);
464//根据自己需求进行选择参数匹配器和预期方法,
465when(mockfunc)(ArgumentMatchers.any).afterReturn('1');
466
467//4.对mock后的函数进行断言,看是否符合预期,注意选择跟第4步中对应的断言方法
468//执行成功的案例1,传参为字符串类型
469expect(claser.method_1('test')).assertEqual('1'); //用例执行通过。
470//执行成功的案例2,传参为数字类型123
471expect(claser.method_1("123")).assertEqual('1');//用例执行通过。
472//执行成功的案例3,传参为boolean类型true
473expect(claser.method_1("true")).assertEqual('1');//用例执行通过。
474
475//执行失败的案例,传参为数字类型空
476//expect(claser.method_1()).assertEqual('1');//用例执行失败。
477});
478});
479}
480```
481
482**示例4: 设定参数类型ArgumentMatchers的使用**
483
484```javascript
485import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
486
487export default function ActsAbilityTest() {
488  describe('ActsAbilityTest', () => {
489    it('testMockfunc', 0, () => {
490      console.info("it1 begin");
491
492      //1.创建一个mock能力的对象MockKit
493      let mocker: MockKit = new MockKit();
494
495      //2.定类ClassName,里面两个函数,然后创建一个对象claser
496      class ClassName {
497        constructor() {
498        }
499
500        method_1(arg: string) {
501          return '888888';
502        }
503
504        method_2(arg: string) {
505          return '999999';
506        }
507}
508
509let claser: ClassName = new ClassName();
510
511//3.进行mock操作,比如需要对ClassName类的method_1函数进行mock
512let mockfunc: Function = mocker.mockFunc(claser, claser.method_1);
513//根据自己需求进行选择
514when(mockfunc)(ArgumentMatchers.anyString).afterReturn('1');
515
516//4.对mock后的函数进行断言,看是否符合预期,注意选择跟第4步中对应的断言方法
517//执行成功的案例,传参为字符串类型
518expect(claser.method_1('test')).assertEqual('1'); //用例执行通过。
519expect(claser.method_1('abc')).assertEqual('1'); //用例执行通过。
520
521//执行失败的案例,传参为数字类型
522//expect(claser.method_1(123)).assertEqual('1');//用例执行失败。
523//expect(claser.method_1(true)).assertEqual('1');//用例执行失败。
524});
525});
526}
527```
528
529**示例5: 设定参数类型为matchRegexs(Regex)等 的使用**
530```javascript
531import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
532
533export default function ActsAbilityTest() {
534  describe('ActsAbilityTest',  () => {
535    it('testMockfunc', 0, () => {
536      console.info("it1 begin");
537
538      //1.创建一个mock能力的对象MockKit
539      let mocker: MockKit = new MockKit();
540
541      //2.定类ClassName,里面两个函数,然后创建一个对象claser
542      class ClassName {
543        constructor() {
544        }
545
546        method_1(arg: string) {
547          return '888888';
548        }
549
550        method_2(arg: string) {
551          return '999999';
552        }
553}
554
555let claser: ClassName = new ClassName();
556
557//3.进行mock操作,比如需要对ClassName类的method_1函数进行mock
558let mockfunc: Function = mocker.mockFunc(claser, claser.method_1);
559//根据自己需求进行选择
560when(mockfunc)(ArgumentMatchers.anyString).afterReturn('1');
561
562//4.对mock后的函数进行断言,看是否符合预期,注意选择跟第4步中对应的断言方法
563//执行成功的案例,传参为字符串类型
564expect(claser.method_1('test')).assertEqual('1'); //用例执行通过。
565expect(claser.method_1('abc')).assertEqual('1'); //用例执行通过。
566
567//执行失败的案例,传参为数字类型
568//expect(claser.method_1(123)).assertEqual('1');//用例执行失败。
569//expect(claser.method_1(true)).assertEqual('1');//用例执行失败。
570});
571});
572}
573```
574
575**示例6: 验证功能 Verify函数的使用**
576```javascript
577 import {describe, expect, it, MockKit, when} from '@ohos/hypium';
578
579 export default function ActsAbilityTest() {
580  describe('ActsAbilityTest',  () => {
581    it('testMockfunc', 0, () => {
582      console.info("it1 begin");
583
584      //1.创建一个mock能力的对象MockKit
585      let mocker: MockKit = new MockKit();
586
587      //2.定类ClassName,里面两个函数,然后创建一个对象claser
588      class ClassName {
589        constructor() {
590        }
591
592        method_1(...arg: string[]) {
593          return '888888';
594        }
595
596        method_2(...arg: string[]) {
597          return '999999';
598        }
599 }
600
601 let claser: ClassName = new ClassName();
602
603 //3.进行mock操作,比如需要对ClassName类的method_1和method_2两个函数进行mock
604 mocker.mockFunc(claser, claser.method_1);
605 mocker.mockFunc(claser, claser.method_2);
606
607 //4.方法调用如下
608 claser.method_1('abc', 'ppp');
609 claser.method_1('abc');
610 claser.method_1('xyz');
611 claser.method_1();
612 claser.method_1('abc', 'xxx', 'yyy');
613 claser.method_1();
614 claser.method_2('111');
615 claser.method_2('111', '222');
616
617 //5.现在对mock后的两个函数进行验证,验证调用情况
618 mocker.verify('method_1', []).atLeast(3); //结果为failed
619 //解释:验证函数'method_1',参数列表为空:[] 的函数,至少执行过3次,
620 //执行结果为failed,因为'method_1'且无参数 在4中只执行过2次
621 //mocker.verify('method_2',['111']).once();//执行success,原因同上
622 //mocker.verify('method_2',['111',,'222']).once();//执行success,原因同上
623 });
624 });
625 }
626```
627
628**示例7:  ignoreMock(obj, method) 忽略函数的使用**
629```javascript
630 import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
631
632 export default function ActsAbilityTest() {
633  describe('ActsAbilityTest', () => {
634    it('testMockfunc', 0, () => {
635      console.info("it1 begin");
636
637      //1.创建一个mock能力的对象MockKit
638      let mocker:MockKit = new MockKit();
639
640      //2.定类ClassName,里面两个函数,然后创建一个对象claser
641      class ClassName {
642        constructor() {
643        }
644
645        method_1(...arg: number[]) {
646          return '888888';
647        }
648
649        method_2(...arg: number[]) {
650          return '999999';
651        }
652 }
653
654 let claser: ClassName = new ClassName();
655
656 //3.进行mock操作,比如需要对ClassName类的method_1和method_2两个函数进行mock
657 let func_1: Function = mocker.mockFunc(claser, claser.method_1);
658 let func_2: Function = mocker.mockFunc(claser, claser.method_2);
659
660 //4.对mock后的函数的行为进行修改
661 when(func_1)(ArgumentMatchers.anyNumber).afterReturn('4');
662 when(func_2)(ArgumentMatchers.anyNumber).afterReturn('5');
663
664 //5.方法调用如下
665 console.log(claser.method_1(123)); //执行结果是4,符合步骤4中的预期
666 console.log(claser.method_2(456)); //执行结果是5,符合步骤4中的预期
667
668 //6.现在对mock后的两个函数的其中一个函数method_1进行忽略处理(原理是就是还原)
669 mocker.ignoreMock(claser, claser.method_1);
670 //然后再去调用 claser.method_1函数,看执行结果
671 console.log(claser.method_1(123)); //执行结果是888888,发现这时结果跟步骤4中的预期不一样了,执行了claser.method_1没被mock之前的结果
672 //用断言测试
673 expect(claser.method_1(123)).assertEqual('4'); //结果为failed 符合ignoreMock预期
674 claser.method_2(456); //执行结果是5,因为method_2没有执行ignore忽略,所有也符合步骤4中的预期
675 });
676 });
677 }
678```
679
680**示例8:  clear()函数的使用**
681
682```javascript
683 import {describe, expect, it, MockKit, when, ArgumentMatchers} from '@ohos/hypium';
684
685 export default function ActsAbilityTest() {
686  describe('ActsAbilityTest', () => {
687    it('testMockfunc', 0, () => {
688      console.info("it1 begin");
689
690      //1.创建一个mock能力的对象MockKit
691      let mocker: MockKit = new MockKit();
692
693      //2.定类ClassName,里面两个函数,然后创建一个对象claser
694      class ClassName {
695        constructor() {
696        }
697
698        method_1(...arg: number[]) {
699          return '888888';
700        }
701
702        method_2(...arg: number[]) {
703          return '999999';
704        }
705 }
706
707 let claser: ClassName = new ClassName();
708
709 //3.进行mock操作,比如需要对ClassName类的method_1和method_2两个函数进行mock
710 let func_1: Function = mocker.mockFunc(claser, claser.method_1);
711 let func_2: Function = mocker.mockFunc(claser, claser.method_2);
712
713 //4.对mock后的函数的行为进行修改
714 when(func_1)(ArgumentMatchers.anyNumber).afterReturn('4');
715 when(func_2)(ArgumentMatchers.anyNumber).afterReturn('5');
716
717 //5.方法调用如下
718 console.log(claser.method_1(123)); //执行结果是4,符合步骤4中的预期
719 console.log(claser.method_2(456)); //执行结果是5,符合步骤4中的预期
720
721 //6.现在对mock后的两个函数的其中一个函数method_1进行忽略处理(原理是就是还原)
722 mocker.ignoreMock(claser, claser.method_1);
723 //然后再去调用 claser.method_1函数,看执行结果
724 console.log(claser.method_1(123)); //执行结果是888888,发现这时结果跟步骤4中的预期不一样了,执行了claser.method_1没被mock之前的结果
725 //用断言测试
726 expect(claser.method_1(123)).assertEqual('4'); //结果为failed 符合ignoreMock预期
727 claser.method_2(456); //执行结果是5,因为method_2没有执行ignore忽略,所有也符合步骤4中的预期
728 });
729 });
730 }
731```
732
733
734**示例9:  afterThrow(msg) 函数的使用**
735
736```javascript
737import {describe, expect, it, MockKit, when} from '@ohos/hypium';
738
739export default function ActsAbilityTest() {
740  describe('ActsAbilityTest',  () => {
741    it('testMockfunc', 0, () => {
742      console.info("it1 begin");
743
744      //1.创建一个mock能力的对象MockKit
745      let mocker: MockKit = new MockKit();
746
747      //2.定类ClassName,里面两个函数,然后创建一个对象claser
748      class ClassName {
749        constructor() {
750        }
751
752        method_1(arg: string) {
753          return '888888';
754        }
755}
756
757let claser: ClassName = new ClassName();
758
759//3.进行mock操作,比如需要对ClassName类的method_1函数进行mock
760let mockfunc: Function = mocker.mockFunc(claser, claser.method_1);
761
762//4.根据自己需求进行选择 执行完毕后的动作,比如这里选择afterReturnNothing();即不返回任何值
763when(mockfunc)('test').afterThrow('error xxx');
764
765//5.执行mock后的函数,捕捉异常并使用assertEqual对比msg否符合预期
766try {
767  claser.method_1('test');
768} catch (e) {
769  expect(e).assertEqual('error xxx');//执行通过
770}
771});
772});
773}
774```
775
776**示例10:  mock异步 函数的使用**
777
778```javascript
779import {describe, expect, it, MockKit, when} from '@ohos/hypium';
780
781export default function ActsAbilityTest() {
782  describe('ActsAbilityTest',  () => {
783    it('testMockfunc', 0, () => {
784      console.info("it1 begin");
785
786      //1.创建一个mock能力的对象MockKit
787      let mocker: MockKit = new MockKit();
788
789      //2.定类ClassName,里面两个函数,然后创建一个对象claser
790      class ClassName {
791        constructor() {
792        }
793
794        async method_1(arg: string) {
795          return new Promise<string>((res: Function, rej: Function) => {
796            //做一些异步操作
797            setTimeout(() => {
798              console.log('执行');
799              res('数据传递');
800            }, 2000);
801          });
802        }
803}
804
805let claser: ClassName = new ClassName();
806
807//3.进行mock操作,比如需要对ClassName类的method_1函数进行mock
808let mockfunc: Function = mocker.mockFunc(claser, claser.method_1);
809
810//4.根据自己需求进行选择 执行完毕后的动作,比如这里选择afterRetrun; 可以自定义返回一个promise
811when(mockfunc)('test').afterReturn(new Promise<string>((res: Function, rej: Function) => {
812  console.log("do something");
813  res('success something');
814}));
815
816//5.执行mock后的函数,即对定义的promise进行后续执行
817claser.method_1('test').then((data: string) => {
818  //数据处理代码...
819  console.log('result : ' + data);
820});
821});
822});
823}
824```
825
826**示例11:mock 系统函数的使用**
827
828```javascript
829import {describe, expect, it, MockKit, when} from '@ohos/hypium';
830import app from '@system.app';
831export default function ActsAbilityTest() {
832  describe('ActsAbilityTest',  () => {
833    it('testMockfunc', 0, () => {
834      console.info("it1 begin");
835
836      //1.创建一个mock能力的对象MockKit
837      let mocker: MockKit = new MockKit();
838      let mockf: Function = mocker.mockFunc(app, app.getInfo);
839      when(mockf)().afterReturn('1');
840      //执行成功案例
841      expect(app.getInfo()).assertEqual('1');
842    });
843  });
844}
845```
846
847
848**示例12:verify times函数的使用(验证函数调用次数)**
849
850```javascript
851 import { describe, expect, it, MockKit, when } from '@ohos/hypium'
852
853 export default function ActsAbilityTest() {
854  describe('ActsAbilityTest', () => {
855    it('test_verify_times', 0, () => {
856      //1.创建MockKit对象
857      let mocker: MockKit = new MockKit();
858      //2.定义需要被mock的类
859      class ClassName {
860        constructor() {
861        }
862
863        method_1(...arg: string[]) {
864          return '888888';
865        }
866}
867 //3.创建类对象
868 let claser: ClassName = new ClassName();
869 //4.mock 类ClassName对象的某个方法,比如method_1
870 let func_1: Function = mocker.mockFunc(claser, claser.method_1);
871 //5.期望被mock后的函数能够返回自己假设的结果
872 when(func_1)('123').afterReturn('4');
873
874 //6.随机执行几次函数,参数如下
875 claser.method_1('123', 'ppp');
876 claser.method_1('abc');
877 claser.method_1('xyz');
878 claser.method_1();
879 claser.method_1('abc', 'xxx', 'yyy');
880 claser.method_1('abc');
881 claser.method_1();
882 //7.验证函数method_1且参数为'abc'时,执行过的次数是否为2
883 mocker.verify('method_1', ['abc']).times(2);
884 });
885 });
886 }
887```
888
889
890**示例13:  verify atLeast 函数的使用 (验证函数调用次数)**
891
892```javascript
893import { describe, expect, it, MockKit, when } from '@ohos/hypium'
894
895export default function ActsAbilityTest() {
896  describe('ActsAbilityTest', () => {
897    it('test_verify_atLeast', 0, () => {
898      //1.创建MockKit对象
899      let mocker: MockKit = new MockKit();
900      //2.定义需要被mock的类
901      class ClassName {
902        constructor() {
903        }
904
905        method_1(...arg: string[]) {
906          return '888888';
907        }
908}
909
910//3.创建类对象
911let claser: ClassName = new ClassName();
912//4.mock  类ClassName对象的某个方法,比如method_1
913let func_1: Function = mocker.mockFunc(claser, claser.method_1);
914//5.期望被mock后的函数能够返回自己假设的结果
915when(func_1)('123').afterReturn('4');
916//6.随机执行几次函数,参数如下
917claser.method_1('123', 'ppp');
918claser.method_1('abc');
919claser.method_1('xyz');
920claser.method_1();
921claser.method_1('abc', 'xxx', 'yyy');
922claser.method_1();
923//7.验证函数method_1且参数为空时,是否至少执行过2次
924mocker.verify('method_1', []).atLeast(2);
925});
926});
927}
928```
929
930#### 数据驱动
931
932##### 约束限制
933
934单元测试框架数据驱动能力从[hypium 1.0.2版本](https://repo.harmonyos.com/#/cn/application/atomService/@ohos%2Fhypium)开始支持。
935
936- 数据参数传递 : 为指定测试套、测试用例传递测试输入数据参数。
937- 压力测试 : 为指定测试套、测试用例设置执行次数。
938
939数据驱动可以根据配置参数来驱动测试用例的执行次数和每一次传入的参数,使用时依赖data.json配置文件,文件内容如下:
940
941>说明 : data.json与测试用例*.test.js|ets文件同目录
942
943```json
944{
945	"suites": [{
946		"describe": ["actsAbilityTest"],
947		"stress": 2,
948		"params": {
949			"suiteParams1": "suiteParams001",
950			"suiteParams2": "suiteParams002"
951		},
952		"items": [{
953			"it": "testDataDriverAsync",
954			"stress": 2,
955			"params": [{
956				"name": "tom",
957				"value": 5
958			}, {
959				"name": "jerry",
960				"value": 4
961			}]
962		}, {
963			"it": "testDataDriver",
964			"stress": 3
965		}]
966	}]
967}
968```
969
970配置参数说明:
971
972|      | 配置项名称 | 功能                                  | 必填 |
973| :--- | :--------- | :------------------------------------ | ---- |
974| 1    | "suite"    | 测试套配置 。                         | 是   |
975| 2    | "items"    | 测试用例配置 。                       | 是   |
976| 3    | "describe" | 测试套名称 。                         | 是   |
977| 4    | "it"       | 测试用例名称 。                       | 是   |
978| 5    | "params"   | 测试套 / 测试用例 可传入使用的参数 。 | 否   |
979| 6    | "stress"   | 测试套 / 测试用例 指定执行次数 。     | 否   |
980
981示例代码:
982
983在TestAbility目录下app.js|ets文件中导入data.json,并在Hypium.hypiumTest() 方法执行前,设置参数数据
984
985```javascript
986import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
987import { Hypium } from '@ohos/hypium'
988import testsuite from '../test/List.test'
989import data from '../test/data.json';
990
991...
992Hypium.setData(data);
993Hypium.hypiumTest(abilityDelegator, abilityDelegatorArguments, testsuite)
994...
995```
996
997```javascript
998 import {describe, beforeAll, beforeEach, afterEach, afterAll, it, expect} from '@ohos/hypium';
999
1000 export default function abilityTest() {
1001  describe('actsAbilityTest', () => {
1002    it('testDataDriverAsync', 0, async (done: Function, data: ParmObj) => {
1003      console.info('name: ' + data.name);
1004      console.info('value: ' + data.value);
1005      done();
1006    });
1007
1008    it('testDataDriver', 0, () => {
1009      console.info('stress test');
1010    });
1011  });
1012}
1013 interface ParmObj {
1014   name: string,
1015   value: string
1016 }
1017```
1018#### 专项能力
1019
1020该项能力需通过在cmd窗口中输入aa test命令执行触发,并通过设置执行参数触发不同功能。另外,测试应用模型与编译方式不同,对应的aa test命令也不同,具体可参考[自动化测试框架使用指导](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/application-test/arkxtest-guidelines.md#cmd%E6%89%A7%E8%A1%8C)
1021
1022- **筛选能力**
1023
1024  1、按测试用例属性筛选
1025
1026  可以利用hypium提供的Level、Size、TestType 对象,对测试用例进行标记,以区分测试用例的级别、粒度、测试类型,各字段含义及代码如下:
1027
1028  | Key      | 含义说明     | Value取值范围                                                |
1029  | -------- | ------------ | ------------------------------------------------------------ |
1030  | level    | 用例级别     | "0","1","2","3","4", 例如:-s level 1                        |
1031  | size     | 用例粒度     | "small","medium","large", 例如:-s size small                |
1032  | testType | 用例测试类型 | "function","performance","power","reliability","security","global","compatibility","user","standard","safety","resilience", 例如:-s testType function |
1033
1034  示例代码:
1035
1036 ```javascript
1037 import { describe, it, expect, TestType, Size, Level } from '@ohos/hypium';
1038
1039 export default function attributeTest() {
1040  describe('attributeTest', () => {
1041    it("testAttributeIt", TestType.FUNCTION | Size.SMALLTEST | Level.LEVEL0, () => {
1042      console.info('Hello Test');
1043    })
1044  })
1045}
1046 ```
1047
1048  示例命令:
1049
1050  ```shell
1051  hdc shell aa test -b xxx -m xxx -s unittest OpenHarmonyTestRunner -s testType function -s size small -s level 0
1052  ```
1053
1054  该命令作用是筛选测试应用中同时满足,用例测试类型是“function”、用例粒度是“small”、用例级别是“0”的三个条件用例执行。
1055
1056  2、按测试套/测试用例名称筛选
1057
1058  hypium可以通过指定测试套与测试用例名称,来指定特定用例的执行,测试套与用例名称用“#”号连接,多个用“,”英文逗号分隔
1059
1060  | Key      | 含义说明                | Value取值范围                                                |
1061  | -------- | ----------------------- | ------------------------------------------------------------ |
1062  | class    | 指定要执行的测试套&用例 | ${describeName}#${itName},${describeName} , 例如:-s class attributeTest#testAttributeIt |
1063  | notClass | 指定不执行的测试套&用例 | ${describeName}#${itName},${describeName} , 例如:-s notClass attributeTest#testAttribut |
1064
1065  示例代码:
1066
1067  ```javascript
1068  import { describe, it, expect, TestType, Size, Level } from '@ohos/hypium';
1069
1070  export default function attributeTest() {
1071  describe('describeTest_000',  () => {
1072    it("testIt_00", TestType.FUNCTION | Size.SMALLTEST | Level.LEVEL0,  () => {
1073      console.info('Hello Test');
1074    })
1075
1076    it("testIt_01", TestType.FUNCTION | Size.SMALLTEST | Level.LEVEL0, () => {
1077      console.info('Hello Test');
1078    })
1079  })
1080
1081  describe('describeTest_001',  () => {
1082    it("testIt_02", TestType.FUNCTION | Size.SMALLTEST | Level.LEVEL0, () => {
1083      console.info('Hello Test');
1084    })
1085  })
1086}
1087  ```
1088
1089  示例命令1:
1090
1091  ```shell
1092  hdc shell aa test -b xxx -m xxx -s unittest OpenHarmonyTestRunner -s class describeTest_000#testIt_00,describeTest_001
1093  ```
1094
1095  该命令作用是执行“describeTest_001”测试套中所用用例,以及“describeTest_000”测试套中的“testIt_00”用例。
1096
1097  示例命令2:
1098
1099  ```shell
1100  hdc shell aa test -b xxx -m xxx -s unittest OpenHarmonyTestRunner -s notClass describeTest_000#testIt_01
1101  ```
1102
1103  该命令作用是不执行“describeTest_000”测试套中的“testIt_01”用例。
1104
1105- **随机执行**
1106
1107  使测试套与测试用例随机执行,用于稳定性测试。
1108
1109  | Key    | 含义说明                             | Value取值范围                                  |
1110  | ------ | ------------------------------------ | ---------------------------------------------- |
1111  | random | @since1.0.3 测试套、测试用例随机执行 | true, 不传参默认为false, 例如:-s random true |
1112
1113  示例命令:
1114
1115  ```shell
1116  hdc shell aa test -b xxx -m xxx -s unittest OpenHarmonyTestRunner -s dryRun true
1117  ```
1118
1119- **压力测试**
1120
1121  指定要执行用例的执行次数,用于压力测试。
1122
1123  | Key    | 含义说明                             | Value取值范围                  |
1124  | ------ | ------------------------------------ | ------------------------------ |
1125  | stress | @since1.0.5 指定要执行用例的执行次数 | 正整数, 例如: -s stress 1000 |
1126
1127  示例命令:
1128
1129  ```shell
1130  hdc shell aa test -b xxx -m xxx -s unittest OpenHarmonyTestRunner -s stress 1000
1131  ```
1132
1133- **用例超时时间设置**
1134
1135  指定测试用例执行的超时时间,用例实际耗时如果大于超时时间,用例会抛出"timeout"异常,用例结果会显示“excute timeout XXX”
1136
1137  | Key     | 含义说明                   | Value取值范围                                        |
1138  | ------- | -------------------------- | ---------------------------------------------------- |
1139  | timeout | 指定测试用例执行的超时时间 | 正整数(单位ms),默认为 5000,例如: -s timeout 15000 |
1140
1141  示例命令:
1142
1143  ```shell
1144  hdc shell aa test -b xxx -m xxx -s unittest OpenHarmonyTestRunner -s timeout 15000
1145  ```
1146
1147- **遇错即停模式**
1148
1149  | Key          | 含义说明                                                     | Value取值范围                                        |
1150  | ------------ | ------------------------------------------------------------ | ---------------------------------------------------- |
1151  | breakOnError | @since1.0.6 遇错即停模式,当执行用例断言失败或者发生错误时,退出测试执行流程 | true, 不传参默认为false, 例如:-s breakOnError true |
1152
1153  示例命令:
1154
1155  ```shell
1156  hdc shell aa test -b xxx -m xxx -s unittest OpenHarmonyTestRunner -s breakOnError true
1157  ```
1158
1159- **测试套中用例信息输出**
1160
1161  输出测试应用中待执行的测试用例信息
1162
1163  | Key    | 含义说明                     | Value取值范围                                  |
1164  | ------ | ---------------------------- | ---------------------------------------------- |
1165  | dryRun | 显示待执行的测试用例信息全集 | true, 不传参默认为false, 例如:-s dryRun true |
1166
1167  示例命令:
1168
1169  ```shell
1170  hdc shell aa test -b xxx -m xxx -s unittest OpenHarmonyTestRunner -s dryRun true
1171  ```
1172
1173### 使用方式
1174
1175单元测试框架以npm包(hypium)形式发布至[服务组件官网](https://repo.harmonyos.com/#/cn/application/atomService/@ohos%2Fhypium),开发者可以下载Deveco Studio后,在应用工程中配置依赖后使用框架能力,测试工程创建及测试脚本执行使用指南请参见[IDE指导文档](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453)1176
1177## Ui测试框架功能特性
1178
1179| No.  | 特性        | 功能说明                                            |
1180| ---- |-----------|-------------------------------------------------|
1181| 1    | Driver    | Ui测试的入口,提供查找控件,检查控件存在性以及注入按键能力。                 |
1182| 2    | On        | 用于描述目标控件特征(文本、id、类型等),`Driver`根据`On`描述的控件特征信息来查找控件。 |
1183| 3    | Component | Driver查找返回的控件对象,提供查询控件属性,滑动查找等触控和检视能力。          |
1184| 4    | UiWindow  | Driver查找返回的窗口对象,提供获取窗口属性、操作窗口的能力。               |
1185
1186**使用者在测试脚本通过如下方式引入使用:**
1187
1188```typescript
1189import {Driver,ON,Component,Uiwindow,MatchPattern} from '@ohos.UiTest'
1190```
1191
1192> 须知
1193> 1. `On`类提供的接口全部是同步接口,使用者可以使用`builder`模式链式调用其接口构造控件筛选条件。
1194> 2. `Driver`和`Component`类提供的接口全部是异步接口(`Promise`形式),**需使用`await`语法**。
1195> 3. Ui测试用例均需使用**异步**语法编写用例,需遵循单元测试框架异步用例编写规范。
1196
1197
1198
1199在测试用例文件中import `On/Driver/Component`类,然后调用API接口编写测试用例。
1200
1201```javascript
1202 import {describe, beforeAll, beforeEach, afterEach, afterAll, it, expect} from '@ohos/hypium'
1203 import {ON, Driver, Component, MatchPattern} from '@ohos.UiTest'
1204
1205 export default async function abilityTest() {
1206  describe('uiTestDemo', () => {
1207    it('uitest_demo0', 0, async () => {
1208      // create Driver
1209      let driver: Driver = Driver.create()
1210      // find component by text
1211      let button: Component = await driver.findComponent(ON.text('hello').enabled(true))
1212      // click component
1213      await button.click()
1214      // get and assert component text
1215      let content: string = await button.getText()
1216      expect(content).assertEqual('clicked!')
1217    })
1218  })
1219}
1220```
1221
1222### Driver使用说明
1223
1224`Driver`类作为UiTest测试框架的总入口,提供查找控件,注入按键,单击坐标,滑动控件,手势操作,截图等能力。
1225
1226| No.  | API                                                             | 功能描述               |
1227| ---- |-----------------------------------------------------------------| ---------------------- |
1228| 1    | create():Promise<Driver>                                        | 静态方法,构造Driver。 |
1229| 2    | findComponent(on:On):Promise<Component>                         | 查找匹配控件。         |
1230| 3    | pressBack():Promise<void>                                       | 单击BACK键。           |
1231| 4    | click(x:number, y:number):Promise<void>                         | 基于坐标点的单击。      |
1232| 5    | swipe(x1:number, y1:number, x2:number, y2:number):Promise<void> | 基于坐标点的滑动。      |
1233| 6    | assertComponentExist(on:On):Promise<void>                       | 断言匹配的控件存在。     |
1234| 7    | delayMs(t:number):Promise<void>                                 | 延时。                 |
1235| 8    | screenCap(s:path):Promise<void>                                 | 截屏。                 |
1236| 9    | findWindow(filter: WindowFilter): Promise<UiWindow>             | 查找匹配窗口。         |
1237
1238其中assertComponentExist接口是断言API,用于断言当前界面存在目标控件;如果控件不存在,该API将抛出JS异常,使当前测试用例失败。
1239
1240```javascript
1241 import { Driver, ON } from '@ohos.UiTest';
1242 import { describe, it} from '@ohos/hypium';
1243 export default async function abilityTest() {
1244  describe('UiTestDemo', () => {
1245    it('Uitest_demo0', 0, async (done: Function) => {
1246      try{
1247        // create Driver
1248        let driver: Driver = Driver.create()
1249        // assert text 'hello' exists on current Ui
1250        await driver.assertComponentExist(ON.text('hello'))
1251      } finally {
1252        done()
1253      }
1254    })
1255  })
1256}
1257```
1258
1259`Driver`完整的API列表请参考[API文档](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.UiTest.d.ts)及[示例文档说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-uitest.md#driver9)1260
1261### On使用说明
1262
1263Ui测试框架通过`On`类提供了丰富的控件特征描述API,用来匹配查找要操作或检视的目标控件。`On`提供的API能力具有以下特点:
1264
1265- 支持匹配单属性和匹配多属性组合,例如同时指定目标控件text和id。
1266- 控件属性支持多种匹配模式(等于,包含,`STARTS_WITH`,`ENDS_WITH`)。
1267- 支持相对定位控件,可通过`isBefore`和`isAfter`等API限定邻近控件特征进行辅助定位。
1268
1269| No. | API                                | 功能描述                       |
1270|-----|------------------------------------|----------------------------|
1271| 1   | id(i:string):On                    | 指定控件id。                    |
1272| 2   | text(t:string, p?:MatchPattern):On | 指定控件文本,可指定匹配模式。            |
1273| 3   | type(t:string):On                 | 指定控件类型。                    |
1274| 4   | enabled(e:bool):On                 | 指定控件使能状态。                  |
1275| 5   | clickable(c:bool):On               | 指定控件可单击状态。                 |
1276| 6   | longClickable(l:bool):On           | 指定控件可长按状态。                 |
1277| 7   | focused(f:bool):On                 | 指定控件获焦状态。                  |
1278| 8   | scrollable(s:bool):On              | 指定控件可滑动状态。                 |
1279| 9   | selected(s:bool):On                | 指定控件选中状态。                  |
1280| 10  | checked(c:bool):On                 | 指定控件选择状态。                  |
1281| 11  | checkable(c:bool):On               | 指定控件可选择状态。                 |
1282| 12  | isBefore(b:On):On                  | **相对定位**,限定目标控件位于指定特征控件之前。 |
1283| 13  | isAfter(b:On):On                   | **相对定位**,限定目标控件位于指定特征控件之后。 |
1284
1285其中,`text`属性支持{`MatchPattern.EQUALS`,`MatchPattern.CONTAINS`,`MatchPattern.STARTS_WITH`,`MatchPattern.ENDS_WITH`}四种匹配模式,缺省使用`MatchPattern.EQUALS`模式。
1286
1287`On`完整的API列表请参考[API文档](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.UiTest.d.ts)及[示例文档说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-uitest.md#on9)1288
1289#### 控件绝对定位
1290
1291**示例代码1**:查找id是`Id_button`的控件。
1292
1293```javascript
1294let button: Component = await driver.findComponent(ON.id('Id_button'))
1295```
1296
1297 **示例代码2**:查找id是`Id_button`并且状态是`enabled`的控件,适用于无法通过单一属性定位的场景。
1298
1299```javascript
1300let button: Component = await driver.findComponent(ON.id('Id_button').enabled(true))
1301```
1302
1303通过`On.id(x).enabled(y)`来指定目标控件的多个属性。
1304
1305**示例代码3**:查找文本中包含`hello`的控件,适用于不能完全确定控件属性取值的场景。
1306
1307```javascript
1308let txt: Component = await driver.findComponent(ON.text('hello', MatchPattern.CONTAINS))
1309```
1310
1311通过向`On.text()`方法传入第二个参数`MatchPattern.CONTAINS`来指定文本匹配规则;默认规则是`MatchPattern.EQUALS`,即目标控件text属性必须严格等于给定值。
1312
1313####  控件相对定位
1314
1315**示例代码1**:查找位于文本控件`Item3_3`后面的,id是`Id_switch`的Switch控件。
1316
1317```javascript
1318let switch: Component = await driver.findComponent(ON.id('Id_switch').isAfter(ON.text('Item3_3')))
1319```
1320
1321通过`On.isAfter`方法,指定位于目标控件前面的特征控件属性,通过该特征控件进行相对定位。一般地,特征控件是某个具有全局唯一特征的控件(例如具有唯一的id或者唯一的text)。
1322
1323类似的,可以使用`On.isBefore`控件指定位于目标控件后面的特征控件属性,实现相对定位。
1324
1325### Component使用说明
1326
1327`Component`类代表了Ui界面上的一个控件,一般是通过`Driver.findComponent(on)`方法查找到的。通过该类的实例,用户可以获取控件属性,单击控件,滑动查找,注入文本等操作。
1328
1329`Component`包含的常用API:
1330
1331| No. | API                                | 功能描述                       |
1332|-----|------------------------------------|----------------------------|
1333| 1   | click():Promise<void>              | 单击该控件。                     |
1334| 2   | inputText(t:string):Promise<void>  | 向控件中输入文本(适用于文本框控件)。        |
1335| 3   | scrollSearch(s:On):Promise<Component>   | 在该控件上滑动查找目标控件(适用于List等控件)。 |
1336| 4   | scrollToTop(s:number):Promise<void>    | 滑动到该控件顶部(适用于List等控件)。      |
1337| 5   | scrollTobottom(s:number):Promise<void> | 滑动到该控件底部(适用于List等控件)。      |
1338| 6   | getText():Promise<string>          | 获取控件text。                  |
1339| 7   | getId():Promise<number>            | 获取控件id。                    |
1340| 8   | getType():Promise<string>          | 获取控件类型。                    |
1341| 9   | isEnabled():Promise<bool>          | 获取控件使能状态。                  |
1342
1343`Component`完整的API列表请参考[API文档](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.UiTest.d.ts)及[示例文档说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-uitest.md#component9)1344
1345**示例代码1**:单击控件。
1346
1347```javascript
1348let button: Component = await driver.findComponent(ON.id('Id_button'))
1349await button.click()
1350```
1351
1352**示例代码2**:通过get接口获取控件属性后,可以使用单元测试框架提供的assert*接口做断言检查。
1353
1354```javascript
1355let component: Component = await driver.findComponent(ON.id('Id_title'))
1356expect(component !== null).assertTrue()
1357```
1358
1359**示例代码3**:在List控件中滑动查找text是`Item3_3`的子控件。
1360
1361```javascript
1362let list: Component = await driver.findComponent(ON.id('Id_list'))
1363let found: Component = await list.scrollSearch(ON.text('Item3_3'))
1364expect(found).assertTrue()
1365```
1366
1367**示例代码4**:向输入框控件中输入文本。
1368
1369```javascript
1370let editText: Component = await driver.findComponent(ON.type('InputText'))
1371await editText.inputText('user_name')
1372```
1373### UiWindow使用说明
1374
1375`UiWindow`类代表了Ui界面上的一个窗口,一般是通过`Driver.findWindow(WindowFilter)`方法查找到的。通过该类的实例,用户可以获取窗口属性,并进行窗口拖动、调整窗口大小等操作。
1376
1377`UiWindow`包含的常用API:
1378
1379| No.  | API                                                          | 功能描述                                           |
1380| ---- | ------------------------------------------------------------ | -------------------------------------------------- |
1381| 1    | getBundleName(): Promise<string>                             | 获取窗口所属应用包名。                             |
1382| 2    | getTitle(): Promise<string>                                  | 获取窗口标题信息。                                 |
1383| 3    | focus(): Promise<bool>                                       | 使得当前窗口获取焦点。                             |
1384| 4    | moveTo(x: number, y: number): Promise<bool>                  | 将当前窗口移动到指定位置(适用于支持移动的窗口)。 |
1385| 5    | resize(wide: number, height: number, direction: ResizeDirection): Promise<bool> | 调整窗口大小(适用于支持调整大小的窗口)。         |
1386| 6    | split(): Promise<bool>                                       | 将窗口模式切换为分屏模式(适用于支持分屏的窗口)。   |
1387| 7    | close(): Promise<bool>                                       | 关闭当前窗口。                                     |
1388
1389`UiWindow`完整的API列表请参考[API文档](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.UiTest.d.ts)及[示例文档说明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-uitest.md#uiwindow9)1390
1391**示例代码1**:获取窗口属性。
1392
1393```javascript
1394let window: UiWindow = await driver.findWindow({actived: true})
1395let bundelName: string = await window.getBundleName()
1396```
1397
1398**示例代码2**:移动窗口。
1399
1400```javascript
1401let window: UiWindow = await driver.findWindow({actived: true})
1402await window.moveTo(500,500)
1403```
1404
1405**示例代码3**:关闭窗口。
1406
1407```javascript
1408let window: UiWindow = await driver.findWindow({actived: true})
1409await window.close()
1410```
1411
1412### 使用方式
1413
1414  开发者可以下载Deveco Studio创建测试工程后,在其中调用框架提供接口进行相关测试操作,测试工程创建及测试脚本执行使用指南请参见[IDE指导文档](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001267284568)1415  UI测试框架使能需要执行如下命令。
1416
1417>```shell
1418> hdc shell param set persist.ace.testmode.enabled 1
1419>```
1420### UI测试框架自构建方式
1421
1422> Ui测试框架在OpenHarmony-3.1-Release版本中未随版本编译,需手动处理,请参考[3.1-Release版本使用指导](https://gitee.com/openharmony/testfwk_arkxtest/blob/OpenHarmony-3.1-Release/README_zh.md#%E6%8E%A8%E9%80%81ui%E6%B5%8B%E8%AF%95%E6%A1%86%E6%9E%B6%E8%87%B3%E8%AE%BE%E5%A4%87)1423
1424开发者如需自行编译Ui测试框架代码验证子修改内容,构建命令和推送位置请参考本章节内容。
1425
1426#### 构建命令
1427
1428```shell
1429./build.sh --product-name rk3568 --build-target uitestkit
1430```
1431#### 推送位置
1432
1433```shell
1434hdc target mount
1435hdc shell mount -o rw,remount /
1436hdc file send uitest /system/bin/uitest
1437hdc file send libuitest.z.so /system/lib/module/libuitest.z.so
1438hdc shell chmod +x /system/bin/uitest
1439```
1440
1441### 命令行使用说明
1442
1443  开发者可以输入如下命令来实现对应功能。
1444
14451、打印使用帮助
1446
1447```shell
1448hdc shell uitest help
1449```
1450
14512、截屏
1452
1453```
1454hdc shell uitest screenCap
1455// 默认存储路径:/data/local/tmp,文件名:时间戳 + .png。
1456hdc shell uitest screenCap -p /data/local/1.png
1457// 指定存储路径和文件名。
1458```
1459
14603、获取设备当前Ui控件树信息
1461
1462```shell
1463hdc shell uitest dumpLayout
1464// 默认存储路径:/data/local/tmp,文件名:时间戳 + .json。
1465hdc shell uitest screenCap -p /data/local/1.json
1466// 指定存储路径和文件名。
1467```
1468
14694、录制Ui操作
1470
1471```shell
1472hdc shell uitest uiRecord record
1473// 将当前执行的Ui操作记录到/data/local/tmp/layout/record.csv
1474hdc shell uitest uiRecord read
1475// 将记录的Ui操作打印出来
1476```
1477
14785、 shell命令方式注入UI模拟操作
1479> 支持操作类型:点击 双击 长按 慢滑 快滑 拖拽 输入文字 KeyEvent。
1480
1481| 配置参数值       | 配置参数含义                                  | 配置参数有值                                                                                                                                                                                              | 示例                                                                                  |
1482|-------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
1483| click       | 模拟单击操作                                  | point_x (必选参数,点击x坐标点)<br/> point_y (必选参数,点击y坐标点)                                                                                                                                                    | hdc shell uitest uiInput click point_x point_y                                      |
1484| doubleClick | 模拟双击操作                                  | point_x (必选参数,双击x坐标点)<br/> point_y (必选参数,双击y坐标点)                                                                                                                                                    | hdc shell uitest uiInput doubleClick point_x point_y                                |
1485| longClick   | 模拟长按操作                                  | point_x (必选参数,长按x坐标点)<br/> point_y (必选参数,长按y坐标点)                                                                                                                                                    | hdc shell uitest uiInput longClick point_x point_y                                  |
1486| fling       | 模拟快滑操作                                  | from_x (必选参数,滑动起点x坐标)<br/> from_y(必选参数,滑动起点y坐标)<br/> to_x(必选参数,滑动终点x坐标)<br/> to_y(必选参数,滑动终点y坐标)<br/> swipeVelocityPps_ (可选参数,滑动速度,取值范围: 200-40000, 默认值: 600)<br/> stepLength(可选参数,滑动步长,默认值:滑动距离/50) | hdc shell uitest uiInput fling from_x from_y to_x to_y swipeVelocityPps_ stepLength |
1487| swipe       | 模拟慢滑操作                                  | from_x (必选参数,滑动起点x坐标)<br/> from_y(必选参数,滑动起点y坐标)<br/> to_x(必选参数,滑动终点x坐标)<br/> to_y(必选参数,滑动终点y坐标)<br/> swipeVelocityPps_ (可选参数,滑动速度,取值范围: 200-40000, 默认值: 600))                                       | hdc shell uitest uiInput swipe from_x from_y to_x to_y swipeVelocityPps_            |
1488| drag        | 模拟拖拽操作                                  | from_x (必选参数,拖拽起点x坐标)<br/> from_y(必选参数,拖拽起点y坐标)<br/> to_x(必选参数,拖拽终点x坐标)<br/> to_y(必选参数,拖拽终点y坐标)<br/> swipeVelocityPps_ (可选参数,滑动速度,取值范围: 200-40000, 默认值: 600))                                       | hdc shell uitest uiInput drag from_x from_y to_x to_y swipeVelocityPps_             |
1489| dircFling   | 模拟指定方向滑动操作                              | direction (可选参数,滑动方向,可选值: [0,1,2,3], 滑动方向: [左,右,上,下],默认值: 0)<br/> swipeVelocityPps_ (可选参数,滑动速度,取值范围: 200-40000, 默认值: 600)<br/> stepLength(可选参数,滑动步长,默认值:滑动距离/50)                                                                                                                                  | hdc shell uitest uiInput dircFling direction swipeVelocityPps_ stepLength                                       |
1490| inputText        | 模拟输入框输入文本操作                             | point_x (必选参数,输入框x坐标点)<br/> point_y (必选参数,输入框y坐标点)<br/> input(输入文本)                                                                                                                                 | hdc shell uitest uiInput inputText  point_x point_y text                                 |
1491| keyEvent    | 模拟实体按键事件(如:键盘,电源键,返回上一级,返回桌面等),以及组合按键操作 | keyID (必选参数,实体按键对应ID)<br/> keyID2 (可选参数,实体按键对应ID)                                                                                                                                                   | hdc shell uitest uiInput keyEvent keyID                                             |
1492
1493示例代码1:执行点击事件。
1494```shell
1495 hdc shell uitest uiInput click 100 100
1496```
1497示例代码2:执行双击事件。
1498```shell
1499 hdc shell uitest uiInput doubleClick 100 100
1500```
1501示例代码3:执行长按事件。
1502```shell
1503 hdc shell uitest uiInput longClick 100 100
1504```
1505示例代码4:执行快滑操作。
1506```shell
1507hdc shell uitest uiInput fling 0 0 200 200 500
1508```
1509示例代码5:执行慢滑操作。
1510```shell
1511hdc shell uitest uiInput swipe 0 0 200 200 500
1512```
1513示例代码6:执行拖拽操作。
1514```shell
1515hdc shell uitest uiInput drag 0 0 100 100 500
1516```
1517示例代码6:执行向左滑动操作。
1518```shell
1519hdc shell uitest uiInput dircFling 0 500
1520```
1521示例代码7:执行向右滑动操作。
1522```shell
1523hdc shell uitest uiInput dircFling 1 600
1524```
1525示例代码8:执行向上滑动操作。
1526```shell
1527hdc shell uitest uiInput dircFling 2
1528```
1529示例代码9:执行向下滑动操作。
1530```shell
1531hdc shell uitest uiInput dircFling 3
1532```
1533
1534示例代码10:执行输入框输入操作。
1535```shell
1536hdc shell uitest uiInput inputText 100 100 hello
1537```
1538
1539示例代码11:执行返回主页操作。
1540```shell
1541hdc shell uitest uiInput keyEvent home
1542```
1543示例代码12:执行返回上一步操作。
1544```shell
1545hdc shell uitest uiInput keyEvent back
1546```
1547示例代码13:执行组合键复制粘贴操作。
1548```shell
1549hdc shell uitest uiInput keyEvent 2072 2038
1550```
1551
1552### 版本信息
1553
1554| 版本号  | 功能说明                                                     |
1555| :------ | :----------------------------------------------------------- |
1556| 3.2.2.1 | 1、增加抛滑、获取/设置屏幕方向接口<br />2、窗口处理逻辑增加不支持场景处理逻辑 |
1557| 3.2.3.0 | 1、滑动控件进行滑动查找、滑动到尾部/顶部功能优化             |
1558| 3.2.4.0 | 1、接口调用异常时会抛出错误码                                |
1559| 3.2.5.0 | 1、通信机制变更                                              |
1560| 3.2.6.0 | 1、增加模拟鼠标操作能力接口<br />2、增加指定应用的窗口下查找目标控件接口 |
1561| 4.0.1.1 | 1、支持在daemon运行时执行uitest dumpLayout                   |
1562| 4.0.1.2 | 1、模拟鼠标动作、键鼠协同功能优化                            |
1563| 4.0.1.3 | 1、示例代码更新<br />2、滑动控件进行滑动查找、滑动到尾部/顶部功能优化 |
1564| 4.0.1.4 | 1、可选参数传入undefined时,当作默认值处理                   |
1565| 4.0.2.0 | 1、支持监听toast和dialog控件出现,使用callback的形式返回结果。 |
1566| 4.0.3.0 | 1、增加加载运行.abc文件机制。                                |
1567| 4.0.4.0 | 1、支持abc_loader框架获取UI操作录制数据,屏幕数据,控件树等,并以callback的形式返回结果<br />2、修改录制数据结构 |
1568| 4.1.1.1 | 1、对接批量获取控件信息能力,缩短获取控件信息的耗时。        |
1569| 4.1.2.0 | 1、增加shell命令方式注入UI模拟操作。                         |
1570| 4.1.3.0 | 1、新增命令行功能,uitest dumuLayout -a ,dump信息中包含控件的背景色、字体颜色/大小信息。 |
1571