The scripts in tools/ run the same checks as the analyze-test GitHub Actions workflow, so a local run and a CI run agree on what passes.
Run them from the root of an extension repository, after sourcing its .devenv:
source .devenv
verify.sh
.devenv puts $WEEWX_TOOL_PATH on PATH, so the scripts can be run by name.
The environment check and the test suites can be run on more than one interpreter, one --python per pyenv version, so the oldest and the newest the project supports are covered in a single pass:
verify.sh --python 3.9.13 --python 3.15.2
Only the steps whose result depends on the interpreter are repeated. lint.sh and the other static checks run once, as the workflow lints a single matrix cell. The versions must already be installed in pyenv; a prefix such as 3.9 resolves to the installed version.
Platforms
The scripts run on Linux, which is what CI uses, and on macOS. They are written for bash 3.2, the /bin/bash macOS ships, and for the utilities both systems provide, so they need neither Homebrew’s bash nor coreutils.
The mosquitto broker is the one macOS difference: Homebrew installs it into /opt/homebrew/sbin, which it keeps off PATH, and the integration tests skip themselves without the binary. Add it:
export PATH="/opt/homebrew/sbin:$PATH"
checkenv.sh reports that binary as missing, so a skipped suite does not pass unnoticed.
The e2e suite uses the default port, so it needs a broker at localhost:1883; brew services start mosquitto on macOS. checkenv.sh reports that one too, when the e2e suite is configured.
tagversions.sh takes its version order from git and maps the releases with awk, and watch*.sh poll with find, so neither needs GNU sort or inotifywait.
Scripts
| Script | Does | Corresponding CI step |
|---|---|---|
verify.sh | Runs checkenv.sh, lint.sh, actionlint.sh, refs.sh, configs.sh, commonrepos.sh, and alltests.sh; with --python, repeats the environment check and the tests on each version. | - |
actionlint.sh | Lints .github/workflows, downloading the pinned actionlint into tools/ on first use. | Lint the workflows |
refs.sh | Points the reusable workflow refs at the current major version tag, or with --check, reports the stale ones. | - |
tagversions.sh | Creates or repairs the floating vX, vX.Y, and latest tags from the release tags; --check reports drift. | - |
configs.sh | Copies the shared config files from development-tools/config; with --check, fails when a copy has drifted. | - |
commonrepos.sh | Copies the files of the shared repositories; --check reports drift. | Check the common repositories |
checkenv.sh | Verifies weewx, paho, the tools, and the brokers the integration and e2e suites need. Reports every miss at once. | Install dependencies |
lint.sh | Runs pylint and flake8 over WEEWX_LINT_PATHS, failing if either reports unless WEEWX_LINT_FAIL is 0. | Lint with pylint / flake8 |
unittests.sh | Runs bin/user/tests/unit. | Unit tests |
functests.sh | Runs bin/user/tests/func. | Function tests |
integtests.sh | Runs bin/user/tests/integ with --import-mode=append. | Integration tests |
e2etests.sh | Runs bin/user/tests/e2e. | E2E tests |
alltests.sh | Runs the suites in WEEWX_TEST_SUITES, skipping suites with no directory, and stops at the first failure. | All of the test steps |
coverage.sh | Measures unit test coverage, writes the HTML and XML reports. | Code Coverage |
cov-func.sh | The same for the function tests. | - |
watch*.sh | Re-runs a suite, and the coverage report, when its script, the module, or the tests change. | - |
runworkflow.sh | Dispatches a workflow on GitHub and watches it. | - |
configs.sh --check skips a config the repository does not carry, as the workflow’s check does, so verify.sh passes in a repository that keeps only some of them. development-tools itself is one: it keeps .flake8 at its root and the rest under config/.
actionlint.sh treats tools/actionlint as a cache, not a vendored file: it is in .gitignore, the cached binary is used only when it matches the pinned release, an actionlint on PATH stands in when nothing is cached, and otherwise the release is downloaded. Offline, the step reports and passes rather than blocking verify.sh.
Settings
The scripts read these from the environment, normally set in .devenv. tools/common.sh supplies the defaults and is sourced by every script.
| Setting | Default | Purpose |
|---|---|---|
WEEWX_MODULE_NAME | - | The module under test, e.g. mqttsubscribe. |
WEEWX_TOOL_PATH | - | This tools directory, added to PATH. |
WEEWX_PYTHONPATH | bin | PYTHONPATH for the tests. With weewx installed, bin is enough. |
WEEWX_PYENV_VERSION | - | Exported as PYENV_VERSION when set. |
WEEWX_LINT_PATHS | bin/user/${WEEWX_MODULE_NAME}.py | What lint.sh checks, the workflow’s lint-paths input. |
WEEWX_LINT_FAIL | 1 | With 0, lint.sh reports the findings without failing, the workflow’s lint-fail input. |
WEEWX_COMMON_REPOS | - | The shared repositories this repository vendors, the workflow’s common-repos input. |
WEEWX_COMMON_SRC | .. | Where the shared repositories’ sibling checkouts are. |
WEEWX_TEST_SUITES | unit func integ e2e | What alltests.sh runs. |
WEEWX_HTML | 0 | With 1, writes the HTML test reports. Needs pytest-html. |
WEEWX_RESULTS_DIR | results | Where the reports are written. |
The workflow installs weewx from PyPI, so WEEWX_PYTHONPATH only needs the checkout. Until weewx is installed, point it at a checkout as well:
if PYTHONPATH= python3 -c 'import weewx' >/dev/null 2>&1; then
export WEEWX_PYTHONPATH=bin
else
export WEEWX_PYTHONPATH=bin:../weewx/src
fi
plugin-loopdata also adds the station’s user package (~/weewx-data/bin), which provides the extensions it depends on.
Shared config files
.pylintrc, .pylintrc-tests, .flake8, .coveragerc, .codacy.yaml, and requirements.txt are the same in every extension repository. The canonical copies live in development-tools/config:
configs.sh # copy them into this repository
configs.sh --check # report the ones that differ
verify.sh runs the check, and the analyze-test workflow compares the repository’s copies with config-ref (default v6) so a stale copy cannot reach CI.
The tests are linted as well, with .pylintrc-tests, which turns off the conventions that tests legitimately break (docstrings, naming, mocks, complexity). .codacy.yaml keeps Codacy from re-linting the tests with its own defaults. lint.sh covers bin/user/tests by default; set WEEWX_TEST_LINT_PATHS='' to skip it.
Shared common repositories
A module shared by several extensions, such as mqttcommon.py for the weewx-mqtt ones, lives in its own repository and is copied in rather than edited. The extensions still ship the copy (their install.py lists it), so the file stays in each repository and is pulled from the source of truth:
commonrepos.sh # copy the shared files in
commonrepos.sh --check # report the ones that differ
commonrepos.sh reads WEEWX_COMMON_REPOS (the same <url> <ref> lines as the workflow’s common-repos input) and looks for sibling checkouts under WEEWX_COMMON_SRC (default ..); set that to point elsewhere, for example to test an uncommitted change against a consumer. Each repository lists its files in its own common-files.txt. verify.sh runs the check, and the analyze-test workflow compares the copies at the declared ref; a repository that declares nothing is skipped.
Floating version tags
The versioning workflow keeps vX, vX.Y, and latest in step with each release. To backfill a repository or repair drift, create the tags from the releases already in the checkout:
git fetch --tags
tagversions.sh --check # report missing or stale tags
tagversions.sh --push # write the tags locally and force-update origin
Only final vX.Y.Z releases are considered; prereleases are ignored. --no-latest leaves latest alone. The script is only needed for the initial backfill or to repair drift; the workflow maintains the tags after each release.
Outputs
Reports go to WEEWX_RESULTS_DIR, the way CI archives them:
results/pylint.txt,results/pylint-tests.txtresults/flake8.txt,results/flake8-tests.txtresults/unittests.html,results/functests.html,results/integtests.html,results/e2etests.html(withWEEWX_HTML=1)results/coverage/index.htmlcoverage.xmlin the repository root, for the coverage providers
Add results/ and coverage.xml to the repository’s .gitignore.
What is not local
The matrix workflow also runs other Python versions, other weewx versions, and a paho-mqtt==1.6.1 job. Those need the workflow itself; use ACT or runworkflow.sh for them.