Implement docstrings for tests

Author: pentest-gg

tests/conftest.py

@@ -8,18 +8,22 @@
 
 
 class User(schemas.BaseUser):
+    """A base class representing an `User`."""
     first_name: str | None
 
 
 class UserCreate(schemas.BaseUserCreate):
+    """A base class representing the creation of an `User`."""
     first_name: str | None
 
 
 class UserUpdate(schemas.BaseUserUpdate):
+    """A base class representing the update of an `User`."""
     pass
 
 
 class UserOAuth(User, schemas.BaseOAuthAccountMixin):
+    """A base class representing an `User` with linked `OAuth` accounts."""
     pass
 
 
@@ -37,6 +41,11 @@ def global_moto_mock():
 
 @pytest.fixture
 def oauth_account1() -> dict[str, Any]:
+    """Return a fake `OAuth` account for testing.
+
+    Returns:
+        dict[str, Any]: A `dict` object representing the `OAuth` account.
+    """
     return {
         "oauth_name": "service1",
         "access_token": "TOKEN",
@@ -48,6 +57,11 @@ def oauth_account1() -> dict[str, Any]:
 
 @pytest.fixture
 def oauth_account2() -> dict[str, Any]:
+    """Return a fake `OAuth` account for testing.
+
+    Returns:
+        dict[str, Any]: A `dict` object representing the `OAuth` account.
+    """
     return {
         "oauth_name": "service2",
         "access_token": "TOKEN",
@@ -59,4 +73,9 @@ def oauth_account2() -> dict[str, Any]:
 
 @pytest.fixture
 def user_id() -> UUID4:
+    """Return a randomly generated UUIDv4.
+
+    Returns:
+        UUID4: The random UUIDv4 user id.
+    """
     return uuid.uuid4()

tests/test_access_token.py

@@ -19,22 +19,55 @@
 
 
 class Base(Model):
+    """A base class representing a PynamoDB `Model`.
+
+    Args:
+        Model (_type_): The PynamoDB base class definition.
+    """
     pass
 
 
 class AccessToken(DynamoDBBaseAccessTokenTableUUID, Base):
+    """A class representing an `AccessToken` object.
+
+    Args:
+        DynamoDBBaseAccessTokenTableUUID (_type_): The underlying table object.
+        Base (_type_): The PynamoDB base class definition.
+    """
     __tablename__: str = config.get("DATABASE_TOKENTABLE_NAME") + "_test"
 
     class Meta:
+        """The required `Meta` definitions for PynamoDB.
+
+        Args:
+            table_name (str): The name of the table.
+            region (str): The AWS region string where the table should be created.
+            billing_mode (str): The billing mode to use when creating the table. \
+            Currently only supports `PAY_PER_REQUEST`.
+        """
         table_name: str = config.get("DATABASE_TOKENTABLE_NAME") + "_test"
         region: str = config.get("DATABASE_REGION")
         billing_mode: str = config.get("DATABASE_BILLING_MODE").value
 
 
 class User(DynamoDBBaseUserTableUUID, Base):
+    """A class representing a `User` obejct.
+
+    Args:
+        DynamoDBBaseUserTableUUID (_type_): The underlying table object.
+        Base (_type_): The PynamoDB base class definition.
+    """
     __tablename__: str = config.get("DATABASE_USERTABLE_NAME") + "_test"
 
     class Meta:
+        """The required `Meta` definitions for PynamoDB.
+
+        Args:
+            table_name (str): The name of the table.
+            region (str): The AWS region string where the table should be created.
+            billing_mode (str): The billing mode to use when creating the table. \
+            Currently only supports `PAY_PER_REQUEST`.
+        """
         table_name: str = config.get("DATABASE_USERTABLE_NAME") + "_test"
         region: str = config.get("DATABASE_REGION")
         billing_mode: str = config.get("DATABASE_BILLING_MODE").value
@@ -44,6 +77,17 @@ class Meta:
 async def dynamodb_access_token_db(
     user_id: UUID4,
 ) -> AsyncGenerator[DynamoDBAccessTokenDatabase[AccessToken]]:
+    """Create a new `AccessToken` Database and yield it to other tests.
+
+    Args:
+        user_id (UUID4): The user id for the default user.
+
+    Returns:
+        AsyncGenerator[DynamoDBAccessTokenDatabase[AccessToken]]: The `AccessToken` Database instance.
+
+    Yields:
+        Iterator[AsyncGenerator[DynamoDBAccessTokenDatabase[AccessToken]]]: The `AccessToken` Database instance.
+    """
     user_db = DynamoDBUserDatabase(User)
     user = await user_db.create(
         User(
@@ -65,6 +109,12 @@ async def test_queries(
     dynamodb_access_token_db: DynamoDBAccessTokenDatabase[AccessToken],
     user_id: UUID4,
 ):
+    """Test default queries to the `AccessToken` Database.
+
+    Args:
+        dynamodb_access_token_db (DynamoDBAccessTokenDatabase[AccessToken]): The database instance to use.
+        user_id (UUID4): The default user id to use.
+    """
     access_token_create = {"token": "TOKEN", "user_id": user_id}
 
     # Create
@@ -130,6 +180,12 @@ async def test_insert_existing_token(
     dynamodb_access_token_db: DynamoDBAccessTokenDatabase[AccessToken],
     user_id: UUID4,
 ):
+    """Test function that creates and saves an already existing `AccessToken`. 
+
+    Args:
+        dynamodb_access_token_db (DynamoDBAccessTokenDatabase[AccessToken]): The database instance to use.
+        user_id (UUID4): The default user id to use.
+    """
     access_token_create = {"token": "TOKEN", "user_id": user_id}
 
     token = await dynamodb_access_token_db.get_by_token(access_token_create["token"])

tests/test_misc.py

@@ -7,22 +7,38 @@
 
 
 class NotAModel:
+    """A class representing an invalid `Model`."""
     pass
 
 
 class IncompleteModel(Model):
+    """A class representing an incomplete `Model`, which misses required functions."""
     pass
 
 
 class ValidModel(Model):
+    """A class representing a valid `Model`."""
     class Meta:
+        """The required `Meta` definitions for PynamoDB.
+
+        Args:
+            table_name (str): The name of the table.
+            region (str): The AWS region string where the table should be created.
+            billing_mode (str): The billing mode to use when creating the table. \
+            Currently only supports `PAY_PER_REQUEST`.
+        """
         table_name: str = "valid_model_test"
         region: str = config.get("DATABASE_REGION")
         billing_mode: str = config.get("DATABASE_BILLING_MODE").value
 
 
 @pytest.mark.asyncio
 async def test_tables_invalid_models(monkeypatch):
+    """Test table creation on various `Model` instances.
+
+    Args:
+        monkeypatch (_type_): The `pytest` monkeypatcher which is used to modify models.
+    """
     with pytest.raises(TypeError, match="must be a subclass of Model"):
         await ensure_tables_exist(NotAModel)  # type: ignore
 
@@ -43,6 +59,11 @@ async def test_tables_invalid_models(monkeypatch):
 
 
 def test_config(monkeypatch):
+    """Test config settings and changes.
+
+    Args:
+        monkeypatch (_type_): The `pytest` monkeypatcher which is used to modify models.
+    """
     billing_mode = config.BillingMode.PAY_PER_REQUEST
     assert billing_mode.value == str(billing_mode)
 
@@ -62,6 +83,11 @@ def test_config(monkeypatch):
 
 
 def test_attributes(user_id):
+    """Test serialization and deserialization of `Attribute` instances.
+
+    Args:
+        user_id (_type_): The default user id to use for testing.
+    """
     id = GUID()
     assert id.serialize(None) is None
 

tests/test_users.py

@@ -17,13 +17,32 @@
 
 
 class Base(Model):
+    """A base class representing a PynamoDB `Model`.
+
+    Args:
+        Model (_type_): The PynamoDB base class definition.
+    """
     pass
 
 
 class User(DynamoDBBaseUserTableUUID, Base):
+    """A class representing an `User` object.
+
+    Args:
+        DynamoDBBaseUserTableUUID (_type_): The underlying table object.
+        Base (_type_): The PynamoDB base class definition.
+    """
     __tablename__: str = config.get("DATABASE_USERTABLE_NAME") + "_test"
 
     class Meta:
+        """The required `Meta` definitions for PynamoDB.
+
+        Args:
+            table_name (str): The name of the table.
+            region (str): The AWS region string where the table should be created.
+            billing_mode (str): The billing mode to use when creating the table. \
+            Currently only supports `PAY_PER_REQUEST`.
+        """
         table_name: str = config.get("DATABASE_USERTABLE_NAME") + "_test"
         region: str = config.get("DATABASE_REGION")
         billing_mode: str = config.get("DATABASE_BILLING_MODE").value
@@ -35,17 +54,42 @@ class Meta:
 
 
 class OAuthBase(Model):
+    """The base class representing `OAuth` related models.
+
+    Args:
+        Model (_type_): The PynamoDB base class definition.
+    """
     pass
 
 
 class OAuthAccount(DynamoDBBaseOAuthAccountTableUUID, OAuthBase):
+    """A class representing an `OAuthAccount` object.
+
+    Args:
+        DynamoDBBaseOAuthAccountTableUUID (_type_): The underlying table object.
+        OAuthBase (_type_): The base class for `OAuth`.
+    """
     pass
 
 
 class UserOAuth(DynamoDBBaseUserTableUUID, OAuthBase):
+    """A class representing an `UserOAuth` object.
+
+    Args:
+        DynamoDBBaseUserTableUUID (_type_): The underlying table object.
+        OAuthBase (_type_): The base class representing `OAuth` related models.
+    """
     __tablename__: str = config.get("DATABASE_OAUTHTABLE_NAME") + "_test"
 
     class Meta:
+        """The required `Meta` definitions for PynamoDB.
+
+        Args:
+            table_name (str): The name of the table.
+            region (str): The AWS region string where the table should be created.
+            billing_mode (str): The billing mode to use when creating the table. \
+            Currently only supports `PAY_PER_REQUEST`.
+        """
         table_name: str = config.get("DATABASE_OAUTHTABLE_NAME") + "_test"
         region: str = config.get("DATABASE_REGION")
         billing_mode: str = config.get("DATABASE_BILLING_MODE").value
@@ -60,18 +104,39 @@ class Meta:
 
 @pytest_asyncio.fixture
 async def dynamodb_user_db() -> AsyncGenerator[DynamoDBUserDatabase, None]:
+    """Create and yield a new `User` database instance for other tests to use.
+
+    Returns:
+        AsyncGenerator[DynamoDBUserDatabase, None]: The `User` database instance.
+
+    Yields:
+        Iterator[AsyncGenerator[DynamoDBUserDatabase, None]]: The `User` database instance.
+    """
     db = DynamoDBUserDatabase(User)
     yield db
 
 
 @pytest_asyncio.fixture
 async def dynamodb_user_db_oauth() -> AsyncGenerator[DynamoDBUserDatabase, None]:
+    """Create and yield a new `OAuth` database instance for other tests to use.
+
+    Returns:
+        AsyncGenerator[DynamoDBUserDatabase, None]: The `OAuth` database instance.
+
+    Yields:
+        Iterator[AsyncGenerator[DynamoDBUserDatabase, None]]: The `OAuth` database instance.
+    """
     db = DynamoDBUserDatabase(UserOAuth, OAuthAccount)
     yield db
 
 
 @pytest.mark.asyncio
 async def test_queries(dynamodb_user_db: DynamoDBUserDatabase[User, UUID_ID]):
+    """Test basic **CRUD** operations on a `User`.
+
+    Args:
+        dynamodb_user_db (DynamoDBUserDatabase[User, UUID_ID]): The `User` database instance to use.
+    """
     user_create = {"email": "lancelot@camelot.bt", "hashed_password": "guinevere"}
 
     # Create user
@@ -134,6 +199,11 @@ async def test_queries(dynamodb_user_db: DynamoDBUserDatabase[User, UUID_ID]):
 async def test_insert_existing_email(
     dynamodb_user_db: DynamoDBUserDatabase[User, UUID_ID],
 ):
+    """Test inserting an email, which already exists.
+
+    Args:
+        dynamodb_user_db (DynamoDBUserDatabase[User, UUID_ID]): The `User` database instance to use.
+    """
     user_create = {
         "email": "lancelot@camelot.bt",
         "hashed_password": "guinevere",
@@ -157,7 +227,11 @@ async def test_insert_existing_email(
 async def test_queries_custom_fields(
     dynamodb_user_db: DynamoDBUserDatabase[User, UUID_ID],
 ):
-    """It should output custom fields in query result."""
+    """Test basic **CRUD** operations (especially querying) on custom fields.
+
+    Args:
+        dynamodb_user_db (DynamoDBUserDatabase[User, UUID_ID]): The `User` database instance to use.
+    """
     user_create = {
         "email": "lancelot@camelot.bt",
         "hashed_password": "guinevere",
@@ -178,6 +252,14 @@ async def test_queries_oauth(
     oauth_account2: dict[str, Any],
     user_id: UUID_ID,
 ):
+    """Test `OAuth` implemenatation and basic **CRUD** operations.
+
+    Args:
+        dynamodb_user_db_oauth (DynamoDBUserDatabase[UserOAuth, UUID_ID]): The `OAuth` database instance to use.
+        oauth_account1 (dict[str, Any]): A fake `OAuth` account for testing.
+        oauth_account2 (dict[str, Any]): Another fake `OAuth` account for testing.
+        user_id (UUID_ID): The default user id to use.
+    """
     # Test OAuth accounts
     user_create = {"email": "lancelot@camelot.bt", "hashed_password": "guinevere"}