UNPKG

168 kBTypeScriptView Raw
1// Type definitions for nightwatch 2.0
2// Project: http://nightwatchjs.org
3// Definitions by: Rahul Kavalapara <https://github.com/rkavalap>
4// Connor Schlesiger <https://github.com/schlesiger>
5// Clayton Astrom <https://github.com/ClaytonAstrom>
6// Lukas Beranek <https://github.com/lloiser>
7// Vaibhav Singh <https://github.com/vaibhavsingh97>
8// Andrei Rusu <https://github.com/beatfactor>
9// David Burns <https://github.com/AutomatedTester>
10// Ravi Sawlani <https://github.com/gravityvi>
11// Binayak Ghosh <https://github.com/swrdfish>
12// Harshit Agrawal <https://github.com/harshit-bs>
13// David Mello <https://github.com/literallyMello>
14// Luke Bickell <https://github.com/lukebickell>
15// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
16// TypeScript Version: 4.5
17
18import { WebElement, WebElementPromise, By } from 'selenium-webdriver';
19
20export * from './globals';
21
22export interface ChromePerfLoggingPrefs {
23 /**
24 * Default: true. Whether or not to collect events from Network domain.
25 */
26 enableNetwork?: boolean | undefined;
27 /**
28 * Default: true. Whether or not to collect events from Page domain.
29 */
30 enablePage?: boolean | undefined;
31 /**
32 * A comma-separated string of Chrome tracing categories for which trace events should be collected.
33 * An unspecified or empty string disables tracing.
34 */
35 traceCategories?: string | undefined;
36 /**
37 * Default: 1000. The requested number of milliseconds between DevTools trace buffer usage events. For example, if 1000,
38 * then once per second, DevTools will report how full the trace buffer is. If a report indicates the buffer usage is 100%,
39 * a warning will be issued.
40 */
41 bufferUsageReportingInterval?: number | undefined;
42}
43
44export interface ChromeOptions {
45 /**
46 * List of command-line arguments to use when starting Chrome. Arguments with an associated value should be separated by a '=' sign
47 * (e.g., ['start-maximized', 'user-data-dir=/tmp/temp_profile']).
48 */
49 args?: string[] | undefined;
50 /**
51 * Path to the Chrome executable to use (on Mac OS X, this should be the actual binary, not just the app. e.g.,
52 * '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome')
53 */
54 binary?: string | undefined;
55 /**
56 * A list of Chrome extensions to install on startup. Each item in the list should be a base-64 encoded packed Chrome extension (.crx)
57 */
58 extensions?: string[] | undefined;
59 /**
60 * A dictionary with each entry consisting of the name of the preference and its value. These preferences are applied
61 * to the Local State file in the user data folder.
62 */
63 localState?: Record<string, string> | undefined;
64 /**
65 * A dictionary with each entry consisting of the name of the preference and its value. These preferences are only applied
66 * to the user profile in use.
67 */
68 prefs?: Record<string, string> | undefined;
69 /**
70 * Default: false. If false, Chrome will be quit when ChromeDriver is killed, regardless of whether the session is quit.
71 * If true, Chrome will only be quit if the session is quit (or closed). Note, if true, and the session is not quit,
72 * ChromeDriver cannot clean up the temporary user data directory that the running Chrome instance is using.
73 */
74 detach?: boolean | undefined;
75 /**
76 * An address of a Chrome debugger server to connect to, in the form of <hostname/ip:port>, e.g. '127.0.0.1:38947'
77 */
78 debuggerAddress?: string | undefined;
79 /**
80 * List of Chrome command line switches to exclude that ChromeDriver by default passes when starting Chrome.
81 * Do not prefix switches with --.
82 */
83 excludeSwitches?: string[] | undefined;
84 /**
85 * Directory to store Chrome minidumps . (Supported only on Linux.)
86 */
87 minidumpPath?: string | undefined;
88 /**
89 * A dictionary with either a value for “deviceName,” or values for “deviceMetrics” and “userAgent.” Refer to Mobile Emulation for more information.
90 */
91 mobileEmulation?: Record<string, string> | undefined;
92 /**
93 * An optional dictionary that specifies performance logging preferences. See below for more information.
94 */
95 perfLoggingPrefs?: ChromePerfLoggingPrefs | undefined;
96 /**
97 * A list of window types that will appear in the list of window handles. For access to <webview> elements, include "webview" in this list.
98 */
99 windowTypes?: string[] | undefined;
100}
101
102// TODO: visit later
103export interface NightwatchDesiredCapabilities {
104 /**
105 * The name of the browser being used; should be one of {android|chrome|firefox|htmlunit|internet explorer|iPhone|iPad|opera|safari}.
106 */
107 browserName?: string | undefined;
108
109 /**
110 * The browser version, or the empty string if unknown.
111 */
112 version?: string | undefined;
113
114 /**
115 * A key specifying which platform the browser should be running on. This value should be one of {WINDOWS|XP|VISTA|MAC|LINUX|UNIX|ANDROID}.
116 * When requesting a new session, the client may specify ANY to indicate any available platform may be used.
117 * For more information see [GridPlatforms (https://code.google.com/p/selenium/wiki/GridPlatforms)]
118 */
119 platform?: string | undefined;
120
121 /**
122 * Whether the session supports taking screenshots of the current page.
123 */
124 takesScreenShot?: boolean | undefined;
125
126 /**
127 * Whether the session can interact with modal popups, such as window.alert and window.confirm.
128 */
129 handlesAlerts?: boolean | undefined;
130
131 /**
132 * Whether the session supports CSS selectors when searching for elements.
133 */
134 cssSelectorsEnabled?: boolean | undefined;
135
136 /**
137 * Whether the session supports executing user supplied JavaScript in the context of the current page (only on HTMLUnitDriver).
138 */
139 javascriptEnabled?: boolean | undefined;
140
141 /**
142 * Whether the session can interact with database storage.
143 */
144 databaseEnabled?: boolean | undefined;
145
146 /**
147 * Whether the session can set and query the browser's location context.
148 */
149 locationContextEnabled?: boolean | undefined;
150
151 /**
152 * Whether the session can interact with the application cache.
153 */
154 applicationCacheEnabled?: boolean | undefined;
155
156 /**
157 * Whether the session can query for the browser's connectivity and disable it if desired.
158 */
159 browserConnectionEnabled?: boolean | undefined;
160
161 /**
162 * Whether the session supports interactions with storage objects (http://www.w3.org/TR/2009/WD-webstorage-20091029/).
163 */
164 webStorageEnabled?: boolean | undefined;
165
166 /**
167 * Whether the session should accept all SSL certs by default.
168 */
169 acceptSslCerts?: boolean | undefined;
170
171 /**
172 * Whether the session can rotate the current page's current layout between portrait and landscape orientations (only applies to mobile platforms).
173 */
174 rotatable?: boolean | undefined;
175
176 /**
177 * Whether the session is capable of generating native events when simulating user input.
178 */
179 nativeEvents?: boolean | undefined;
180
181 /**
182 * What the browser should do with an unhandled alert before throwing out the UnhandledAlertException. Possible values are "accept", "dismiss" and "ignore"
183 */
184 unexpectedAlertBehaviour?: string | undefined;
185
186 /**
187 * Allows the user to specify whether elements are scrolled into the viewport for interaction to align with the top (0) or bottom (1) of the viewport.
188 * The default value is to align with the top of the viewport. Supported in IE and Firefox (since 2.36)
189 */
190 elementScrollBehaviour?: number | undefined;
191
192 /**
193 * A JSON object describing the logging level of different components in the browser, the driver, or any intermediary WebDriver servers.
194 * Available values for most loggers are "OFF", "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER", "FINEST", "ALL".
195 * This produces a JSON object looking something like: {"loggingPrefs": {"driver": "INFO", "server": "OFF", "browser": "FINE"}}.
196 */
197 loggingPrefs?:
198 | {
199 browser?: string | undefined;
200 driver?: string | undefined;
201 server?: string | undefined;
202 }
203 | undefined;
204 /**
205 * This is a list of all the Chrome-specific desired capabilities.
206 */
207 chromeOptions?: ChromeOptions | undefined;
208}
209
210export interface NightwatchScreenshotOptions {
211 enabled?: boolean | undefined;
212 filename_format: ({
213 testSuite,
214 testCase,
215 isError,
216 dateObject,
217 }?: {
218 testSuite?: string;
219 testCase?: string;
220 isError?: boolean;
221 dateObject?: Date;
222 }) => string;
223 on_failure?: boolean | undefined;
224 on_error?: boolean | undefined;
225 path?: string | undefined;
226}
227
228export interface NightwatchTestRunner {
229 type?: string | undefined;
230 options?:
231 | {
232 ui?: string | undefined;
233 }
234 | undefined;
235}
236
237export interface NightwatchTestWorker {
238 enabled: boolean;
239 workers: string | number;
240 node_options?: string | string[] | undefined;
241}
242
243export interface TimeoutOptions {
244 /**
245 * @default 60000
246 */
247 timeout: number;
248 /**
249 * @default 0
250 */
251 retry_attempts: number;
252}
253
254export interface NightwatchOptions {
255 /**
256 * Location(s) where custom commands will be loaded from.
257 */
258 custom_commands_path?: string | string[] | undefined;
259
260 /**
261 * Location(s) where custom assertions will be loaded from.
262 */
263 custom_assertions_path?: string | string[] | undefined;
264
265 /**
266 * Location(s) where page object files will be loaded from.
267 */
268 page_objects_path?: string | string[] | undefined;
269
270 // An array specifying a list of Nightwatch plugin names that should be used;
271 // e.g.: plugins: ['vite-plugin-nightwatch']
272 plugins: string[];
273
274 /**
275 * Location of an external globals module which will be loaded and made available to the test as a property globals on the main client instance.
276 * Globals can also be defined/overwritten inside a test_settings environment.
277 */
278 globals_path?: string | undefined;
279
280 /**
281 * An object which will be made available on the main test api, throughout the test execution.
282 */
283 globals?: NightwatchGlobals;
284
285 /**
286 * configuration settings for the dotenv module - a zero-dependency module that loads environment variables from a .env file into process.env. More details on https://www.npmjs.com/package/dotenv
287 */
288 dotenv?: any;
289
290 /**
291 * persist the same globals object between runs or have a (deep) copy of it per each test;
292 * this can be useful when persisting data between test suites is needed, such as a cookie or session information.
293 * @default false
294 */
295 persist_globals?: boolean | undefined;
296
297 /**
298 * The location where the JUnit XML report files will be saved. Set this to false if you want to disable XML reporting.
299 */
300 output_folder?: string | undefined;
301
302 /**
303 * An array of folders (excluding subfolders) where the tests are located.
304 */
305 src_folders: string | string[];
306
307 /**
308 * Used when running in parallel to determine if the output should be collected and displayed at the end.
309 */
310 live_output?: boolean | undefined;
311
312 /**
313 * disable support of loading of typescript files for backwards compatibility with test suites.
314 */
315 disable_typescript: boolean | undefined;
316
317 /**
318 * Controls whether or not to disable coloring of the cli output globally.
319 */
320 disable_colors?: boolean | undefined;
321
322 /**
323 * Used when running in parallel to specify the delay (in milliseconds) between starting the child processes
324 */
325 parallel_process_delay?: number | undefined;
326
327 /**
328 * An object containing Selenium Server related configuration options. See below for details.
329 */
330 selenium?: NightwatchSeleniumOptions | undefined;
331
332 /**
333 * Whether or not to automatically start the Selenium/WebDriver session. If running unit tests, this should be set tot false.
334 * @default true
335 */
336 start_process?: boolean | undefined;
337
338 /**
339 * End the session automatically when the test is being terminated, usually after a failed assertion.
340 * @default true
341 */
342 end_session_on_fail?: boolean | undefined;
343
344 /**
345 * Skip the remaining test cases from the current test suite, when one test case fails.
346 */
347 skip_testcases_on_fail?: boolean | undefined;
348
349 /**
350 * Whether or not to run individual test files in parallel. If set to true, runs the tests in parallel and determines the number of workers automatically.
351 * If set to an object, can specify specify the number of workers as "auto" or a number. Example: "test_workers" : {"enabled" : true, "workers" : "auto"}
352 * @default false
353 */
354 test_workers?: boolean | NightwatchTestWorker | undefined;
355
356 /**
357 * This object contains all the test related options. See below for details.
358 */
359 test_settings: NightwatchTestSettings;
360
361 /**
362 * Specifies which test runner to use when running the tests. Values can be either default (built in nightwatch runner) or mocha.
363 * Example: "test_runner" : {"type" : "mocha", "options" : {"ui" : "tdd"}}
364 * @default 'default'
365 */
366 test_runner?: string | NightwatchTestRunner | undefined;
367
368 /**
369 * Allows for webdriver config (mostly the same as selenium)
370 */
371 webdriver?:
372 | {
373 /**
374 * When this is enabled, the Webdriver server is run in background in a child process and started/stopped automatically.
375 * Nightwatch includes support for managing Chromedriver, Geckodriver (Firefox), Safaridriver, and Selenium Server. Please refer to the Install Webdriver section for details.
376 * @default false
377 */
378 start_process: boolean;
379
380 /**
381 * Only useful if start_process is enabled.
382 * @default none
383 */
384 server_path: string;
385
386 /**
387 * Only needed when the Webdriver service is running on a different machine.
388 */
389 host: string;
390
391 /**
392 * The port number on which the Webdriver service will listen and/or on which Nightwatch will attempt to connect.
393 */
394 port: number;
395
396 /**
397 * Should be set to true if connecting to a remote (cloud) service via HTTPS. Also don't forget to set port to 443.
398 */
399 ssl: boolean;
400
401 /**
402 * The location where the Webdriver service log file output.log file will be placed. Defaults to current directory.
403 * To disable Webdriver logging, set this to false.
404 * @default none
405 */
406 log_path: string | boolean;
407
408 /**
409 * List of cli arguments to be passed to the Webdriver process. This varies for each Webdriver implementation.
410 *
411 * @default none
412 */
413 cli_args: any;
414
415 /**
416 * Some Webdriver implementations (Safari, Edge) support both the W3C Webdriver API as well as the legacy JSON Wire (Selenium) API.
417 *
418 * @default false
419 */
420 use_legacy_jsonwire: boolean;
421
422 /**
423 * Time to wait (in ms) before starting to check the Webdriver server is up and running.
424 *
425 * @default 100
426 */
427 check_process_delay: number;
428
429 /**
430 * Maximum number of ping status check attempts when checking if the Webdriver server is up and running before returning a timeout error.
431 *
432 * @default 5
433 */
434 max_status_poll_tries: number;
435
436 /**
437 * Interval (in ms) to use between status ping checks when checking if the Webdriver server is up and running.
438 *
439 * @default 100
440 */
441 status_poll_interval: number;
442
443 /**
444 * The entire time (in ms) to wait for the Node.js process to be created and running (default is 2 min), including spawning the child process and checking the status.
445 *
446 * @default 120000
447 */
448 process_create_timeout: number;
449
450 /**
451 * Proxy requests to the Webdriver (or Selenium) service. http, https, socks(v5), socks5, sock4, and pac are accepted. Uses node-proxy-agent.
452 *
453 * @example http://user:pass@host:port
454 * @default none
455 */
456 proxy: string;
457
458 /**
459 * Requests to the Webdriver service will timeout in timeout miliseconds; a retry will happen retry_attempts number of times.
460 *
461 * @example {timeout: 15000, retry_attempts: 5}
462 */
463 timeout_options: TimeoutOptions;
464
465 /**
466 * Needed sometimes when using a Selenium Server. The prefix to be added to to all requests (e.g. /wd/hub).
467 */
468 default_path_prefix: string;
469
470 /**
471 * Usually only needed for cloud testing Selenium services. In case the server requires credentials this username will be used to compute the Authorization header.
472 *
473 * The value can be also an environment variable, in which case it will look like this:
474 * "username" : "${SAUCE_USERNAME}"
475 *
476 * @default none
477 */
478 username: string;
479
480 /**
481 * This field will be used together with username to compute the Authorization header.
482 *
483 * Like username, the value can be also an environment variable:
484 * "access_key" : "${SAUCE_ACCESS_KEY}"
485 *
486 * @default none
487 */
488 access_key: string;
489 }
490 | undefined;
491
492 /**
493 * An array of folders or file patterns to be skipped (relative to the main source folder).
494 * @example
495 * "exclude" : ["excluded-folder"]
496 * or:
497 * "exclude" : ["test-folder/*-smoke.js"]
498 */
499 exclude?: string[];
500
501 /**
502 * Folder or file pattern to be used when loading the tests. Files that don't match this pattern will be ignored
503 * @example
504 * "filter" : "tests/*-smoke.js"
505 */
506 filter?: string;
507
508 /**
509 * Skip a group of tests (a subfolder); can be a list of comma-separated values (no space).
510 */
511 skipgroup?: string;
512
513 /**
514 * A name property will be added to the desiredCapabilities containing the test suite name when this is enabled. It is useful when using cloud testing services.
515 */
516 sync_test_names?: boolean;
517
518 /**
519 * Skip tests by tag name; can be a list of comma-separated values (no space).
520 */
521 skiptags?: string;
522
523 /**
524 * Use xpath as the default locator strategy.
525 */
526 use_xpath?: boolean;
527
528 parallel_mode?: boolean;
529
530 report_prefix?: string;
531
532 unit_testing_mode?: boolean;
533
534 /**
535 * @default junit
536 */
537 default_reporter?: string;
538
539 /**
540 * @default false
541 */
542 backwards_compatibility_mode?: boolean;
543
544 disable_global_apis?: boolean;
545}
546
547export interface NightwatchGlobals {
548 [key: string]: any;
549 /**
550 * this controls whether to abort the test execution when an assertion failed and skip the rest
551 * it's being used in waitFor commands and expect assertions
552 * @default true
553 */
554 abortOnAssertionFailure?: boolean | undefined;
555
556 /**
557 * this controls whether to abort the test execution when an assertion failed and skip the rest
558 * it's being used in waitFor commands and expect assertions
559 * @default false
560 */
561 abortOnElementLocateError?: boolean | undefined;
562
563 /**
564 * this will overwrite the default polling interval (currently 500ms) for waitFor commands
565 * and expect assertions that use retry
566 * @default 500
567 */
568 waitForConditionPollInterval?: number | undefined;
569
570 /**
571 * default timeout value in milliseconds for waitFor commands and implicit waitFor value for
572 * expect assertions
573 * @default 5000
574 */
575 waitForConditionTimeout?: number | undefined;
576
577 /**
578 * this will cause waitFor commands on elements to throw an error if multiple
579 * elements are found using the given locate strategy and selector
580 * @default false
581 */
582 throwOnMultipleElementsReturned?: boolean | undefined;
583
584 /**
585 * By default a warning is printed if multiple elements are found using the given locate strategy
586 * and selector; set this to true to suppress those warnings
587 * @default false
588 */
589 suppressWarningsOnMultipleElementsReturned: boolean | undefined;
590
591 /**
592 * controls the timeout time for async hooks. Expects the done() callback to be invoked within this time
593 * or an error is thrown
594 * @default 20000
595 */
596 asyncHookTimeout?: number | undefined;
597
598 /**
599 * controls the timeout value for when running async unit tests. Expects the done() callback to be invoked within this time
600 * or an error is thrown
601 * @default 2000
602 */
603 unitTestsTimeout?: number | undefined;
604
605 /**
606 * controls the timeout value for when executing the global async reporter. Expects the done() callback to be invoked within this time
607 * or an error is thrown
608 * @default 20000
609 */
610 customReporterCallbackTimeout?: number | undefined;
611
612 /**
613 * Automatically retrying failed assertions - You can tell Nightwatch to automatically retry failed assertions until a given timeout is reached, before the test runner gives up and fails the test.
614 */
615 retryAssertionTimeout?: number | undefined;
616
617 reporter: (results: any, cb: any) => void;
618 beforeTestSuite(browser: any): Promise<void>;
619 afterTestSuite(browser: any): Promise<void>;
620 beforeTestCase(browser: any): Promise<void>;
621 afterTestCase(browser: any): Promise<void>;
622 onBrowserNavigate(browser: any): Promise<void>;
623 onBrowserQuit(browser: any): Promise<void>;
624}
625
626export interface NightwatchSeleniumOptions {
627 /**
628 * Whether or not to manage the selenium process automatically.
629 * @default false
630 */
631 start_process: boolean;
632
633 /**
634 * Whether or not to automatically start the Selenium session.
635 */
636 start_session: boolean;
637
638 /**
639 * The location of the selenium jar file. This needs to be specified if start_process is enabled.E.g.: lib/selenium-server-standalone-2.43.0.jar
640 */
641 server_path: string;
642
643 /**
644 * The location where the selenium Selenium-debug.log file will be placed. Defaults to current directory. To disable Selenium logging, set this to false
645 */
646 log_path: string | boolean;
647
648 /**
649 * Usually not required and only used if start_process is true. Specify the IP address you wish Selenium to listen on.
650 */
651 host: string;
652
653 /**
654 * The port number Selenium will listen on.
655 */
656 port: number | undefined;
657
658 /**
659 * List of cli arguments to be passed to the Selenium process. Here you can set various options for browser drivers, such as:
660 *
661 * webdriver.firefox.profile: Selenium will be default create a new Firefox profile for each session.
662 * If you wish to use an existing Firefox profile you can specify its name here.
663 * Complete list of Firefox Driver arguments available https://code.google.com/p/selenium/wiki/FirefoxDriver.
664 *
665 * webdriver.chrome.driver: Nightwatch can run the tests using Chrome browser also. To enable this you have to download the ChromeDriver binary
666 * (http://chromedriver.storage.googleapis.com/index.html) and specify it's location here. Also don't forget to specify chrome as the browser name in the
667 * desiredCapabilities object.
668 * More information can be found on the ChromeDriver website (https://sites.google.com/a/chromium.org/chromedriver/).
669 *
670 * webdriver.ie.driver: Nightwatch has support for Internet Explorer also. To enable this you have to download the IE Driver binary
671 * (https://code.google.com/p/selenium/wiki/InternetExplorerDriver) and specify it's location here. Also don't forget to specify "internet explorer" as the browser
672 * name in the desiredCapabilities object.
673 */
674 cli_args: {};
675
676 /**
677 * Time to wait (in ms) before starting to check the Webdriver server is up and running
678 * @default 500
679 */
680 check_process_delay: number;
681
682 /**
683 * Maximum number of ping status check attempts before returning a timeout error
684 * @default 15
685 */
686 max_status_poll_tries: number;
687
688 /**
689 * Interval (in ms) to use between status ping checks when checking if the Webdriver server is up and running
690 * @default 200
691 */
692 status_poll_interval: number;
693}
694
695// TODO: Remove duplicates from NightwatchOptions
696export interface NightwatchTestSettingGeneric {
697 /**
698 * A url which can be used later in the tests as the main url to load. Can be useful if your tests will run on different environments, each one with a different url.
699 */
700 launch_url?: string | undefined;
701
702 /**
703 * The hostname/IP on which the selenium server is accepting connections.
704 */
705 selenium_host?: string | undefined;
706
707 /**
708 * The port number on which the selenium server is accepting connections.
709 */
710 selenium_port?: number | undefined;
711
712 /**
713 * Whether to show extended Selenium command logs.
714 */
715 silent?: boolean | undefined;
716
717 /**
718 * Use to disable terminal output completely.
719 */
720 output?: boolean | undefined;
721
722 /**
723 * Use to disable colored output in the terminal.
724 */
725 disable_colors?: boolean | undefined;
726
727 /**
728 * In case the selenium server requires credentials this username will be used to compute the Authorization header.
729 * The value can be also an environment variable, in which case it will look like this: "username" : "${SAUCE_USERNAME}"
730 */
731 username?: string | undefined;
732
733 /**
734 * This field will be used together with username to compute the Authorization header.
735 * Like username, the value can be also an environment variable: "access_key" : "${SAUCE_ACCESS_KEY}"
736 */
737 access_key?: string | undefined;
738
739 /**
740 * Proxy requests to the selenium server. http, https, socks(v5), socks5, sock4, and pac are accepted. Uses node-proxy-agent. Example: http://user:pass@host:port
741 */
742 proxy?: string | undefined;
743
744 /**
745 * An object which will be passed to the Selenium WebDriver when a new session will be created. You can specify browser name for instance along with other capabilities.
746 * Example:
747 * "desiredCapabilities" : {
748 * "browserName" : "firefox",
749 * "acceptSslCerts" : true
750 * }
751 * You can view the complete list of capabilities https://code.google.com/p/selenium/wiki/DesiredCapabilities.
752 */
753 desiredCapabilities?: NightwatchDesiredCapabilities | undefined;
754
755 /**
756 * An object which will be made available within the test and can be overwritten per environment. Example:"globals" : { "myGlobal" : "some_global" }
757 */
758 globals?: NightwatchTestHooks | undefined;
759
760 /**
761 * An array of folders or file patterns to be skipped (relative to the main source folder).
762 * Example: "exclude" : ["excluded-folder"] or: "exclude" : ["test-folder/*-smoke.js"]
763 */
764 exclude?: string[] | undefined;
765
766 /**
767 * Folder or file pattern to be used when loading the tests. Files that don't match this patter will be ignored.
768 * Example: "filter" : "tests/*-smoke.js"
769 */
770 filter?: string | undefined;
771
772 /**
773 * Do not show the Base64 image data in the (verbose) log when taking screenshots.
774 */
775 log_screenshot_data?: boolean | undefined;
776
777 /**
778 * Use xpath as the default locator strategy
779 */
780 use_xpath?: boolean | undefined;
781
782 /**
783 * Same as Selenium settings cli_args. You can override the global cli_args on a per-environment basis.
784 */
785 cli_args?: any;
786
787 /**
788 * End the session automatically when the test is being terminated, usually after a failed assertion.
789 */
790 end_session_on_fail?: boolean | undefined;
791
792 /**
793 * Skip the rest of testcases (if any) when one testcase fails..
794 */
795 skip_testcases_on_fail?: boolean | undefined;
796}
797
798export interface NightwatchTestSettingScreenshots extends NightwatchTestSettingGeneric {
799 /**
800 * Selenium generates screenshots when command errors occur. With on_failure set to true, also generates screenshots for failing or erroring tests. These are saved on the disk.
801 * Since v0.7.5 you can disable screenshots for command errors by setting "on_error" to false.
802 * Example:
803 * "screenshots" : {
804 * "enabled" : true,
805 * "on_failure" : true,
806 * "on_error" : false,
807 * "path" : ""
808 * }
809 */
810 screenshots: NightwatchScreenshotOptions;
811}
812
813export interface NightwatchTestOptions extends NightwatchTestSettingGeneric {
814 screenshots: boolean;
815 screenshotsPath: string;
816}
817
818export interface NightwatchTestSuite {
819 name: string;
820 module: string;
821 group: string;
822 results: any;
823}
824
825export interface NightwatchAssertionsError {
826 name: string;
827 message: string;
828 showDiff: boolean;
829 stack: string;
830}
831
832export interface NightwatchLanguageChains {
833 to: Expect;
834 be: Expect;
835 been: Expect;
836 is: Expect;
837 that: Expect;
838 which: Expect;
839 and: Expect;
840 has: Expect;
841 have: Expect;
842 with: Expect;
843 at: Expect;
844 of: Expect;
845}
846
847export interface NightwatchTestSettings {
848 [key: string]: NightwatchTestSettingScreenshots;
849}
850
851export interface Expect extends NightwatchLanguageChains, NightwatchBrowser {
852 /**
853 * Returns the DOM Element
854 */
855 element(property: any): this;
856
857 /**
858 * These methods will perform assertions on the specified target on the current element.
859 * The targets can be an attribute value, the element's inner text and a css property.
860 */
861 equal(value: string): this;
862 equals(value: string): this;
863 contain(value: string): this;
864 contains(value: string): this;
865 match(value: string | RegExp): this;
866 startWith(value: string): this;
867 startsWith(value: string): this;
868 endWith(value: string): this;
869 endsWith(value: string): this;
870
871 /**
872 * Negates any of assertions following in the chain.
873 */
874 not: this;
875
876 /**
877 * These methods perform the same thing which is essentially retrying the assertion for the given amount of time (in milliseconds).
878 * before or after can be chained to any assertion and thus adding retry capability. You can change the polling interval by defining
879 * a waitForConditionPollInterval property (in milliseconds) as a global property in your nightwatch.json or in
880 * your external globals file. Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).
881 */
882 before(value: number): this;
883 after(value: number): this;
884
885 /**
886 * Checks if the type (i.e. tag name) of a specified element is of an expected value.
887 */
888 a(value: string, message?: string): this;
889 an(value: string, message?: string): this;
890
891 /**
892 * Checks if a given attribute of an element exists and optionally if it has the expected value.
893 */
894 attribute(name: string, message?: string): this;
895
896 /**
897 * Checks a given css property of an element exists and optionally if it has the expected value.
898 */
899 css(property: string, message?: string): this;
900
901 section(property: string): this;
902
903 /**
904 * Property that checks if an element is currently enabled.
905 */
906 enabled: this;
907
908 /**
909 * Property that checks if an element is present in the DOM.
910 */
911 present: this;
912
913 /**
914 * Property that checks if an OPTION element, or an INPUT element of type checkbox or radio button is currently selected.
915 */
916 selected: this;
917
918 /**
919 * Property that retrieves the text contained by an element. Can be chained to check if contains/equals/matches the specified text or regex.
920 */
921 text: this;
922
923 /**
924 * Property that retrieves the value (i.e. the value attributed) of an element. Can be chained to check if contains/equals/matches the specified text or regex.
925 */
926 value: this;
927
928 /**
929 * Property that asserts the visibility of a specified element.
930 */
931 visible: this;
932}
933
934export interface NightwatchAssertions extends NightwatchCommonAssertions, NightwatchCustomAssertions {
935 /**
936 * Negates any of assertions following in the chain.
937 */
938 not: this;
939}
940
941export interface NightwatchCommonAssertions {
942 /**
943 * Checks if the given attribute of an element contains the expected value.
944 *
945 * ```
946 * this.demoTest = function (client) {
947 * browser.assert.attributeContains('#someElement', 'href', 'google.com');
948 * };
949 * ```
950 */
951 attributeContains(
952 selector: string | ElementProperties,
953 attribute: string,
954 expected: string,
955 message?: string,
956 ): NightwatchAPI;
957
958 /**
959 * Checks if the given attribute of an element has the expected value.
960 *
961 * ```
962 * this.demoTest = function (client) {
963 * browser.assert.attributeEquals('body', 'data-attr', 'some value');
964 * };
965 * ```
966 */
967 attributeEquals(
968 selector: string | ElementProperties,
969 attribute: string,
970 expected: string,
971 message?: string,
972 ): NightwatchAPI;
973
974 /**
975 * Checks if the given element contains the specified text.
976 *
977 * ```
978 * this.demoTest = function (client) {
979 * browser.assert.containsText('#main', 'The Night Watch');
980 * };
981 * ```
982 */
983 containsText(selector: string | ElementProperties, expectedText: string, message?: string): NightwatchAPI;
984
985 /**
986 * Checks if the given element has the specified CSS class.
987 *
988 * ```
989 * this.demoTest = function (client) {
990 * browser.assert.cssClassPresent('#main', 'container');
991 * };
992 * ```
993 */
994 cssClassPresent(selector: string | ElementProperties, className: string, message?: string): NightwatchAPI;
995
996 /**
997 * Checks if the specified css property of a given element has the expected value.
998 *
999 * ```
1000 * this.demoTest = function (client) {
1001 * browser.assert.cssProperty('#main', 'display', 'block');
1002 * };
1003 * ```
1004 */
1005 cssProperty(
1006 selector: string | ElementProperties,
1007 cssProperty: string,
1008 expected: string | number,
1009 msg?: string,
1010 ): NightwatchAPI;
1011
1012 deepEqual(value: any, expected: any, message?: string): NightwatchAPI;
1013
1014 deepStrictEqual(value: any, expected: any, message?: string): NightwatchAPI;
1015
1016 doesNotThrow(value: any, expected: any, message?: string): NightwatchAPI;
1017
1018 /**
1019 * Checks if the given element exists in the DOM.
1020 *
1021 * ```
1022 * this.demoTest = function (client) {
1023 * browser.assert.elementPresent("#main");
1024 * };
1025 * ```
1026 */
1027 elementPresent(selector: string | ElementProperties, msg?: string): NightwatchAPI;
1028
1029 equal(value: any, expected: any, message?: string): NightwatchAPI;
1030
1031 fail(actual?: any, expected?: any, message?: string, operator?: string): NightwatchAPI;
1032
1033 ifError(value: any, message?: string): NightwatchAPI;
1034
1035 notDeepEqual(actual: any, expected: any, message?: string): NightwatchAPI;
1036
1037 notDeepStrictEqual(value: any, message?: string): NightwatchAPI;
1038
1039 notEqual(actual: any, expected: any, message?: string): NightwatchAPI;
1040
1041 notStrictEqual(value: any, expected: any, message?: string): NightwatchAPI;
1042
1043 ok(actual: boolean, message?: string): NightwatchAPI;
1044
1045 strictEqual(value: any, expected: any, message?: string): NightwatchAPI;
1046
1047 throws(fn: () => void, message?: string): NightwatchAPI;
1048
1049 /**
1050 * Checks if the page title equals the given value.
1051 * @deprecated in Nightwatch 2.0 and will be removed from future versions.
1052 * @see assert.titleEquals()
1053 * ```
1054 * this.demoTest = function (client) {
1055 * browser.assert.title("Nightwatch.js");
1056 * };
1057 * ```
1058 */
1059 title(expected: string, message?: string): NightwatchAPI;
1060
1061 /**
1062 * Checks if the page title equals the given value.
1063 * @since 2.0
1064 * ```
1065 * this.demoTest = function (client) {
1066 * browser.assert.titleEquals("Nightwatch.js");
1067 * };
1068 * ```
1069 */
1070 titleEquals(expected: string, message?: string): NightwatchAPI;
1071
1072 /**
1073 * Checks if the page title equals the given value.
1074 *
1075 * ```
1076 * this.demoTest = function (client) {
1077 * browser.assert.title("Nightwatch.js");
1078 * };
1079 * ```
1080 */
1081 titleContains(expected: string, message?: string): NightwatchAPI;
1082
1083 /**
1084 * Checks if the current URL contains the given value.
1085 *
1086 * ```
1087 * this.demoTest = function (client) {
1088 * browser.assert.urlContains('google');
1089 * };
1090 * ```
1091 */
1092 urlContains(expectedText: string, message?: string): NightwatchAPI;
1093
1094 /**
1095 * Checks if the current url equals the given value.
1096 *
1097 * ```
1098 * this.demoTest = function (client) {
1099 * browser.assert.urlEquals('https://www.google.com');
1100 * };
1101 * ```
1102 */
1103 urlEquals(expected: string, message?: string): NightwatchAPI;
1104
1105 /**
1106 * Checks if the given form element's value equals the expected value.
1107 *
1108 * ```
1109 * this.demoTest = function (client) {
1110 * browser.assert.value("form.login input[type=text]", "username");
1111 * };
1112 * ```
1113 */
1114 value(selector: string | ElementProperties, expectedText: string, message?: string): NightwatchAPI;
1115
1116 /**
1117 * Checks if the given form element's value contains the expected value.
1118 *
1119 * ```
1120 * this.demoTest = function (client) {
1121 * browser.assert.valueContains("form.login input[type=text]", "username");
1122 * };
1123 * ```
1124 */
1125 valueContains(selector: string | ElementProperties, expectedText: string, message?: string): NightwatchAPI;
1126
1127 /**
1128 * Checks if the given element is visible on the page.
1129 *
1130 * ```
1131 * this.demoTest = function (client) {
1132 * browser.assert.visible(".should_be_visible");
1133 * };
1134 * ```
1135 */
1136 visible(selector: string | ElementProperties, message?: string): NightwatchAPI;
1137
1138 /**
1139 * Checks if the given element is selected.
1140 *
1141 * @example
1142 * this.demoTest = function (browser) {
1143 * browser.assert.selected('.should_be_selected');
1144 * browser.assert.selected({selector: '.should_be_selected'});
1145 * browser.assert.selected({selector: '.should_be_selected', suppressNotFoundErrors: true});
1146 * };
1147 */
1148 selected(selector: string | ElementProperties, message?: string): NightwatchAPI;
1149
1150 /**
1151 * Checks if the given element is enabled (as indicated by the 'disabled' attribute).
1152 *
1153 * @example
1154 * this.demoTest = function (browser) {
1155 * browser.assert.enabled('.should_be_enabled');
1156 * browser.assert.enabled({selector: '.should_be_enabled'});
1157 * browser.assert.enabled({selector: '.should_be_enabled', suppressNotFoundErrors: true});
1158 * };
1159 */
1160 enabled(selector: string | ElementProperties, message?: string): NightwatchAPI;
1161
1162 /**
1163 * Checks if the specified DOM property of a given element has the expected value.
1164 * For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).
1165 * If the result value is JSON object or array, a deep equality comparison will be performed.
1166 */
1167 domPropertyEquals(
1168 selector: string | ElementProperties,
1169 domProperty: string,
1170 expected: string | number,
1171 msg?: string,
1172 ): NightwatchAPI;
1173
1174 /**
1175 * Checks if the specified DOM property of a given element has the expected value.
1176 * For all the available DOM element properties, consult the [Element doc at MDN](https://developer.mozilla.org/en-US/docs/Web/API/element).
1177 * Several properties can be specified (either as an array or command-separated list). Nightwatch will check each one for presence.
1178 */
1179 domPropertyContains(
1180 selector: string | ElementProperties,
1181 domProperty: string,
1182 expected: string | number,
1183 msg?: string,
1184 ): NightwatchAPI;
1185
1186 NightwatchAssertionsError: NightwatchAssertionsError;
1187}
1188
1189export interface ElementProperties {
1190 /**
1191 * the element selector name
1192 *
1193 * @example
1194 * '@searchBar'
1195 */
1196 selector: string;
1197
1198 /**
1199 * locator strategy can be one of
1200 * - css selector
1201 * - link text
1202 * - partial link text
1203 * - tag name
1204 * - xpath
1205 *
1206 * @example
1207 * 'css selector'
1208 */
1209 locateStrategy?: LocateStrategy;
1210
1211 /**
1212 * used to target a specific element in a query that results in multiple elements returned. Normally,
1213 * only the first element is used (index = 0) but using the index property, you can specify any element within the result.
1214 */
1215 index?: number;
1216
1217 /**
1218 * used to overwrite this setting when using waitForElement* commands.
1219 */
1220 abortOnFailure?: boolean;
1221
1222 /**
1223 * used to overwrite the default timeout for when using waitForElement* commands or assertions.
1224 */
1225 timeout?: number;
1226
1227 /**
1228 * used to overwrite the default retry interval for when using waitForElement* commands or assertions.
1229 */
1230 retryInterval?: number;
1231
1232 /**
1233 * Some element commands like .click() or .getText() will throw a NoSuchElement error if the element cannot be located, causing the test to fail.
1234 * If this option is set to true then this error is ignored.
1235 */
1236 suppressNotFoundErrors?: boolean;
1237}
1238
1239export interface NightwatchTypedCallbackResult<T> {
1240 status: 0;
1241 value: T;
1242 error: Error;
1243}
1244export interface NightwatchCallbackResultError {
1245 status: 1; // we cannot use `number` so giving it a "symbolic" value allows to disjoint the union
1246 value: {
1247 message: string;
1248 screen: string;
1249 class: string;
1250 stackTrace: Array<{
1251 fileName: string;
1252 lineNumber: number;
1253 className: string;
1254 methodName: string;
1255 }>;
1256 };
1257 state: Error | string;
1258}
1259
1260export type NightwatchCallbackResult<T> = NightwatchTypedCallbackResult<T> | NightwatchCallbackResultError;
1261
1262export interface NightwatchLogEntry {
1263 /**
1264 * The log entry message.
1265 */
1266 message: string;
1267
1268 /**
1269 * The time stamp of log entry in seconds.
1270 */
1271 opt_timestamp: number;
1272
1273 /**
1274 * The log type, if known.
1275 */
1276 opt_type?: string;
1277
1278 /**
1279 * Severity level
1280 */
1281 level: 'ALL' | 'DEBUG' | 'FINE' | 'FINER' | 'FINEST' | 'INFO' | 'OFF' | 'SEVERE' | 'WARNING' | Level | number;
1282}
1283
1284export interface Level {
1285 /**
1286 * the level's name.
1287 */
1288 name: string;
1289
1290 /**
1291 * the level's numeric value.
1292 */
1293 level: number;
1294}
1295
1296export interface NightwatchKeys {
1297 /** Releases all held modifier keys. */
1298 NULL: string;
1299 /** OS-specific keystroke sequence that performs a cancel action. */
1300 CANCEL: string;
1301 /** The help key. This key only appears on older Apple keyboards in place of the Insert key. */
1302 HELP: string;
1303 /** The backspace key. */
1304 BACK_SPACE: string;
1305 /** The tab key. */
1306 TAB: string;
1307 /** The clear key. This key only appears on full-size Apple keyboards in place of Num Lock key. */
1308 CLEAR: string;
1309 /** The return key. */
1310 RETURN: string;
1311 /** The enter (numpad) key. */
1312 ENTER: string;
1313 /** The shift key. */
1314 SHIFT: string;
1315 /** The control key. */
1316 CONTROL: string;
1317 /** The alt key. */
1318 ALT: string;
1319 /** The pause key. */
1320 PAUSE: string;
1321 /** The escape key. */
1322 ESCAPE: string;
1323
1324 /** The space bar. */
1325 SPACE: string;
1326 /** The page up key. */
1327 PAGEUP: string;
1328 /** The page down key. */
1329 PAGEDOWN: string;
1330 /** The end key. */
1331 END: string;
1332 /** The home key. */
1333 HOME: string;
1334 /** The left arrow. */
1335 ARROW_LEFT: string;
1336 LEFT_ARROW: string;
1337 /** The up arrow. */
1338 ARROW_UP: string;
1339 UP_ARROW: string;
1340 /** The right arrow. */
1341 ARROW_RIGHT: string;
1342 RIGHT_ARROW: string;
1343 /** The down arrow. */
1344 ARROW_DOWN: string;
1345 DOWN_ARROW: string;
1346 /** The insert key. */
1347 INSERT: string;
1348 /** The delete key. */
1349 DELETE: string;
1350 /** The semicolon key. */
1351 SEMICOLON: string;
1352 /** The equals key. */
1353 EQUALS: string;
1354
1355 /** The numpad zero key. */
1356 NUMPAD0: string;
1357 /** The numpad one key. */
1358 NUMPAD1: string;
1359 /** The numpad two key. */
1360 NUMPAD2: string;
1361 /** The numpad three key. */
1362 NUMPAD3: string;
1363 /** The numpad four key. */
1364 NUMPAD4: string;
1365 /** The numpad five key. */
1366 NUMPAD5: string;
1367 /** The numpad six key. */
1368 NUMPAD6: string;
1369 /** The numpad seven key. */
1370 NUMPAD7: string;
1371 /** The numpad eight key. */
1372 NUMPAD8: string;
1373 /** The numpad nine key. */
1374 NUMPAD9: string;
1375
1376 /** The numpad multiply (*) key. */
1377 MULTIPLY: string;
1378 /** The numpad add (+) key. */
1379 ADD: string;
1380 /** The numpad separator (=) key. */
1381 SEPARATOR: string;
1382 /** The numpad subtract (-) key. */
1383 SUBTRACT: string;
1384 /** The numpad decimal (.) key. */
1385 DECIMAL: string;
1386 /** The numpad divide (/) key. */
1387 DIVIDE: string;
1388
1389 /** The F1 key. */
1390 F1: string;
1391 /** The F2 key. */
1392 F2: string;
1393 /** The F3 key. */
1394 F3: string;
1395 /** The F4 key. */
1396 F4: string;
1397 /** The F5 key. */
1398 F5: string;
1399 /** The F6 key. */
1400 F6: string;
1401 /** The F7 key. */
1402 F7: string;
1403 /** The F8 key. */
1404 F8: string;
1405 /** The F9 key. */
1406 F9: string;
1407 /** The F10 key. */
1408 F10: string;
1409 /** The F11 key. */
1410 F11: string;
1411 /** The F12 key. */
1412 F12: string;
1413 /** The meta (Windows) key. */
1414 META: string;
1415 /** The command (⌘) key. */
1416 COMMAND: string;
1417}
1418
1419export type NightwatchPage = {
1420 [name: string]: () => EnhancedPageObject<any, any, any>;
1421} & {
1422 [name: string]: NightwatchPage;
1423};
1424
1425export interface NightwatchAPI extends SharedCommands, WebDriverProtocol, NightwatchCustomCommands {
1426 baseURL: string;
1427 assert: NightwatchAssertions;
1428 expect: Expect;
1429 verify: NightwatchAssertions;
1430
1431 page: NightwatchPage & NightwatchCustomPageObjects;
1432
1433 /**
1434 * SessionId of the session used by the Nightwatch api.
1435 */
1436 sessionId: string;
1437
1438 /**
1439 * Override the sessionId used by Nightwatch client with another session id.
1440 */
1441 setSessionId(sessionId: string): this;
1442
1443 options: NightwatchTestOptions;
1444
1445 Keys: NightwatchKeys;
1446
1447 currentTest: NightwatchTestSuite;
1448
1449 globals: NightwatchGlobals;
1450
1451 launchUrl: string;
1452 launch_url: string;
1453}
1454
1455// tslint:disable-next-line:no-empty-interface
1456export interface NightwatchCustomCommands {}
1457
1458// tslint:disable-next-line:no-empty-interface
1459export interface NightwatchCustomAssertions {}
1460
1461// tslint:disable-next-line:no-empty-interface
1462export interface NightwatchCustomPageObjects {}
1463
1464export interface NightwatchBrowser
1465 extends NightwatchAPI,
1466 NightwatchComponentTestingCommands,
1467 NightwatchCustomCommands {}
1468
1469export interface NightwatchComponentTestingCommands {
1470 importScript(scriptPath: string, options: { scriptType: string; componentTyp: string }, callback: () => void): this;
1471 mountReactComponent(componentPath: string, props?: string | (() => void), callback?: () => void): this;
1472 mountVueComponent(componentPath: string, options?: any, callback?: () => void): this;
1473 launchComponentRenderer(): this;
1474}
1475
1476// tslint:disable-next-line
1477export interface NightwatchElement extends WebElement {}
1478
1479export type NightwatchTest = (browser?: NightwatchBrowser) => void;
1480export interface NightwatchTestFunctions {
1481 before?: NightwatchTestHook | undefined;
1482 after?: NightwatchTestHook | undefined;
1483 beforeEach?: NightwatchTestHook | undefined;
1484 afterEach?: NightwatchTestHook | undefined;
1485 '@tags'?: string | string[] | undefined;
1486 '@disabled'?: boolean | undefined;
1487 [key: string]: any;
1488}
1489
1490export type NightwatchTestHook = GlobalNightwatchTestHookEach | GlobalNightwatchTestHook;
1491
1492export type GlobalNightwatchTestHookEach = (browser: NightwatchBrowser, done: (err?: any) => void) => void;
1493
1494export type GlobalNightwatchTestHook = (done: (err?: any) => void) => void;
1495
1496export interface NightwatchTestHooks extends NightwatchGlobals {
1497 before?: GlobalNightwatchTestHook | undefined;
1498 after?: GlobalNightwatchTestHook | undefined;
1499 beforeEach?: GlobalNightwatchTestHookEach | undefined;
1500 afterEach?: GlobalNightwatchTestHookEach | undefined;
1501}
1502
1503export function element(locator: string | ElementProperties | By | WebElement, options?: any): WebElement;
1504
1505export type NightwatchTests = NightwatchTestFunctions | NightwatchTestHooks;
1506
1507export class DescribeInstance {
1508 '[instance]': any;
1509 '[attributes]': {};
1510 '[client]': NightwatchClient;
1511 name(): string;
1512 tags(): string | string[];
1513 unitTest(): boolean;
1514 endSessionOnFail(): boolean;
1515 skipTestcasesOnFail(): boolean;
1516 disabled(): boolean;
1517 desiredCapabilities(): NightwatchDesiredCapabilities;
1518 page(): any;
1519 globals(): NightwatchGlobals;
1520 settings(): NightwatchOptions;
1521 argv(): any;
1522 timeout(value: number): void;
1523 waitForTimeout(value: number): number | void;
1524 waitForRetryInterval(value: number): number | void;
1525 retryInterval(value: number): void;
1526 retries(n: any): void;
1527 suiteRetries(n: any): void;
1528 define(name: any, value: any): any;
1529}
1530
1531interface SuiteFunction {
1532 (title: string, fn?: (this: DescribeInstance) => void): this;
1533 only: ExclusiveSuiteFunction;
1534 skip: PendingSuiteFunction;
1535}
1536
1537interface ExclusiveSuiteFunction {
1538 (title: string, fn?: (this: DescribeInstance) => void): this;
1539}
1540
1541interface PendingSuiteFunction {
1542 (title: string, fn: (this: DescribeInstance) => void): this | void;
1543}
1544
1545interface ExclusiveTestFunction {
1546 (fn: NormalFunc | AsyncFunc): this;
1547 (title: string, fn?: NormalFunc | AsyncFunc): this;
1548}
1549
1550interface PendingTestFunction {
1551 (fn: NormalFunc | AsyncFunc): this;
1552 (title: string, fn?: NormalFunc | AsyncFunc): this;
1553}
1554
1555type NormalFunc = (this: DescribeInstance) => any;
1556type AsyncFunc = (this: DescribeInstance) => PromiseLike<any>;
1557interface TestFunction {
1558 (fn: NormalFunc | AsyncFunc): this;
1559 (title: string, fn?: NormalFunc | AsyncFunc): this;
1560 only: ExclusiveTestFunction;
1561 skip: PendingTestFunction;
1562 retries(n: number): void;
1563}
1564
1565export const describe: SuiteFunction;
1566export const xdescribe: PendingSuiteFunction;
1567export const context: SuiteFunction;
1568export const xcontext: PendingSuiteFunction;
1569export const test: TestFunction;
1570export const it: TestFunction;
1571export const xit: PendingTestFunction;
1572export const specify: TestFunction;
1573export const xspecify: PendingTestFunction;
1574export const before: GlobalNightwatchTestHook;
1575export const after: GlobalNightwatchTestHook;
1576export const beforeEach: GlobalNightwatchTestHookEach;
1577export const afterEach: GlobalNightwatchTestHookEach;
1578/**
1579 * Performs an assertion
1580 *
1581 */
1582export type NightwatchAssert = (
1583 passed: boolean,
1584 receivedValue?: any,
1585 expectedValue?: any,
1586 message?: string,
1587 abortOnFailure?: boolean,
1588 originalStackTrace?: string,
1589) => void;
1590
1591/**
1592 * Abstract assertion class that will subclass all defined assertions
1593 *
1594 * All assertions must implement the following api:
1595 *
1596 * - @param {T|function} expected
1597 * - @param {string} message
1598 * - @param {function} pass
1599 * - @param {function} value
1600 * - @param {function} command
1601 * - @param {function} - Optional failure
1602 */
1603export interface NightwatchAssertion<T, U = any> {
1604 expected: (() => T) | T;
1605 message: string;
1606 pass(value: T): any;
1607 value(result: U): T;
1608 command(callback: (result: U) => void): this;
1609 failure?(result: U): boolean;
1610 api: NightwatchAPI;
1611 client: NightwatchClient;
1612}
1613
1614export interface NightwatchClient {
1615 api: NightwatchAPI;
1616 locateStrategy: LocateStrategy;
1617 options: NightwatchOptions;
1618 // TODO: Add reporter
1619 // reporter: reporte
1620 sessionID: string;
1621 settings: NightwatchOptions;
1622}
1623
1624export interface CreateClientParams {
1625 browserName: string | null;
1626 headless?: boolean;
1627 silent?: boolean;
1628 output?: boolean;
1629 useAsync?: boolean;
1630 env?: string;
1631 timeout?: number;
1632 parallel?: boolean;
1633 reporter?: null;
1634 globals?: any;
1635 devtools?: boolean;
1636 debug?: boolean;
1637 enable_global_apis?: boolean;
1638 config?: string;
1639}
1640
1641export interface Nightwatch {
1642 cli(callback: any): this;
1643 client(settings: NightwatchOptions, reporter?: any, argv?: {}): this;
1644 createClient({
1645 headless,
1646 silent,
1647 output,
1648 useAsync,
1649 env,
1650 timeout,
1651 parallel,
1652 reporter,
1653 browserName,
1654 globals,
1655 devtools,
1656 debug,
1657 enable_global_apis,
1658 config,
1659 }: CreateClientParams): this;
1660 cliRunner(argv?: {}): this;
1661 initClient(opts: any): this;
1662 runner(argv?: {}, done?: () => void, settings?: {}): this;
1663 runTests(testSource: string | string[], settings?: any, ...args: any[]): any;
1664 api: NightwatchAPI;
1665 assert: NightwatchAssertions;
1666 expect: Expect;
1667 verify: NightwatchAssertions;
1668}
1669
1670export type LocateStrategy =
1671 | 'class name'
1672 | 'css selector'
1673 | 'id'
1674 | 'name'
1675 | 'link text'
1676 | 'partial link text'
1677 | 'tag name'
1678 | 'xpath';
1679
1680/**
1681 * #### [Enhanced Element Instances](https://github.com/nightwatchjs/nightwatch/wiki/Page-Object-API#enhanced-element-instances)
1682 * Element instances encapsulate the definition used to handle element selectors.
1683 * Generally you won't need to access them directly,
1684 * instead referring to them using their `@`-prefixed names for selector arguments,
1685 * but they are available through a page object or section's elements property.
1686 */
1687export interface EnhancedElementInstance<T> {
1688 /**
1689 * The name of the element as defined by its key in the parent section or the page object's `elements` definition.
1690 * This is the same name used with the `@` prefix in selector arguments for page object commands that refer to the element.
1691 */
1692 name: string;
1693
1694 /**
1695 * The locate strategy to be used with `selector` when finding the element within the DOM.
1696 */
1697 locateStrategy: LocateStrategy;
1698
1699 /**
1700 * A reference to the parent object instance.
1701 * This is the parent section or the page object that contained the definition for this object.
1702 */
1703 parent: T;
1704
1705 /**
1706 * The selector string used to find the element in the DOM.
1707 */
1708 selector: string;
1709}
1710
1711export type EnhancedSectionInstance<
1712 Commands = {},
1713 Elements = {},
1714 Sections extends EnhancedPageObjectSections = {},
1715> = EnhancedPageObject<Commands, Elements, Sections>;
1716
1717export interface EnhancedPageObjectSections {
1718 [name: string]: EnhancedSectionInstance<any, any, any>;
1719}
1720
1721/**
1722 * #### [Enhanced Page Object Instances](https://github.com/nightwatchjs/nightwatch/wiki/Page-Object-API#enhanced-page-object-instances)
1723 * Page object module definitions are used to define page object instances when their respective factory functions within the page reference of the standard command API is called.
1724 * ```
1725 * var myPageObject = browser.page.MyPage(); // defined in MyPage.js module
1726 * ```
1727 * Every time a factory function like MyPage above is called, a new instance of the page object is instantiated.
1728 */
1729export type EnhancedPageObject<
1730 Commands = {},
1731 Elements = {},
1732 Sections extends EnhancedPageObjectSections = {},
1733> = Nightwatch &
1734 SharedCommands &
1735 NightwatchCustomCommands &
1736 Commands & {
1737 /**
1738 * A map of Element objects (see [Enhanced Element Instances](https://github.com/nightwatchjs/nightwatch/wiki/Page-Object-API#enhanced-element-instances)) used by element selectors.
1739 */
1740 elements: {
1741 [name: string]: EnhancedElementInstance<EnhancedPageObject<Commands, Elements, Sections>>;
1742 };
1743
1744 section: Sections;
1745
1746 /**
1747 * The name of the page object as defined by its module name (not including the extension).
1748 * This is the same name used to access the `page` object factory from the page reference in the command API.
1749 */
1750 name: string;
1751
1752 /**
1753 * This command is an alias to url and also a convenience method because when called without any arguments
1754 * it performs a call to .url() with passing the value of `url` property on the page object.
1755 * Uses `url` protocol command.
1756 */
1757 navigate(url?: string, callback?: () => void): EnhancedPageObject<Commands, Elements, Sections>;
1758 };
1759
1760export interface Cookie {
1761 name: string;
1762 value: string;
1763 path: string | undefined;
1764 domain: string | undefined;
1765 secure: boolean | undefined;
1766 expiry: Date | number | undefined;
1767 httpOnly: boolean | undefined;
1768}
1769
1770export interface SharedCommands extends ClientCommands, ElementCommands {}
1771
1772export type windowSizeAndPosition = { offsetX: number; offsetY: number } | { height: number; width: number };
1773export interface ClientCommands {
1774 /**
1775 * Close the current window. This can be useful when you're working with multiple windows open (e.g. an OAuth login).
1776 * Uses `window` protocol command.
1777 *
1778 * @example
1779 * this.demoTest = function () {
1780 * browser.closeWindow();
1781 * };
1782 *
1783 * @see window
1784 */
1785 closeWindow(callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<null>) => void): this;
1786
1787 /**
1788 * Delete the cookie with the given name. This command is a no-op if there is no such cookie visible to the current page.
1789 *
1790 * @example
1791 * this.demoTest = function() {
1792 * browser.deleteCookie("test_cookie", function() {
1793 * // do something more in here
1794 * });
1795 * }
1796 *
1797 * @see cookie
1798 */
1799 deleteCookie(
1800 cookieName: string,
1801 callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<null>) => void,
1802 ): this;
1803
1804 /**
1805 * Delete all cookies visible to the current page.
1806 *
1807 * @example
1808 * this.demoTest = function() {
1809 * browser.deleteCookies(function() {
1810 * // do something more in here
1811 * });
1812 * }
1813 *
1814 * @see cookie
1815 */
1816 deleteCookies(callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<null>) => void): this;
1817
1818 /**
1819 * Ends the session. Uses session protocol command.
1820 *
1821 * @example
1822 * this.demoTest = function () {
1823 * browser.end();
1824 * };
1825 *
1826 * @see session
1827 */
1828 end(callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<null>) => void): this;
1829
1830 /**
1831 * Retrieve a single cookie visible to the current page. The cookie is returned as a cookie JSON object,
1832 * as defined [here](https://code.google.com/p/selenium/wiki/JsonWireProtocol#Cookie_JSON_Object).
1833 *
1834 * Uses `cookie` protocol command.
1835 *
1836 * @example
1837 * this.demoTest = function() {
1838 * browser.getCookie(name, function callback(result) {
1839 * this.assert.equal(result.value, '123456');
1840 * this.assert.equals(result.name, 'test_cookie');
1841 * });
1842 * }
1843 *
1844 * @see cookie
1845 */
1846 getCookie(name: string, callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<Cookie>) => void): this;
1847
1848 /**
1849 * Retrieve all cookies visible to the current page. The cookies are returned as an array of cookie JSON object,
1850 * as defined [here](https://code.google.com/p/selenium/wiki/JsonWireProtocol#Cookie_JSON_Object).
1851 *
1852 * Uses `cookie` protocol command.
1853 *
1854 * @example
1855 * this.demoTest = function() {
1856 * browser.getCookies(function callback(result) {
1857 * this.assert.equal(result.value.length, 1);
1858 * this.assert.equals(result.value[0].name, 'test_cookie');
1859 * });
1860 * }
1861 *
1862 * @see cookie
1863 */
1864 getCookies(callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<Cookie[]>) => void): this;
1865
1866 /**
1867 * Gets a log from Selenium.
1868 *
1869 * @example
1870 * this.demoTest = function() {
1871 * this.getLog('browser', function(logEntriesArray) {
1872 * console.log('Log length: ' + logEntriesArray.length);
1873 * logEntriesArray.forEach(function(log) {
1874 * console.log('[' + log.level + '] ' + log.timestamp + ' : ' + log.message);
1875 * });
1876 * });
1877 * };
1878 *
1879 * @see getLogTypes
1880 */
1881 getLog(typestring: string, callback?: (this: NightwatchAPI, log: NightwatchLogEntry[]) => void): this;
1882
1883 /**
1884 * Gets the available log types. More info about log types in WebDriver can be found here: https://github.com/SeleniumHQ/selenium/wiki/Logging
1885 *
1886 * @example
1887 * this.demoTest = function() {
1888 * this.getLogTypes(function(typesArray) {
1889 * console.log(typesArray);
1890 * });
1891 * };
1892 *
1893 * @see sessionLogTypes
1894 */
1895 getLogTypes(
1896 callback?: (
1897 this: NightwatchAPI,
1898 result: Array<'client' | 'driver' | 'browser' | 'server' | 'performance'>,
1899 ) => void,
1900 ): this;
1901
1902 /**
1903 * Returns the title of the current page. Uses title protocol command.
1904 *
1905 * @example
1906 * this.demoTest = function () {
1907 * browser.getTitle(function(title) {
1908 * this.assert.equal(typeof title, 'string');
1909 * this.assert.equal(title, 'Nightwatch.js');
1910 * });
1911 * };
1912 *
1913 * @see title
1914 */
1915 getTitle(callback?: (this: NightwatchAPI, result?: string) => void): this;
1916
1917 /**
1918 * This command is an alias to url and also a convenience method when called without any arguments in the sense
1919 * that it performs a call to .url() with passing the value of `launch_url` field from the settings file.
1920 * Uses `url` protocol command.
1921 *
1922 * @example
1923 * this.demoTest = function () {
1924 * browser.init();
1925 * };
1926 *
1927 * @see url
1928 */
1929 init(url?: string): this;
1930
1931 /**
1932 * Utility command to load an external script into the page specified by url.
1933 *
1934 * @example
1935 * this.demoTest = function() {
1936 * this.injectScript("{script-url}", function() {
1937 * // we're all done here.
1938 * });
1939 * };
1940 */
1941 injectScript(
1942 scriptUrl: string,
1943 id?: string,
1944 callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<void>) => void,
1945 ): this;
1946
1947 /**
1948 * Utility command to test if the log type is available.
1949 *
1950 * @example
1951 * this.demoTest = function() {
1952 * browser.isLogAvailable('browser', function(isAvailable) {
1953 * // do something more in here
1954 * });
1955 * }
1956 *
1957 * @see getLogTypes
1958 */
1959 isLogAvailable(typeString: string, callback?: (this: NightwatchAPI, result: boolean) => void): this;
1960
1961 /**
1962 * Maximizes the current window.
1963 *
1964 * @example
1965 * this.demoTest = function () {
1966 * browser.maximizeWindow();
1967 * };
1968 *
1969 * @see windowMaximize
1970 */
1971 maximizeWindow(callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<void>) => void): this;
1972
1973 /**
1974 * Suspends the test for the given time in milliseconds. If the milliseconds argument is missing it will suspend the test indefinitely
1975 *
1976 * @example
1977 * this.demoTest = function () {
1978 * browser.pause(1000);
1979 * // or suspend indefinitely
1980 * browser.pause();
1981 * };
1982 */
1983 pause(ms?: number, callback?: (this: NightwatchAPI) => void): this;
1984
1985 /**
1986 * A simple perform command which allows access to the Nightwatch API in a callback. Can be useful if you want to read variables set by other commands.
1987 *
1988 * The callback signature can have up to two parameters.
1989 * - no parameters: callback runs and perform completes immediately at the end of the execution of the callback.
1990 * - one parameter: allows for asynchronous execution within the callback providing a done callback function for completion as the first argument.
1991 * - two parameters: allows for asynchronous execution with the Nightwatch `api` object passed in as the first argument, followed by the done callback.
1992 *
1993 * @example
1994 * this.demoTest = function () {
1995 * var elementValue;
1996 * browser
1997 * .getValue('.some-element', function(result) {
1998 * elementValue = result.value;
1999 * })
2000 * // other stuff going on ...
2001 * //
2002 * // self-completing callback
2003 * .perform(function() {
2004 * console.log('elementValue', elementValue);
2005 * // without any defined parameters, perform
2006 * // completes immediately (synchronously)
2007 * })
2008 * //
2009 * // asynchronous completion
2010 * .perform(function(done) {
2011 * console.log('elementValue', elementValue);
2012 * // potentially other async stuff going on
2013 * // on finished, call the done callback
2014 * done();
2015 * })
2016 * //
2017 * // asynchronous completion including api (client)
2018 * .perform(function(done) {
2019 * console.log('elementValue', elementValue);
2020 * // similar to before, but now with client
2021 * // potentially other async stuff going on
2022 * // on finished, call the done callback
2023 * done();
2024 * });
2025 * };
2026 */
2027 perform(
2028 callback:
2029 | (() => undefined | Promise<any>)
2030 | ((done: () => void) => void)
2031 | ((client: NightwatchAPI, done: () => void) => void),
2032 ): this;
2033
2034 /**
2035 * Resizes the current window.
2036 *
2037 * @example
2038 * this.demoTest = function () {
2039 * browser.resizeWindow(1000, 800);
2040 * };
2041 *
2042 * @see windowSize
2043 */
2044 resizeWindow(
2045 width: number,
2046 height: number,
2047 callback?: (this: NightwatchAPI, result: NightwatchCallbackResult<void>) => void,
2048