feat: Setup a fully featured test setup and add initial tests on utils

.github/workflows/lib-checks.yml

@@ -52,6 +52,7 @@ jobs:
           uv run codespell --ignore-words-list="groupt,nd,ot,ro,falsy,BU" \
           --exclude-file=".github/workflows/codespell.yml"
   ruff:
+    if: ${{ github.event_name != 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - name: "Checkout Repository"
@@ -97,3 +98,29 @@ jobs:
         run: mkdir -p -v .mypy_cache
       - name: "Run mypy"
         run: uv run mypy --non-interactive discord/
+  tests:
+    if: ${{ github.event_name != 'schedule' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.13', '3.12', '3.11', '3.10']
+    steps:
+      - name: "Checkout Repository"
+        uses: actions/checkout@v4
+
+      - name: "Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: "Install uv"
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --no-python-downloads --group dev
+
+      - name: "Run tests"
+        run: uv run tox

discord/enums.py

@@ -28,7 +28,9 @@
 import types
 from enum import Enum as EnumBase
 from enum import IntEnum
-from typing import Any, Self, TypeVar, Union
+from typing import Any, TypeVar, Union
+
+from typing_extensions import Self
 
 E = TypeVar("E", bound="Enum")
 

discord/utils/__init__.py

@@ -26,6 +26,7 @@
 from __future__ import annotations
 
 from .public import (
+    DISCORD_EPOCH,
     MISSING,
     UNICODE_EMOJIS,
     Undefined,
@@ -44,9 +45,6 @@
     utcnow,
 )
 
-DISCORD_EPOCH = 1420070400000
-
-
 __all__ = (
     "oauth_url",
     "snowflake_time",
@@ -63,5 +61,6 @@
     "basic_autocomplete",
     "Undefined",
     "MISSING",
+    "DISCORD_EPOCH",
     "UNICODE_EMOJIS",
 )

discord/utils/private.py

@@ -412,7 +412,21 @@ async def sane_wait_for(futures: Iterable[Awaitable[T]], *, timeout: float) -> s
     return done
 
 
-class SnowflakeList(array.array[int]):
+# array.array is generic only since Python 3.12
+# ref: https://docs.python.org/3/whatsnew/3.12.html#array
+# We use the method suggested by mypy
+# ref: https://mypy.readthedocs.io/en/stable/runtime_troubles.html#using-classes-that-are-generic-in-stubs-but-not-at-runtime
+
+if TYPE_CHECKING:
+    SnowflakeListBase = array.array[int]
+else:
+    if sys.version_info >= (3, 12):
+        SnowflakeListBase = array.array[int]
+    else:
+        SnowflakeListBase = array.array
+
+
+class SnowflakeList(SnowflakeListBase):
     """Internal data storage class to efficiently store a list of snowflakes.
 
     This should have the following characteristics:
@@ -426,10 +440,6 @@ class SnowflakeList(array.array[int]):
 
     __slots__ = ()
 
-    if TYPE_CHECKING:
-
-        def __init__(self, data: Iterable[int], *, is_sorted: bool = False): ...
-
     def __new__(cls, data: Iterable[int], *, is_sorted: bool = False):
         return super().__new__(cls, "Q", data if is_sorted else sorted(data))
 

discord/utils/public.py

@@ -546,12 +546,11 @@ def find(predicate: Callable[[T], Any], seq: Iterable[T]) -> T | None:
 
 
 try:
-    with importlib.resources.files(__package__).joinpath("../emojis.json").open(encoding="utf-8") as f:
-        EMOJIS_MAP = json.load(f)
+    with importlib.resources.files(__package__).joinpath("../emojis.json").open(encoding="utf-8") as f:  # pyright: ignore[reportArgumentType] # __package__ will always be discord.utils
+        EMOJIS_MAP: dict[str, str] = json.load(f)
 except FileNotFoundError:
     _log.debug(
         "Couldn't find emojis.json. Is the package data missing? Discord emojis names will not work.",
     )
-
-EMOJIS_MAP = {}
+    EMOJIS_MAP = {}  # pyright: ignore[reportConstantRedefinition]
 UNICODE_EMOJIS = set(EMOJIS_MAP.values())

pyproject.toml

@@ -71,10 +71,16 @@ dev = [
     "coverage~=7.8",
     "mypy~=1.18.1",
     "pre-commit==4.3.0",
-    "pytest~=8.4.1",
-    "pytest-asyncio~=0.26.0",
     "python-dotenv>=1.1.1",
-    "ruff>=0.11.9",
+    "ruff>=0.12.12",
+    "tox>=4.27.0",
+    "tox-gh>=1.5.0",
+    "tox-uv>=1.26.1",
+]
+
+test = [# Not in `dev` because we use tox for testing. Tox will install these dependencies.
+    "pytest~=8.3.5",
+    "pytest-asyncio~=0.24.0",
 ]
 ci = [
     "pygithub>=2.7.0",
@@ -304,3 +310,20 @@ ignore_errors = true
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.tox]
+requires = ["tox>=4"]
+env_list = ["3.13", "3.12", "3.11", "3.10"]
+
+[tool.tox.env_run_base]
+description = "run unit tests"
+commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]
+dependency_groups = ["test"]
+
+# GitHub actions
+[tool.tox.gh.python]
+"3.13" = ["3.13"]
+"3.12" = ["3.12"]
+"3.11" = ["3.11"]
+"3.10" = ["3.10"]

tests/test_basic_bot.py

@@ -0,0 +1,50 @@
+"""
+The MIT License (MIT)
+
+Copyright (c) 2021-present Pycord Development
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import pytest
+
+import discord
+
+
+@pytest.mark.asyncio
+async def test_bot_login_failure_login():
+    bot = discord.Bot()
+
+    with pytest.raises(discord.LoginFailure):
+        await bot.login("invalid_token")
+
+
+@pytest.mark.asyncio
+async def test_bot_login_failure_start():
+    bot = discord.Bot()
+
+    with pytest.raises(discord.LoginFailure):
+        await bot.start("invalid_token")
+
+
+def test_bot_login_failure_run():
+    bot = discord.Bot()
+
+    with pytest.raises(discord.LoginFailure):
+        bot.run("invalid_token")

tests/helpers.py → tests/test_emojis_mapping.py

@@ -1,7 +1,6 @@
 """
 The MIT License (MIT)
 
-Copyright (c) 2015-2021 Rapptz
 Copyright (c) 2021-present Pycord Development
 
 Permission is hereby granted, free of charge, to any person obtaining a
@@ -23,10 +22,8 @@
 DEALINGS IN THE SOFTWARE.
 """
 
-from typing import TypeVar
+from discord.utils import UNICODE_EMOJIS
 
-V = TypeVar("V")
 
-
-async def coroutine(val: V) -> V:
-    return val
+def test_emoji_mapping_len():
+    assert len(UNICODE_EMOJIS) > 0, "No unicode emojis loaded"

tests/test_find_util.py

@@ -0,0 +1,131 @@
+"""
+The MIT License (MIT)
+
+Copyright (c) 2021-present Pycord Development
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator
+from typing import Literal, TypeVar
+
+import pytest
+from typing_extensions import TypeIs
+
+from discord.utils import find
+
+T = TypeVar("T")
+
+
+def is_even(x: int) -> bool:
+    return x % 2 == 0
+
+
+def always_true(_: object) -> bool:
+    return True
+
+
+def greater_than_3(x: int) -> bool:
+    return x > 3
+
+
+def equals_1(x: int) -> TypeIs[Literal[1]]:
+    return x == 1
+
+
+def equals_2(x: int) -> TypeIs[Literal[2]]:
+    return x == 2
+
+
+def equals_b(c: str) -> TypeIs[Literal["b"]]:
+    return c == "b"
+
+
+def equals_30(x: int) -> TypeIs[Literal[30]]:
+    return x == 30
+
+
+def is_none_pred(x: object) -> TypeIs[None]:
+    return x is None
+
+
+@pytest.mark.parametrize(
+    ("seq", "predicate", "expected"),
+    [
+        ([], always_true, None),
+        ([1, 2, 3], greater_than_3, None),
+        ([1, 2, 3], equals_1, 1),
+        ([1, 2, 3], equals_2, 2),
+        ("abc", equals_b, "b"),
+        ((10, 20, 30), equals_30, 30),
+        ([None, False, 0], is_none_pred, None),
+        ([1, 2, 3, 4], is_even, 2),
+    ],
+)
+def test_find_basic_parametrized(
+    seq: Iterable[T],
+    predicate: Callable[[T], object],
+    expected: T | None,
+) -> None:
+    result = find(predicate, seq)
+    if expected is None:
+        assert result is None
+    else:
+        assert result == expected
+
+
+def test_find_with_truthy_non_boolean_predicate() -> None:
+    seq: list[int] = [2, 4, 5, 6]
+    result = find(lambda x: x % 2, seq)
+    assert result == 5
+
+
+def test_find_on_generator_and_stop_early() -> None:
+    def bad_gen() -> Iterator[str]:
+        yield "first"
+        raise RuntimeError("should not be reached")
+
+    assert find(lambda x: x == "first", bad_gen()) == "first"
+
+
+def test_find_does_not_evaluate_rest() -> None:
+    calls: list[str] = []
+
+    def predicate(x: str) -> bool:
+        calls.append(x)
+        return x == "stop"
+
+    seq: list[str] = ["go", "stop", "later"]
+    result = find(predicate, seq)
+    assert result == "stop"
+    assert calls == ["go", "stop"]
+
+
+def test_find_with_set_returns_first_iterated_element() -> None:
+    data: set[str] = {"a", "b", "c"}
+    result = find(lambda x: x in data, data)
+    assert result in data
+
+
+def test_find_none_predicate() -> None:
+    seq: list[int] = [42, 43, 44]
+    result = find(lambda x: True, seq)
+    assert result == 42