Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorControl::ModuleTestHost Class Reference

Checks one control module without a window, for the module's own CI. More...

#include <PhosphorControl/ModuleTestHost.h>

Public Member Functions

 ModuleTestHost (QString modulePath)
void setResultTimeoutMs (int ms)
 How long to wait for a domain's applyResult or discardResult.
void setStagingDirectory (const QString &directory)
 Where run() stages its copies: a fresh directory <directory>/module-test-XXXXXX/, removed when run() returns, whose control/ holds the module as module.so and the target modules as target-000.so onwards, whatever their files are called.
void addTargetModule (const QString &modulePath)
 Offer the module at modulePath too, so the module under test's extensions aimed at it, and its search entries on that module's pages, are checked against what its metadata declares.
void setPreviousAnchors (const QString &anchorsPath)
 The anchors.json of the module's previous release (phosphor_add_control_module_metadata's MODULE_ANCHORS_FILE), which holds each page's anchors, its anchors version and the versions of its named extension points.
QStringList run ()
 Every problem found, one line each. Empty means the module passes.

Static Public Attributes

static constexpr int DefaultResultTimeoutMs = 2000

Detailed Description

Checks one control module without a window, for the module's own CI.

Lives in the PhosphorControl::PhosphorControlTest library.

run() copies the module library, and every target module (addTargetModule()), into a private search path, hosts them in a ModuleHost over a fresh ApplicationController, loads the module, and checks that:

  • the catalog accepts it (IID, ApiVersion, a valid "Id")
  • its metadata is valid, and parses without a warning: a key this PhosphorControl does not know, a search entry of a kind it does not know, or a Key[<lang>] whose locale is not written in letters, digits and '_' (Name[pt-BR], which no locale picks) is reported as metadata: <warning>, since the module is built against the PhosphorControl that checks it
  • it loads, and registerInto registers exactly the pages and extensions its metadata declares, each page with a controller of the matching id and an absolute QML source (the rules ModuleContext enforces)
  • every page was bound, and every headless domain and every extension's domain is still there, which code the module runs while it loads could delete, at once or with a deleteLater()
  • each page's and each extension's QML source exists, for a qrc: or file: URL
  • no page controller, headless domain or extension domain is dirty right after loading
  • every page controller, headless domain and extension domain answers apply() with one applyResult and discard() with one discardResult, both reporting success, sends no second one within a short grace period, and is not deleted by either call or by another domain's
  • a module whose metadata says SearchProviders registered one
  • every entry its search providers return, except an action (which has no page), points at one of its pages or a page it extends. A setting or section entry with an anchor names one its page lists, on its own page, and on a page it extends when that page's module is a target, where the anchor <module>:<extension> of one of the module's own sections on that page passes too. One with no anchor points at the page as a whole and passes.
  • with addTargetModule(), every extension aimed at a target module fits the slot and version that module offers
  • with setPreviousAnchors(), no page of the previous release is gone, no anchor is gone unless the page's anchors version went up, the anchors version did not go down, and no named extension point is gone or went down in version. A page can never go, since other modules may extend it, whatever its version.

When the module is refused, its metadata is invalid or it does not load, run() reports that and stops, since the later checks need a loaded module. The checks after loading all run and report together. A problem with a target module is reported too, by the path it was added with, and the run goes on without it: a target the catalog refuses, and one whose id is the module's or another target's, which is left out.

The apply and discard round runs on freshly loaded, clean state, which is not how the host drives a domain: it applies dirty domains only. It catches a domain that answers twice or not at all, not one whose dirty path misbehaves, so cover that in the module's own tests.

run() does not write the settings files the module opens through ModuleContext::configBackend, as long as the module's factory opens the path it is handed. It makes each of them under its staging directory instead (ModuleHost::setConfigRedirect), so the module starts from an empty file and its defaults, and the files go when run() returns. Anything else a domain's apply() writes (a file the module opens by itself, a call to a daemon) still goes where the module sends it, so point that at a scratch target first.

Needs a QCoreApplication (or QGuiApplication) running on this thread.

Constructor & Destructor Documentation

◆ ModuleTestHost()

PhosphorControl::ModuleTestHost::ModuleTestHost ( QString modulePath)
explicit

Member Function Documentation

◆ addTargetModule()

void PhosphorControl::ModuleTestHost::addTargetModule ( const QString & modulePath)

Offer the module at modulePath too, so the module under test's extensions aimed at it, and its search entries on that module's pages, are checked against what its metadata declares.

A target is never loaded, and its own metadata and extensions are not checked.

◆ run()

QStringList PhosphorControl::ModuleTestHost::run ( )
nodiscard

Every problem found, one line each. Empty means the module passes.

◆ setPreviousAnchors()

void PhosphorControl::ModuleTestHost::setPreviousAnchors ( const QString & anchorsPath)

The anchors.json of the module's previous release (phosphor_add_control_module_metadata's MODULE_ANCHORS_FILE), which holds each page's anchors, its anchors version and the versions of its named extension points.

◆ setResultTimeoutMs()

void PhosphorControl::ModuleTestHost::setResultTimeoutMs ( int ms)

How long to wait for a domain's applyResult or discardResult.

Zero or negative restores DefaultResultTimeoutMs.

◆ setStagingDirectory()

void PhosphorControl::ModuleTestHost::setStagingDirectory ( const QString & directory)

Where run() stages its copies: a fresh directory <directory>/module-test-XXXXXX/, removed when run() returns, whose control/ holds the module as module.so and the target modules as target-000.so onwards, whatever their files are called.

A relative directory is taken against the working directory of run(). Default: QDir::tempPath(). Pick a directory on a filesystem that allows executing libraries when /tmp is mounted noexec. A module that finds its own libraries through an $ORIGIN rpath needs them reachable from that copy, or an absolute rpath.

Member Data Documentation

◆ DefaultResultTimeoutMs

int PhosphorControl::ModuleTestHost::DefaultResultTimeoutMs = 2000
staticconstexpr

The documentation for this class was generated from the following file: