feat(chromium): add waitForSelector option to Chromium conversions (#1446)

* Add `waitForSelector` option to Chromium conversions

Closes #960

As an alternative to waiting on an expression, this allows users to wait
for a specific node matching a selector to become visible in the HTML /
at the remote URL before converting to PDF.

* Fix style / prettify

pkg/modules/chromium/browser.go

@@ -290,6 +290,7 @@ func (b *chromiumBrowser) pdf(ctx context.Context, logger *zap.Logger, url, outp
 		forceExactColorsActionFunc(logger, options.PrintBackground),
 		emulateMediaTypeActionFunc(logger, options.EmulatedMediaType),
 		waitForExpressionBeforePrintActionFunc(logger, b.arguments.disableJavaScript, options.WaitForExpression),
+		waitForSelectorVisibleBeforePrintActionFunc(logger, options.WaitForSelector),
 		waitDelayBeforePrintActionFunc(logger, b.arguments.disableJavaScript, options.WaitDelay),
 		// PDF specific.
 		printToPdfActionFunc(logger, outputPath, options),
@@ -315,6 +316,7 @@ func (b *chromiumBrowser) screenshot(ctx context.Context, logger *zap.Logger, ur
 		forceExactColorsActionFunc(logger, true),
 		emulateMediaTypeActionFunc(logger, options.EmulatedMediaType),
 		waitForExpressionBeforePrintActionFunc(logger, b.arguments.disableJavaScript, options.WaitForExpression),
+		waitForSelectorVisibleBeforePrintActionFunc(logger, options.WaitForSelector),
 		waitDelayBeforePrintActionFunc(logger, b.arguments.disableJavaScript, options.WaitDelay),
 		// Screenshot specific.
 		setDeviceMetricsOverride(logger, options.Width, options.Height),

pkg/modules/chromium/chromium.go

@@ -33,6 +33,10 @@ var (
 	// returns an exception or undefined.
 	ErrInvalidEvaluationExpression = errors.New("invalid evaluation expression")
 
+	// ErrInvalidSelectorQuery happens if a selector query returns an exception
+	// or undefined.
+	ErrInvalidSelectorQuery = errors.New("invalid selector query")
+
 	// ErrRpccMessageTooLarge happens when the messages received by
 	// ChromeDevTools are larger than 100 MB.
 	ErrRpccMessageTooLarge = errors.New("rpcc message too large")
@@ -142,6 +146,10 @@ type Options struct {
 	// converting an HTML document until it returns true
 	WaitForExpression string
 
+	// WaitForSelector is the element query to wait until visible before
+	// converting an HTML document.
+	WaitForSelector string
+
 	// Cookies are the cookies to put in the Chromium cookies' jar.
 	Cookies []Cookie
 
@@ -173,6 +181,7 @@ func DefaultOptions() Options {
 		WaitDelay:                       0,
 		WaitWindowStatus:                "",
 		WaitForExpression:               "",
+		WaitForSelector:                 "",
 		Cookies:                         nil,
 		UserAgent:                       "",
 		ExtraHttpHeaders:                nil,

pkg/modules/chromium/routes.go

@@ -55,6 +55,7 @@ func FormDataChromiumOptions(ctx *api.Context) (*api.FormData, Options) {
 		waitDelay                       time.Duration
 		waitWindowStatus                string
 		waitForExpression               string
+		waitForSelector                 string
 		cookies                         []Cookie
 		userAgent                       string
 		extraHttpHeaders                []ExtraHttpHeader
@@ -108,6 +109,7 @@ func FormDataChromiumOptions(ctx *api.Context) (*api.FormData, Options) {
 		Duration("waitDelay", &waitDelay, defaultOptions.WaitDelay).
 		String("waitWindowStatus", &waitWindowStatus, defaultOptions.WaitWindowStatus).
 		String("waitForExpression", &waitForExpression, defaultOptions.WaitForExpression).
+		String("waitForSelector", &waitForSelector, defaultOptions.WaitForSelector).
 		Custom("cookies", func(value string) error {
 			if value == "" {
 				cookies = defaultOptions.Cookies
@@ -237,6 +239,7 @@ func FormDataChromiumOptions(ctx *api.Context) (*api.FormData, Options) {
 		WaitDelay:                       waitDelay,
 		WaitWindowStatus:                waitWindowStatus,
 		WaitForExpression:               waitForExpression,
+		WaitForSelector:                 waitForSelector,
 		Cookies:                         cookies,
 		UserAgent:                       userAgent,
 		ExtraHttpHeaders:                extraHttpHeaders,
@@ -809,6 +812,22 @@ func handleChromiumError(err error, options Options) error {
 		)
 	}
 
+	if errors.Is(err, ErrInvalidSelectorQuery) {
+		if options.WaitForSelector == "" {
+			// We only expect to see this error if the user specified a selector.
+			// If they didn't and we still generated the error, return a 500.
+			return err
+		}
+
+		return api.WrapError(
+			err,
+			api.NewSentinelHttpError(
+				http.StatusBadRequest,
+				fmt.Sprintf("The selector '%s' (waitForSelector) returned an exception or undefined", options.WaitForSelector),
+			),
+		)
+	}
+
 	if errors.Is(err, ErrInvalidHttpStatusCode) {
 		return api.WrapError(
 			err,

pkg/modules/chromium/tasks.go

@@ -512,3 +512,19 @@ func waitForExpressionBeforePrintActionFunc(logger *zap.Logger, disableJavaScrip
 		}
 	}
 }
+
+func waitForSelectorVisibleBeforePrintActionFunc(logger *zap.Logger, selector string) chromedp.ActionFunc {
+	return func(ctx context.Context) error {
+		if selector == "" {
+			logger.Debug("no wait selector")
+			return nil
+		}
+
+		logger.Debug(fmt.Sprintf("wait until '%s' is visible before print", selector))
+		err := chromedp.WaitVisible(selector, chromedp.ByQuery, chromedp.RetryInterval(time.Duration(100)*time.Millisecond)).Do(ctx)
+		if err != nil {
+			return fmt.Errorf("wait visible: %v: %w", err, ErrInvalidSelectorQuery)
+		}
+		return nil
+	}
+}