---
title: "Debug failing puppeteer tests due to background tab"
description: "Debugging failing tests in puppeteer because of background tab"
canonical_url: "https://www.bigbinary.com/blog/debugging-failing-tests-in-background-tab-in-puppeteer"
markdown_url: "https://www.bigbinary.com/blog/debugging-failing-tests-in-background-tab-in-puppeteer.md"
---

# Debug failing puppeteer tests due to background tab

Debugging failing tests in puppeteer because of background tab

- Author: Rohit Kumar
- Published: August 15, 2018
- Categories: Misc

We have been using puppeteer in one of our projects to write end-to-end tests.
We run our tests in headful mode to see the browser in action.

If we start puppeteer tests and do nothing in our laptop (just watch the tests
being executed) then all the tests will pass.

However if we are doing our regular work in our laptop while tests are running
then tests would fail randomly. This was quite puzzling.

Debugging such flaky tests is hard. We first suspected that the test cases
themselves needed more of implicit waits for element/text to be present/visible
on the DOM.

After some debugging using puppeteer protocol logs, it seemed like the browser
was performing certain actions very slowly or was waiting for the browser to be
active ( in view ) before performing those actions.

Chrome starting with version 57 introduced
[throttling of background tabs](https://developers.google.com/web/updates/2017/03/background_tabs)
for improving performance and battery life. We execute one test per browser
meaning we didn't make use of multiple tabs. Also tests failed only when the
user was performing some other activities while the tests were executing in
other background windows.
[Pages were hidden](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)
only when user switched tabs or minimized the browser window containing the tab.

After observing closely we noticed that the pages were making requests to the
server. The issue was the page was not painting if the page is not in view. We
added flag `--disable-background-timer-throttling` but we did not notice any
difference.

After doing some searches we noticed the flag `--disable-renderer-backgrounding`
was being used in
[karma-launcher](https://github.com/karma-runner/karma-chrome-launcher/blob/01c7efc870e64733d81347d4996fb9bcbf099825/index.js#L42-L46).
The comment states that it is specifically required on macOS. Here is the
[code](https://cs.chromium.org/chromium/src/content/browser/renderer_host/render_widget_host_impl.cc?l=684-689)
responsible for lowering the priority of the renderer when it is hidden.

But the new flag didn't help either.

While looking at all the available command line switches for chromium, we
stumbled upon `--disable-backgrounding-occluded-windows`. Chromium also
backgrounds the renderer while the window is not visible to the user. It seems
from the comment that the flag
[kDisableBackgroundingOccludedWindowsForTesting](https://cs.chromium.org/chromium/src/content/public/common/content_switches.cc?l=99-102)
is specifically added to avoid non-deterministic behavior during tests.

We have added following flags to chromium for running our integration suite and
this solved our problem.

```js
const chromeArgs = [
  "--disable-background-timer-throttling",
  "--disable-backgrounding-occluded-windows",
  "--disable-renderer-backgrounding",
];
```

References

- [Background tabs & offscreen frames ](https://docs.google.com/document/d/18_sX-KGRaHcV3xe5Xk_l6NNwXoxm-23IOepgMx4OlE4/pub)
- [Mac Window Occlusion API Use](https://www.chromium.org/developers/design-documents/mac-occlusion)

## Links

- [Human page](https://www.bigbinary.com/blog/debugging-failing-tests-in-background-tab-in-puppeteer)