From 06732a337b4e4ad823ba8a79bf0c06d3c7775cdd Mon Sep 17 00:00:00 2001 From: Peter Hedenskog Date: Fri, 10 Jun 2022 09:51:02 +0200 Subject: [PATCH] Add --debug mode (#3672) --- .../sitespeed.io/scripting/index.md | 73 ++++++++++++------- lib/cli/cli.js | 29 +++++++- 2 files changed, 74 insertions(+), 28 deletions(-) diff --git a/docs/documentation/sitespeed.io/scripting/index.md b/docs/documentation/sitespeed.io/scripting/index.md index 4fce266fe..33f8ac369 100644 --- a/docs/documentation/sitespeed.io/scripting/index.md +++ b/docs/documentation/sitespeed.io/scripting/index.md @@ -175,36 +175,11 @@ One of the key things in your script is to be able to find the right element to Using Chrome to find the CSS Selector to the element

-## Running setUp and tearDown in the same script - -Scripts can also directly define the ```--preScript``` and ```--postScript``` options by implementing a *setUp* and/or a *tearDown* function. These functions will get the same arguments than the test itself. When using this form, the three functions are declared in *module.exports* under the *setUp*, *tearDown* and *test* keys. - -Here's a minimal example: - -~~~javascript -async function setUp(context, commands) { - // do some useful set up -}; - -async function perfTest(context, commands) { - // add your own code here -}; - -async function tearDown(context, commands) { - // do some cleanup here -}; - -module.exports = { - setUp: setUp, - tearDown: tearDown, - test: perfTest -}; -~~~ - - ## Debug There's a couple of way that makes it easier to debug your scripts: +* Run in `--debug` mode and add breakpoints to your code. The browser will open with devtools open and will pause on each breakpoint. + * Make sure to [use the log](#log-from-your-script) so you can see what happens in your log output. Your script can log to the sitespeed.io default log. ~~~javascript context.log.info('Info logging from your script'); @@ -794,6 +769,33 @@ module.exports = function() { And then run it: ```sitespeed.io --multi test.js``` + +## Running setUp and tearDown in the same script + +Scripts can also directly define the ```--preScript``` and ```--postScript``` options by implementing a *setUp* and/or a *tearDown* function. These functions will get the same arguments than the test itself. When using this form, the three functions are declared in *module.exports* under the *setUp*, *tearDown* and *test* keys. + +Here's a minimal example: + +~~~javascript +async function setUp(context, commands) { + // do some useful set up +}; + +async function perfTest(context, commands) { + // add your own code here +}; + +async function tearDown(context, commands) { + // do some cleanup here +}; + +module.exports = { + setUp: setUp, + tearDown: tearDown, + test: perfTest +}; +~~~ + ## Commands All commands will return a promise and you should await it to fulfil. If some command do not work, we will log that automatically and rethrow the error, so you can catch that and can act on that. @@ -987,6 +989,23 @@ module.exports = async function(context, commands) { } ~~~ +### Breakpoint + +You can use breakpoints to debug your script. You can add breakpoints to your script that will be used when you run in `--debug` mode. At each breakpoint the browser will pause. You can continue by adding `window.browsertime.pause=false;` in your developer console. + +Debug mode works in Chrome/Firefox/Edge when running on desktop. It do not work in Docker and on mobile. When you run in debug mode, devtools will be automatically open so you can debug your script. + +In debug mode, the browser will pause after each iteration. + +~~~javascript +module.exports = async function(context, commands) { + await commands.measure.start('https://www.sitespeed.io'); + await commands.breakpoint(''); + return commands.measure.start('https://www.sitespeed.io/documentation/'); +}; +~~~ + + ### Click The click command will click on links. diff --git a/lib/cli/cli.js b/lib/cli/cli.js index 9f6ea791e..fa89d8c3b 100644 --- a/lib/cli/cli.js +++ b/lib/cli/cli.js @@ -141,6 +141,18 @@ function validateInput(argv) { return 'You need to specify the --safari.deviceUDID when you run the simulator. Run "xcrun simctl list devices" in your terminal to list all devices.'; } + if (argv.browsertime.debug && argv.browsertime.browser === 'safari') { + return 'Debug mode do not work in Safari. Please try with Firefox/Chrome or Edge'; + } + + if (argv.browsertime.debug && argv.android) { + return 'Debug mode do not work on Android. Please run debug mode on Desktop.'; + } + + if (argv.browsertime.debug && argv.docker) { + return 'There is no benefit running debug mode inside a Docker container.'; + } + // validate URLs/files const urlOrFiles = argv._; for (let urlOrFile of urlOrFiles) { @@ -208,7 +220,7 @@ module.exports.parseCommandLine = function parseCommandLine() { type: 'boolean' }) .option('verbose', { - alias: ['v', 'debug'], + alias: ['v'], describe: 'Verbose mode prints progress messages to the console. Enter up to three times (-vvv)' + ' to increase the level of detail.', @@ -250,6 +262,14 @@ module.exports.parseCommandLine = function parseCommandLine() { default: false, group: 'Browser' }) + .option('browsertime.debug', { + alias: 'debug', + type: 'boolean', + default: false, + describe: + 'Run Browsertime in debug mode. Use commands.breakpoint(name) to set btreakpoints in your script. Debug mode works for Firefox/Chrome/Edge on desktop.', + group: 'Browser' + }) .option('browsertime.gnirehtet', { alias: 'gnirehtet', type: 'boolean', @@ -1753,6 +1773,13 @@ module.exports.parseCommandLine = function parseCommandLine() { set(argv, 'browsertime.urlMetaData', meta); } + // Set the timeouts to a maximum while debugging + if (argv.debug) { + set(argv, 'browsertime.timeouts.pageload', 2147483647); + set(argv, 'browsertime.timeouts.script', 2147483647); + set(argv, 'browsertime.timeouts.pageCompleteCheck', 2147483647); + } + return { urls: argv.multi ? argv._ : cliUtil.getURLs(argv._), urlsMetaData,