Fix integration tests (#6724)

This PR tightens the integration test workflow so CI runs the
dependency-heavy checks that are usually skipped in local environments.

### What changed

- Install the system packages and Poetry extras needed by
integration-only coverage, including ffmpeg/ffprobe,
ImageMagick/Pillow-backed art resizing, chroma, docs, replaygain,
reflink, lyrics, and related plugin dependencies.
- Run `poe docs` before `poe test` in the integration workflow and set
`LYRICS_UPDATED=1` so lyrics tests are included in CI.
- Centralize CI detection in `beets.test.helper.RUNNING_IN_CI` and reuse
shared import/program checks across test collection and helpers.
- Keep dependency-heavy tests strict in the beetbox GitHub Actions
environment, while skipping them locally when optional tools/modules are
unavailable.
- Mark ffprobe-, artresizer-, chroma-, pandoc-, and completion-related
cases with focused availability gates so local test runs fail less often
for missing optional dependencies.
- Update docs link-check ignores and stale documentation URLs so `poe
check-docs-links` is less noisy in CI.

Author: snejus

.github/workflows/integration_test.yaml

@@ -19,13 +19,30 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
           cache: poetry
 
+      - name: Install system dependencies
+        run: |
+          sudo apt update
+          sudo apt install --yes --no-install-recommends \
+            ffmpeg \
+            gobject-introspection \
+            gstreamer1.0-plugins-base \
+            imagemagick \
+            libcairo2-dev \
+            libgirepository-2.0-dev \
+            mp3gain \
+            pandoc \
+            python3-gst-1.0
+
       - name: Install dependencies
-        run: poetry install
+        run: poetry install --extras=autobpm --extras=discogs --extras=lyrics --extras=docs --extras=replaygain --extras=reflink --extras=fetchart --extras=chroma --extras=sonosupdate
 
       - name: Test
         env:
           INTEGRATION_TEST: 1
-        run: poe test
+          LYRICS_UPDATED: 1
+        run: |
+          poe docs
+          poe test
 
       - name: Check external links in docs
         run: poe check-docs-links
@@ -34,7 +51,7 @@ jobs:
         if: ${{ failure() }}
         env:
           ZULIP_BOT_CREDENTIALS: ${{ secrets.ZULIP_BOT_CREDENTIALS }}
-        run: |
+        run: |-
           if [ -z "${ZULIP_BOT_CREDENTIALS}" ]; then
             echo "Skipping notify, ZULIP_BOT_CREDENTIALS is unset"
             exit 0

beets/test/helper.py

@@ -25,6 +25,7 @@
 
 from __future__ import annotations
 
+import importlib.util
 import os
 import os.path
 import shutil
@@ -34,7 +35,7 @@
 from contextlib import contextmanager
 from dataclasses import dataclass
 from enum import Enum
-from functools import cached_property
+from functools import cache, cached_property
 from pathlib import Path
 from tempfile import gettempdir, mkdtemp, mkstemp
 from typing import TYPE_CHECKING, Any, ClassVar
@@ -61,6 +62,8 @@
 if TYPE_CHECKING:
     from requests_mock.mocker import Mocker
 
+RUNNING_IN_CI = os.environ.get("GITHUB_ACTIONS") == "true"
+
 
 class LogCapture(logging.Handler):
     def __init__(self):
@@ -98,6 +101,11 @@ def has_program(cmd, args=["--version"]):
         return True
 
 
+@cache
+def is_importable(modname: str) -> bool:
+    return bool(importlib.util.find_spec(modname))
+
+
 def check_reflink_support(path: str) -> bool:
     try:
         import reflink
@@ -107,6 +115,15 @@ def check_reflink_support(path: str) -> bool:
     return reflink.supported_at(path)
 
 
+NEEDS_REFLINK = pytest.mark.skipif(
+    not check_reflink_support(gettempdir()), reason="need reflink"
+)
+NEEDS_FFPROBE = pytest.mark.skipif(
+    not has_program("ffprobe") and not RUNNING_IN_CI,
+    reason="ffprobe (ffmpeg) is not available",
+)
+
+
 class ConfigMixin:
     @cached_property
     def config(self) -> beets.IncludeLazyConfig:
@@ -122,11 +139,6 @@ def config(self) -> beets.IncludeLazyConfig:
         return config
 
 
-NEEDS_REFLINK = pytest.mark.skipif(
-    not check_reflink_support(gettempdir()), reason="need reflink"
-)
-
-
 class RunMixin:
     lib: Library
 

docs/conf.py

@@ -74,7 +74,14 @@
     r"https://[^/]*fanart\.tv/",  # blocks requests
     r"https://[^/]*fandom\.com/",  # blocks requests
     r"https://imgur\.com/",  # not accessible from the UK
-    r"https://www.discogs.com/settings/developers",  # requires login
+    r"https://(www\.)?discogs.com.*",  # blocks requests
+    r"https://essentia.upf.edu/",  # times out in CI
+    r"https://flask.palletsprojects.com.*",  # times out in CI
+    r"https://search.worldcat.org.*",  # blocks requests
+    r"https://tidal.com.*",  # blocks requests
+    r"https://www.tekstowo.pl/",  # blocks requests
+    r"https://www.gnu.org.*",  # sometimes unreachable
+    r"https://www.nongnu.org.*",  # sometimes unreachable
 ]
 
 # Options for HTML output

docs/faq.rst

@@ -171,7 +171,7 @@ follow these guidelines when reporting an issue:
 
 - Most importantly: if beets is crashing, please `include the traceback
   <https://imgur.com/jacoj>`__. Tracebacks can be more readable if you put them
-  in a pastebin (e.g., `Gist <https://gist.github.com/>`__ or `Hastebin
+  in a pastebin (e.g., `Gist <https://gist.github.com/discover>`__ or `Hastebin
   <https://www.toptal.com/developers/hastebin>`__), especially when
   communicating over IRC.
 - Turn on beets' debug output (using the -v option: for example, ``beet -v

docs/plugins/fetchart.rst

@@ -221,7 +221,7 @@ To use the google image search backend you need to `register for a Google API
 key`_. Set the ``google_key`` configuration option to your key, then add
 ``google`` to the list of sources in your configuration.
 
-.. _register for a google api key: https://console.developers.google.com.
+.. _register for a google api key: https://console.cloud.google.com/apis/credentials
 
 Optionally, you can `define a custom search engine`_. Get your search engine's
 token and use it for your ``google_engine`` configuration option. The default

docs/plugins/lyrics.rst

@@ -188,8 +188,8 @@ Activate Google Custom Search
 -----------------------------
 
 You need to `register for a Google API key
-<https://console.developers.google.com/>`__. Set the ``google_API_key``
-configuration option to your key.
+<https://console.cloud.google.com/apis/credentials>`__. Set the
+``google_API_key`` configuration option to your key.
 
 Then add ``google`` to the list of sources in your configuration (or use default
 list, which includes it as long as you have an API key). If you use default

test/conftest.py

@@ -1,22 +1,16 @@
-import importlib.util
 import inspect
 import os
-from functools import cache
 
 import pytest
 
 from beets.autotag import Distance
 from beets.dbcore.query import Query
 from beets.test._common import DummyIO
-from beets.test.helper import ConfigMixin
+from beets.test.helper import RUNNING_IN_CI, ConfigMixin
+from beets.test.helper import is_importable as check_import
 from beets.util import cached_classproperty
 
 
-@cache
-def _is_importable(modname: str) -> bool:
-    return bool(importlib.util.find_spec(modname))
-
-
 def skip_marked_items(items: list[pytest.Item], marker_name: str, reason: str):
     for item in (i for i in items if i.get_closest_marker(marker_name)):
         test_name = item.nodeid.split("::", 1)[-1]
@@ -41,15 +35,15 @@ def pytest_collection_modifyitems(
             force_ci = marker.kwargs.get("force_ci", True)
             if (
                 force_ci
-                and os.environ.get("GITHUB_ACTIONS") == "true"
+                and RUNNING_IN_CI
                 # only apply this to our repository, to allow other projects to
                 # run tests without installing all dependencies
                 and os.environ.get("GITHUB_REPOSITORY", "") == "beetbox/beets"
             ):
                 continue
 
             modname = marker.args[0]
-            if not _is_importable(modname):
+            if not check_import(modname):
                 test_name = item.nodeid.split("::", 1)[-1]
                 item.add_marker(
                     pytest.mark.skip(
@@ -134,4 +128,4 @@ def io(
 def is_importable():
     """Fixture that provides a function to check if a module can be imported."""
 
-    return _is_importable
+    return check_import

test/plugins/test_art.py

@@ -31,18 +31,28 @@
 from beets.autotag import AlbumInfo, AlbumMatch, Distance
 from beets.library import Album
 from beets.test import _common
-from beets.test.helper import FetchImageHelper, TestHelper
+from beets.test.helper import (
+    RUNNING_IN_CI,
+    FetchImageHelper,
+    TestHelper,
+    has_program,
+    is_importable,
+)
 from beets.util import clean_module_tempdir, syspath
 from beets.util.artresizer import ArtResizer
 from beetsplug import fetchart
 
-logger = logging.getLogger("beets.test_art")
-
-
 if TYPE_CHECKING:
     from collections.abc import Iterator, Sequence
     from unittest.mock import MagicMock
 
+logger = logging.getLogger("beets.test_art")
+
+REQUIRES_ARTRESIZER = pytest.mark.skipif(
+    not (has_program("magick") or is_importable("PIL")) and not RUNNING_IN_CI,
+    reason="requires ImageMagick or Pillow",
+)
+
 
 class Settings(fetchart.FetchArtPlugin):
     """Used to pass settings to the ArtSources when the plugin isn't fully
@@ -992,6 +1002,7 @@ def get_album_art(self):
         return self.plugin.art_for_album(Album(), [""], True)
 
 
+@REQUIRES_ARTRESIZER
 class TestAlbumArtOperationConfiguration(AlbumArtOperationMixin):
     """Check that scale & filesize configuration is respected.
 
@@ -1033,6 +1044,7 @@ def test_enforce_ratio_with_percent_margin(self):
         assert self.get_album_art()
 
 
+@REQUIRES_ARTRESIZER
 class TestAlbumArtPerformOperation(AlbumArtOperationMixin):
     """Test that the art is resized and deinterlaced if necessary."""
 

test/plugins/test_chroma.py

@@ -20,7 +20,8 @@
 from beets.autotag import AlbumInfo, TrackInfo
 from beets.library import Item
 from beets.test.helper import ImportHelper, IOMixin, PluginMixin
-from beetsplug import chroma
+
+chroma = pytest.importorskip("beetsplug.chroma", exc_type=ImportError)
 
 TEST_TITLE_1 = "TEST_TITLE_1"
 TEST_TITLE_2 = "TEST_TITLE_2"

test/plugins/test_embedart.py

@@ -29,6 +29,7 @@
 from beets.exceptions import UserError
 from beets.test import _common
 from beets.test.helper import (
+    NEEDS_FFPROBE,
     FetchImageHelper,
     ImportHelper,
     IOMixin,
@@ -308,6 +309,7 @@ def test_embed_art_from_url_not_image(
         mediafile = MediaFile(syspath(item.path))
         assert not mediafile.images
 
+    @NEEDS_FFPROBE
     def test_clearart_on_import_disabled(self):
         file_path = self.create_mediafile_fixture(
             images=["jpg"], target_dir=self.import_path
@@ -320,6 +322,7 @@ def test_clearart_on_import_disabled(self):
         item = self.lib.items()[0]
         assert MediaFile(os.path.join(item.path)).images
 
+    @NEEDS_FFPROBE
     def test_clearart_on_import_enabled(self):
         file_path = self.create_mediafile_fixture(
             images=["jpg"], target_dir=self.import_path