API break suggestions for 4.0

As mentioned in https://github.com/pytest-dev/pytest-qt/pull/302#issuecomment-629513007 I went through the docs/code and thought about possible API breaks which would make sense for 4.0. Here are a couple of ideas:

• 1. One thing that always irked me a bit is that we have two naming conventions (add_widget vs. addWidget). Is it really a good idea to support both? At least in my project, it only lead to using both inconsistently over the years without noticing. Should we get rid of one of those? On the other hand, that’s probably a lot of churn for projects using pytest-qt, so I’m not sure if it’s worth it. Maybe as an alternative, we could make it possible to configure the desired API style in pytest.ini so that the other style would raise an exception (that could be done after 4.0)?
• 2. Right now the user needs to decide between waitActive, waitExposed and waitForWindowShown (which might be a hurdle if using the same tests for two different backends). Should we have a wrapper which decides what to use instead?
• 3. Shouldn’t waitForWindowShown have a timeout as well? (can be done after 4.0)
• 4. Does anyone really use qtbot.stopForInteraction() instead of qtbot.stop()? A GitHub search reveals 60 results, vs. 122 results for .stop(), though I guess it’s mostly used interactively for debugging without being added to the code. Should we remove the long name?
• 5. Should we raise the default timeout for waitSignal() to 5000, similar to QSignalSpy.wait() in Qt and the other default timeouts in pytest-qt?
• 6. waitSignal and waitSignals can take None instead of a signal, in which case they just wait until the timeout occurred. But we already have qtbot.wait() for that, so is there a reason to support it?
• 7. Can we get rid of the SignalTimeoutError compatibility alias for TimeoutError?
• 8. The docs for pytestqt.logging.Record says that context is only available for Qt 5, that can probably be removed now (can be done after 4.0)
• 9. (new, see below) Get rid of qt_wait_signal_raising
• 10. (new, see below) Get rid of aliases in plugin.py

[The-Compiler]

All done! 🎉

[The-Compiler]

So I had a quick look at the waitActive, waitExposed and waitForWindowShown situation, and here’s what I gathered:

• qWaitForWindowActive and qWaitForWindowExposed (which we expose as waitActive and waitExposed) were added in Qt 5.0 and still exist in Qt 6. Those we should probably keep as-is.
• qWaitForWindowShown is obsolete in Qt 5 and removed in Qt 6. In other words, it’s only “correct” to use with Qt 4, which we don’t support anymore.
• It looks like the problem with qWaitForWindowShown is indeed that the name is confusing, and it’s indeed just an alias to qWaitForWindowExposed
• In pytest-qt, we originally used qWaitForWindowShown if available (falling back to qWaitForWindowExposed otherwise), but this was changed later as part of #159.
• Both PySide2 (even 5.11.0) and PyQt5 (even 5.7.1) don’t expose QtTest.QTest.qWaitForWindowShown at all, probably because it was obsolete with Qt 5.0 already.

Now with Qt 4 support dropped, in theory we could also drop waitForWindowShown entirely. However, it seems quite widely used:

• GitHub search: 238 results camel case, 13 results snake case
• grep.app: 60 results
• Debian Code Search: 1 result (plus pytest-qt) - but note that tests often aren’t packaged/distributed, so that’s a bit of an outlier.

So it seems to me like we accidentally kept something alive which was long obsoleted/deprecated, and due to the pytest-qt layer, users wouldn’t notice any deprecation warnings (or the removals in the Qt 5 wrappers) at all…

Another problem is that we document both waitActive and waitExposed as:

This function is only available in PyQt5, raising a RuntimeError if called from PySide2/6.

and indeed do so:

https://github.com/pytest-dev/pytest-qt/blob/5ea3a3d292dd30b721ef333d9372a221abbbd5a9/src/pytestqt/qtbot.py#L732-L733

but in fact at least the underlying Qt functions are available with both PySide2 and PySide6. Looking at #159, I think what we actually wanted to say there is that it’s not available with PyQt4 and PySide (i.e. on Qt 4), but at that time PyQt5 was the only supported Qt 5 wrapper. Somehow this stayed around until today, despite PySide2 and then later PyQt6 and PySide6 being added…

So I’m not sure how to proceed here. We definitely should support all wrappers with waitActive and waitExposed, but what do we do with waitForWindowShown given the widespread usage (and only option so far if using PySide2 or Qt 6)? Options I can think of:

• Keep the wrapper but add a deprecation warning
• As above, but fail hard if PYTEST_QT_API is set to PySide6/PyQt6 (because the upstream method is fully gone there)
• Remove the wrapper and force people to adjust, given that this has been deprecated in Qt for 9 years and we’re doing a major release here

What do you think @nicoddemus?