Expand troubleshooting documentation

[The-Compiler]

See this discussion on Twitter: https://twitter.com/VeronicaInPink/status/1129848173084717056

Ideas what to mention:

• What to do on segfaults/aborts (running pytest with -s, pytest-faulthandler)
• Missing libxkbcommon-x11-0 dependency (e.g. on Travis)

[vkbo]

Thanks for picking up this discussion on Twitter!

So, first of all, running with pytest-faulthandler did help, and alerted me to the point of failure in pytest-qt, which was here: https://github.com/pytest-dev/pytest-qt/blob/master/pytestqt/plugin.py#L57

Pytest exited with error code 134. Installing the correct dependency for PyQt5 fixed this, but on this particular VM at least (Ubuntu 16.04), I needed to install pywt5.qtsvg as a separate package. The tests still ran on my code while missing that package, but I got a segfault at the end. I am unsure why. I stopped debugging it when installing the package solved it.

My main problem was tracking down exactly what failed, because that wasn't at all obvious at first. So, your first point is a good one to add.

It looks to me that the segfault happened on the PyQt5 side of things, as I found a few bug reports on applications segfaulting on missing dependencies or mixed library versions.

[The-Compiler]

Some more changes the troubleshooting docs will need:

• With #300, I there will also be some useful output from Qt when there's no display set with -s`:

test_qt.py qt.qpa.xcb: could not connect to display 
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, webgl, xcb.

Fatal Python error: Aborted

• With the upcoming Qt 5.15, not only libxkbcommon-x11-0 needs to be installed, but some other packages as well:

  • libxcb-icccm4
  • libxcb-image0
  • libxcb-keysyms1
  • libxcb-randr0
  • libxcb-render-util0
  • libxcb-xinerama0

• Also see https://github.com/pytest-dev/pytest-qt/issues/266#issuecomment-510035926

[nicoddemus]

Another addition to the docs: https://github.com/pytest-dev/pytest-qt/issues/254#issuecomment-561848689

[nicoddemus]

Another: https://github.com/pytest-dev/pytest-qt/issues/211#issuecomment-625861149

[The-Compiler]

Two more:

• #324 (mainly QT_DEBUG_PLUGINS)
• The Qt 5.15.2 libxcb-util issue

[adam-grant-hendry]

Please add additional information for Windows OS users. Specifically, headless testing on CI/CD for Windows machines is needed. There is support for Linux with pytest-xvfb, but no instruction for Windows (AFAICT).

[The-Compiler]

@adam-grant-hendry because, to my knowledge, no equivalent for Windows exists.

[adam-grant-hendry]

@The-Compiler Set the environment variable

QT_QPA_PLATFORM=offscreen

I found this is how GitLab users are running their tests.