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

.github/CODEOWNERS

@@ -1,4 +1,4 @@
-* @Pycord-Development/pycord-next-contributors 
+* @Pycord-Development/pycord-next-contributors
 
 /.github @Lulalaby
 /crowdin.yml @Pycord-Development/maintain-translations

.github/workflows/lib-checks.yml

@@ -48,6 +48,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"
@@ -93,3 +94,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/utils/__init__.py

@@ -46,12 +46,10 @@
     raw_role_mentions,
     remove_markdown,
     escape_markdown,
+    DISCORD_EPOCH,
     UNICODE_EMOJIS,
 )
 
-DISCORD_EPOCH = 1420070400000
-
-
 __all__ = (
     "oauth_url",
     "snowflake_time",
@@ -69,6 +67,7 @@
     "basic_autocomplete",
     "Undefined",
     "MISSING",
+    "DISCORD_EPOCH",
     "UNICODE_EMOJIS",
 )
 

discord/utils/private.py

@@ -26,7 +26,6 @@
     Union,
     Coroutine,
     Awaitable,
-    reveal_type,
     Generic,
     Sequence,
     Iterator,

pyproject.toml

@@ -69,11 +69,17 @@ docs = [
 dev = [
     "codespell==2.4.1",
     "coverage~=7.8",
-    "mypy~=1.17.1",
-    "pre-commit==4.3.0",
-    "pytest~=8.4.1",
-    "pytest-asyncio~=0.26.0",
-    "python-dotenv>=1.1.1",
+    "mypy~=1.15.0",
+    "pre-commit==4.2.0",
+    "ruff>=0.11.9",
+    "tox>=4.27.0",
+    "tox-gh>=1.5.0",
+    "tox-uv>=1.26.1",
+]
+
+test = [# Not in `dev` becuase we use tox for testing. Tox will install these dependencies.
+    "pytest~=8.3.5",
+    "pytest-asyncio~=0.24.0",
     "ruff>=0.11.9",
 ]
 ci = [
@@ -320,3 +326,19 @@ ignore_errors = true
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+
+[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_find_util.py

@@ -0,0 +1,90 @@
+"""
+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
+from discord.utils import find
+
+
+def is_even(x):
+    return x % 2 == 0
+
+
+@pytest.mark.parametrize(
+    ("seq", "predicate", "expected"),
+    [
+        ([], lambda x: True, None),
+        ([1, 2, 3], lambda x: x > 3, None),
+        ([1, 2, 3], lambda x: x == 1, 1),
+        ([1, 2, 3], lambda x: x == 2, 2),
+        ("abc", lambda c: c == "b", "b"),
+        ((10, 20, 30), lambda x: x == 30, 30),
+        ([None, False, 0], lambda x: x is None, None),
+        ([1, 2, 3, 4], is_even, 2),
+    ],
+)
+def test_find_basic_parametrized(seq, predicate, expected):
+    result = find(predicate, seq)
+    if expected is None:
+        assert result is None
+    else:
+        assert result == expected
+
+
+def test_find_with_truthy_non_boolean_predicate():
+    seq = [2, 4, 5, 6]
+    result = find(lambda x: x % 2, seq)
+    assert result == 5
+
+
+def test_find_on_generator_and_stop_early():
+    def bad_gen():
+        yield "first"
+        raise RuntimeError("should not be reached")
+
+    assert find(lambda x: x == "first", bad_gen()) == "first"
+
+
+def test_find_does_not_evaluate_rest():
+    calls = []
+
+    def predicate(x):
+        calls.append(x)
+        return x == "stop"
+
+    seq = ["go", "stop", "later"]
+    result = find(predicate, seq)
+    assert result == "stop"
+    assert calls == ["go", "stop"]
+
+
+def test_find_with_set_returns_first_iterated_element():
+    data = {"a", "b", "c"}
+    result = find(lambda x: x in data, data)
+    assert result in data
+
+
+def test_find_none_predicate():
+    seq = [42, 43, 44]
+    result = find(lambda x: True, seq)
+    assert result == 42

tests/test_format_dt.py

@@ -0,0 +1,70 @@
+"""
+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 datetime
+import random
+import pytest
+from discord.utils import format_dt
+
+# Fix seed so that time tests are reproducible
+random.seed(42)
+
+ALL_STYLES = ["t", "T", "d", "D", "f", "F", "R", None]
+
+DATETIME_CASES = [
+    (datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=datetime.timezone.utc), 0),
+    (datetime.datetime(2000, 2, 29, 12, 0, 0, tzinfo=datetime.timezone.utc), 951825600),
+    (datetime.datetime(1999, 12, 31, 23, 59, 59, tzinfo=datetime.timezone.utc), 946684799),
+    (datetime.datetime(2023, 1, 2, 3, 4, 5, tzinfo=datetime.timezone.utc), 1672628645),
+    (datetime.datetime(2050, 6, 15, 7, 30, 0, tzinfo=datetime.timezone.utc), 2538891000),
+]
+
+
+def random_time():
+    return datetime.time(
+        random.randint(0, 23),
+        random.randint(0, 59),
+        random.randint(0, 59),
+    )
+
+
+@pytest.mark.parametrize(("dt", "expected_ts"), DATETIME_CASES)
+@pytest.mark.parametrize("style", ALL_STYLES)
+def test_format_dt_formats_datetime(dt, expected_ts, style):
+    if style is None:
+        expected = f"<t:{expected_ts}>"
+    else:
+        expected = f"<t:{expected_ts}:{style}>"
+    result = format_dt(dt, style=style)
+    assert result == expected
+
+
+@pytest.mark.parametrize("style", ALL_STYLES)
+def test_format_dt_formats_time_equivalence(style):
+    tm = random_time()
+    today = datetime.datetime.now().date()
+    result_time = format_dt(tm, style=style)
+    dt = datetime.datetime.combine(today, tm)
+    result_dt = format_dt(dt, style=style)
+    assert result_time == result_dt