Audit test conventions and improve regression setup and assertions

AGENTS.md

@@ -82,7 +82,8 @@ uv run --env-file .env pytest -n 1 tests/pyathena/test_cursor.py -v
 #### Test Conventions
 
 - **Class-based tests** for integration tests that use fixtures (cursors, engines): `class TestCursor:` with methods like `def test_fetchone(self, cursor):`
-- **Standalone functions** for unit tests of pure logic (converters, parsers, utils): `def test_to_struct_json_formats(input_value, expected):`
+- **Standalone functions** are the default for stateless helpers: `def test_to_struct_json_formats(input_value, expected):`. Unit tests may use a class when it groups the behavior of one object or meaningful common setup, such as `TestTypeSignatureParser`.
+- Function-oriented utility tests may remain standalone even when they use AWS fixtures, as in `tests/pyathena/pandas/test_util.py`. Fixture use alone does not determine the grouping.
 - Test file naming mirrors source: `pyathena/parser.py` → `tests/pyathena/test_parser.py`
 - **Fixtures**: Cursor/engine fixtures are defined in `conftest.py` and injected by name (e.g., `cursor`, `engine`, `async_cursor`). Use `indirect=True` parametrization to pass connection options:
 
@@ -93,6 +94,9 @@ uv run --env-file .env pytest -n 1 tests/pyathena/test_cursor.py -v
   ```
 
 - **Parametrize** with `@pytest.mark.parametrize(("input", "expected"), [...])` for data-driven tests
+- Keep parameter definitions declarative. Build mocks, configured result sets, and one-shot readers during fixture setup or test execution. Pure values and framework type/expression objects may be constructed in parameter definitions.
+- Make expected values independent of the implementation under test. A library comparison is appropriate when matching that library is the contract; describe intentional differences with explicit expected values.
+- Preserve test IDs, parameter coverage, marks, fixture scopes, and resource cleanup when reorganizing tests. SQLAlchemy compliance tests retain their upstream class and plugin conventions and applicable attribution.
 - **Integration tests** (need AWS) use cursor/engine fixtures with real Athena queries; **unit tests** (no AWS) call functions directly with test data
 
 ### Markdown Lint

docs/testing.md

@@ -128,6 +128,38 @@ uv run --env-file .env pytest -n 1 tests/pyathena/test_cursor.py -v
 ```
 
 A targeted run helps during development but does not replace other coverage required by the affected callers or features.
+
+(testing-offline)=
+
+### Run self-contained tests offline
+
+The pandas and Polars result-set modules have self-contained tests that can run without AWS access when the session hooks are excluded.
+Reuse the `.env` file described in the AWS environment section if it is already configured.
+For an offline-only setup, create a gitignored `.env` file in the repository root with these placeholder values:
+
+```ini
+AWS_DEFAULT_REGION=us-east-1
+AWS_ATHENA_S3_STAGING_DIR=s3://pyathena-offline-placeholder/
+AWS_ATHENA_WORKGROUP=offline
+AWS_ATHENA_SPARK_WORKGROUP=offline
+AWS_EC2_METADATA_DISABLED=true
+```
+
+After `just lint`, load `.env` and run:
+
+```bash
+uv run --env-file .env pytest --noconftest -p no:rerunfailures -q \
+  tests/pyathena/pandas/test_result_set.py \
+  tests/pyathena/polars/test_result_set.py
+```
+
+The four AWS configuration values are required by `tests/__init__.py`, which pytest still imports with `--noconftest`.
+The offline-only `.env` example disables EC2 metadata to prevent implicit credential lookup through that service.
+`--noconftest` excludes the AWS session hooks and fixtures; disabling the rerun plugin also avoids its local socket setup in restricted environments.
+Use this invocation only for self-contained modules; integration tests need their normal fixtures and a real AWS environment.
+
+### SQLAlchemy suites
+
 The SQLAlchemy compliance suites under `tests/sqlalchemy/` run with different configurations: use `sqla` for synchronous dialects and `sqla-async` for native asyncio dialects.
 They do not run PyAthena's own dialect regression tests under `tests/pyathena/sqlalchemy/` and `tests/pyathena/aio/sqlalchemy/`.
 Run the relevant PyAthena tests too, either through `just test pyathena` or a focused selection during development:
@@ -136,17 +168,39 @@ Run the relevant PyAthena tests too, either through `just test pyathena` or a fo
 uv run --env-file .env pytest -n 1 tests/pyathena/sqlalchemy/ tests/pyathena/aio/sqlalchemy/ -v
 ```
 
+### Run tox
+
 To invoke the configured tox environments locally:
 
 ```bash
 uv run --env-file .env just tox
 ```
 
+### Record results
+
 Record the tested commit, Python and relevant dependency versions, exact commands, and results in the pull request.
 Include failed and skipped tests and explain any unrun coverage.
 Separate real AWS results from mock-based tests and static checks.
 Sanitize logs before sharing them.
 
+## Organize tests
+
+Group cursor and engine integration tests in classes, and use standalone functions for stateless helpers.
+A unit-test class can group the behavior of one object or common setup, as in `TestTypeSignatureParser`.
+Function-oriented utility tests can remain standalone when they use AWS fixtures; `tests/pyathena/pandas/test_util.py` follows this pattern.
+SQLAlchemy compliance tests retain the classes, decorators, and plugin setup required by the upstream suite.
+Preserve attribution for adapted tests as documented in `NOTICE`.
+
+Parameter definitions should make inputs, options, and expected behavior visible.
+Build mocks, configured result sets, and one-shot readers during fixture setup or test execution.
+Pure values and framework type or expression objects can be constructed in parameters.
+Choose explicit parameter IDs when generated IDs obscure the case, and keep existing IDs, marks, and fixture scopes when reorganizing tests.
+
+Use literal expected values for contract-specific behavior.
+A library comparison is useful when matching that library is the contract, such as joining pandas chunks versus reading the whole file.
+Express intentional differences directly rather than recreating the implementation in the expected-value builder.
+Retain dtype and schema checks, option contexts, resource cleanup, and equivalent synchronous and asynchronous scenarios where applicable.
+
 ## GitHub Actions
 
 The Test workflow runs for pull requests that change files other than `docs/` and Markdown.

tests/pyathena/filesystem/test_s3.py

@@ -4819,9 +4819,26 @@ def test_find_withdirs(self, fs):
         result = fs.find(dir_, withdirs=False)
         assert len(result) == 4  # Only files
 
-    def test_du(self):
-        # TODO
-        pass
+    def test_du(self, fs):
+        """Disk usage reports file sizes, their total, and the requested depth."""
+        directory = (
+            f"s3://{ENV.s3_staging_bucket}/{ENV.s3_staging_key}{ENV.schema}/filesystem/test_du"
+        )
+        first = f"{directory}/first"
+        second = f"{directory}/nested/second"
+        try:
+            fs.pipe_file(first, b"abc")
+            fs.pipe_file(second, b"12345")
+            assert fs.du(directory) == 8
+            assert fs.du(directory, total=False) == {
+                fs._strip_protocol(first): 3,
+                fs._strip_protocol(second): 5,
+            }
+            assert fs.du(directory, maxdepth=1) == 3
+            assert fs.du(first) == 3
+        finally:
+            with contextlib.suppress(FileNotFoundError):
+                fs.rm(directory, recursive=True)
 
     def test_glob(self, fs):
         dir_ = f"s3://{ENV.s3_staging_bucket}/{ENV.s3_staging_key}{ENV.schema}/filesystem/test_glob"

tests/pyathena/filesystem/test_s3_async.py

@@ -1775,9 +1775,25 @@ async def test_find_withdirs(self, fs):
         result = await fs._find(dir_, withdirs=False)
         assert len(result) == 4  # Only files
 
-    def test_du(self):
-        # TODO
-        pass
+    @pytest.mark.asyncio
+    async def test_du(self, fs):
+        """Disk usage reports file sizes, their total, and the requested depth."""
+        directory = f"s3://{ENV.s3_staging_bucket}/{ENV.s3_staging_key}{ENV.schema}/filesystem/test_async_du"
+        first = f"{directory}/first"
+        second = f"{directory}/nested/second"
+        try:
+            await fs._pipe_file(first, b"abc")
+            await fs._pipe_file(second, b"12345")
+            assert await fs._du(directory) == 8
+            assert await fs._du(directory, total=False) == {
+                fs._strip_protocol(first): 3,
+                fs._strip_protocol(second): 5,
+            }
+            assert await fs._du(directory, maxdepth=1) == 3
+            assert await fs._du(first) == 3
+        finally:
+            with contextlib.suppress(FileNotFoundError):
+                await fs._rm(directory, recursive=True)
 
     @pytest.mark.asyncio
     async def test_glob(self, fs):