Further update missing documentation

Author: brodriguez8774

django_expanded_test_cases/mixins/core_mixin.py

@@ -600,7 +600,8 @@ def get_user(self, user, password=ETC_DEFAULT_USER_PASSWORD, extra_usergen_kwarg
 
         :param user: User model, or corresponding user identifier, to use.
         :param password: Password str to assign to user.
-        :param extra_usergen_kwargs: Optional extra kwargs to pass into the get_user_model().objects.create_user()
+        :param extra_usergen_kwargs: Optional extra kwargs to pass into the
+                                     get_user_model().objects.create_user()
                                      function.
         :return: User object
         """

docs/source/test_cases/base_test_case.rst

@@ -15,22 +15,83 @@ Custom Assertions
 =================
 
 
-assertText
-----------
+assertText()
+------------
 
 .. code::
 
-    assertText(actual_text, expected_text, strip=True)
+    self.assertText(expected_text, actual_text, strip=True)
 
 
-Currently, this is mostly a wrapper for assertEqual(), which prints full
-values to console on mismatch.
+This is effectively a wrapper for assertEqual(), which is meant specifically
+for comparing two bits of text.
+The difference is that on failure, this attempts to print full values to
+console on mismatch (``assertEqual()`` will truncate if values are too long).
 
-In the future, this may be updated to have more useful AssertionFailure
-output, particularly for long values.
+Furthermore if `Colorama <https://pypi.org/project/colorama/>`_ is installed,
+then text will be colored according to what characters did and did not match.
 
-:param actual_text: The value you wish to verify.
-:param expected_text: The value to compare against. These should match.
+
+:param expected_text: The value you expect to find.
+:param actual_text: The variable value you're testing against, to match against
+                    ``expected_text``.
+:param strip: A boolean indicating if white space characters should be stripped
+              from both comparison values, prior to comparing.
+              Set False to skip stripping.
+
+
+assertTextStartsWith()
+----------------------
+
+.. code::
+
+    self.assertTextStartsWith(expected_text, actual_text, strip=True)
+
+Similar to above
+:ref:`test_cases/base_test_case:assertText()`, except it only cares about
+matching from the start of the comparison strings.
+
+If ``expected_text`` is shorter than ``actual_text``, then this assertion
+only matches equal to the total characters found in ``expected_text``.
+
+If ``expected_text`` is longer than ``actual_text``, then raise an error
+for the missing characters, but still attempt to compare full strings to
+indicate if all other values match or not.
+
+
+:param expected_text: The value you expect to find.
+:param actual_text: The variable value you're testing against, to match against
+                    ``expected_text``.
+:param strip: A boolean indicating if white space characters should be stripped
+              from both comparison values, prior to comparing.
+              Set False to skip stripping.
+
+
+assertTextEndsWith()
+----------------------
+
+.. code::
+
+    self.assertTextEndsWith(expected_text, actual_text, strip=True)
+
+Similar to above
+:ref:`test_cases/base_test_case:assertText()`, except it only cares about
+matching from the end of the comparison strings.
+
+If ``expected_text`` is shorter than ``actual_text``, then this assertion
+only matches equal to the total characters found in ``expected_text``.
+
+If ``expected_text`` is longer than ``actual_text``, then raise an error
+for the missing characters, but still attempt to compare full strings to
+indicate if all other values match or not.
+
+
+:param expected_text: The value you expect to find.
+:param actual_text: The variable value you're testing against, to match against
+                    ``expected_text``.
+:param strip: A boolean indicating if white space characters should be stripped
+              from both comparison values, prior to comparing.
+              Set False to skip stripping.
 
 
 Helper Functions
@@ -41,81 +102,177 @@ Reminder that the ``BaseTestCase`` class is meant to be minimalistic. So most
 types of input, and then return the expected value.
 
 
-get_user
---------
+User Helper Functions
+---------------------
+
+get_user()
+^^^^^^^^^^
 
 .. code::
 
-    get_user(user, password='password')
+    self.get_user(user, password='password', extra_usergen_kwargs=**kwargs)
 
 Helper function to obtain a given User object.
 
-Treats the provided value as the `username` field. Returns the User object that
-matches. If no such User exists in the database yet, then a new one is first
-created.
+Treats the provided value as the field defined in settings as the
+:ref:`user model identifier <configuration/auth:USER_MODEL_IDENTIFIER>`.
+
+Returns the User object that matches.
+If no such User exists in the database yet, then a new one is first created.
 
 For testing purposes, also makes sure the provided password is assigned to the
-user, and then includes this raw value as an attribute on the returned object.
+test user object, and then includes this raw value as an attribute on the
+returned object, found as ``user_object.password``.
+
 
+:param user: Identifier to use to attempt to get user with.
 :param password: The password to assign this user. On the returned User
                 object, the raw password value can be accessed via a
                 provided ``unhashed_password`` field.
+:param extra_usergen_kwargs: Optional extra kwargs to pass into the
+                            ``get_user_model().objects.create_user()`` function.
+                            If your project has custom logic for the
+                            ``create_user()`` function, then you can use this to
+                            pass additional values in.
 
 :return: Found User object.
 
 
-add_user_permission
--------------------
+add_user_permission()
+^^^^^^^^^^^^^^^^^^^^^
 
 .. code::
 
-    add_user_permission(user_permission, user='test_user')
+    self.add_user_permission(user_permission, user='test_user')
 
 Helper function to add
 `permissions <https://docs.djangoproject.com/en/dev/topics/auth/default/#permissions-and-authorization>`_
 to a given User.
 
+
 :param user_permission: Permission object, or name of permission object, to
                        add to User.
-:parm user: User to add permission to. Defaults to ``test_user``.
+:parm user: User to add permission to.
+            Can take in either a literal user object, or the identifier of a
+            user.
+            Defaults to ``test_user``.
 
 :return: Updated User object.
 
 
-add_user_group
---------------
+add_user_group()
+^^^^^^^^^^^^^^^^
 
 .. code::
 
-    add_user_group(user_group, user='test_user')
+    self.add_user_group(user_group, user='test_user')
 
 Helper function to add
 `groups <https://docs.djangoproject.com/en/dev/topics/auth/default/#groups>`_
 to a given User.
 
+
 :param user_group: Group object, or name of group object, to add to User.
-:param user: User to add group to. Defaults to ``test_user``.
+:param user: User to add group to.
+             Can take in either a literal user object, or the identifier of a
+             user.
+             Defaults to ``test_user``.
 
 :return: Updated User object.
 
 
-generate_get_url
-----------------
+Other Helper Functions
+----------------------
+
+generate_get_url()
+^^^^^^^^^^^^^^^^^^
 
 .. code::
 
-    generate_get_url(url=None, **kwargs)
+    self.generate_get_url(url=None, **kwargs)
 
 Helper function to generate a full GET request URL.
 
-Note: If you're repeatedly accessing the same URL, you can define the value
-```self.url``` in the **BaseTestCase** class.
-
 Any provided kwargs are assumed to be
 `URL Parameters <https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#parameters>`_,
 and are appended to the end of the URL accordingly.
 
+.. note::
+
+    If you're repeatedly accessing the same URL, you can define the value
+    ``self.url`` class variable.
+
+
 :param url: The desired url string value to use as the
            `URL path <https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#path_to_resource>`_.
+:param kwargs: A dictionary of key-value pairs, to be converted to Url
+               Parameters in the final url.
 
 :return: The generated url string.
+
+
+standardize_characters()
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code::
+
+    self.standardize_characters(value)
+
+Standardizes characters in provided string.
+
+For example, in HTML, the "greater than" symbol can be denoted in multiple
+ways, such as ``>``, ``&gt;``, ``&#62;``, or ``&#x3E``.
+
+This function takes all such known "equivalent" representations of various
+characters, and reformats them to a single type for consistency.
+
+Many of the assertions in this package use this function, in order to make
+testing easier and more consistent. (In our above example, the programmer
+probably doesn't care WHICH version of the "greater than" symbol is present.
+They most likely would only care that one of the several representations is
+present.)
+
+
+:param value: A string value to convert to standardized characters.
+
+:return: A string of more standardized characters.
+
+
+standardize_whitespace()
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code::
+
+    self.standardize_whitespace(value)
+
+Standardizes whitespace characters in provided string.
+
+When possible, all repeating whitespace and whitespace-esque characters
+(including newlines) are reduced down to a single space.
+
+
+:param value: A string value to convert to standardized characters.
+
+:return: A string of more standardized characters.
+
+
+standardize_newlines()
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code::
+
+    self.standardize_newlines(value)
+
+Standardizes newline/whitespace characters in provided string.
+
+When possible, all repeating newlines are converted down to a single ``\n``
+character, and whitespace and whitespace-esque characters
+(excluding newlines) are reduced down to a single space.
+
+If multiple newline characters and space characters repeat in a row, then
+that's reduced down to a single newline with up to one space on either side.
+
+
+:param value: A string value to convert to standardized characters.
+
+:return: A string of more standardized characters.

docs/source/test_cases/integration_test_case/other_functionality.rst

@@ -322,38 +322,61 @@ inject.
 By default, these functions do nothing on their own and are fully safe to
 override.
 
-* ``self._get_login_user__extra_user_auth_setup()``
-  - This function is called after getting the corresponding
-  :doc:`User object for authentication<../../managing_test_users>`, but prior
-  to attempting to process the request-response cycle.
+_get_login_user__extra_user_auth_setup()
+----------------------------------------
 
-  This is critical for projects with additional authentication logic.
-  If a project has additional authentication logic to process (such as
-  authentication keys or custom Auth backend logic), then it should be done
-  here.
+.. code::
+
+    self._get_login_user__extra_user_auth_setup(*args, **kwargs)
+
+This function is called after getting the corresponding
+:doc:`User object for authentication<../../managing_test_users>`, but prior
+to attempting to process the
+`request-response <https://docs.djangoproject.com/en/dev/ref/request-response/>`_
+cycle.
+
+This is critical for projects with additional authentication logic.
+If a project has additional authentication logic to process (such as
+authentication keys or custom Auth backend logic), then it should be done
+here to ensure test users can authenticate.
 
-  This hook receives only known args/kwargs that are related to user
-  authentication and request processing.
+This hook receives only known args/kwargs that are related to user
+authentication and request processing.
+
+
+_assertResponse__pre_builtin_tests()
+------------------------------------
+
+.. code::
 
-* ``self._assertResponse__pre_builtin_tests()``
-  - This function is called after getting the page response, but prior to
-  calling any assertion checks on it.
+    self._assertResponse__pre_builtin_tests(*args, **kwargs)
+
+This function is called after getting the
+`page response <https://docs.djangoproject.com/en/dev/ref/request-response/#httpresponse-objects>`_,
+but prior to calling any assertion checks on it.
+
+If a project requires any additional pre-check setup, or should have any
+custom checks to run prior to those built into ETC, then it should be done here.
+
+This hook receives all known args/kwargs that the response assertion receives.
+
+
+_assertResponse__post_builtin_tests()
+-------------------------------------
+
+.. code::
 
-  If a project requires any additional pre-check setup, or should have any
-  custom checks to run prior to those built into ETC, then it should be done
-  here.
+    self._assertResponse__post_builtin_tests()
 
-  This hook receives all known args/kwargs that the response assertion receives.
 
-* ``self._assertResponse__post_builtin_tests()``
-  - This function is called after
-  getting the page response, and after calling all provided assertion checks
-  on it.
+This function is called after getting the
+`page response <https://docs.djangoproject.com/en/dev/ref/request-response/#httpresponse-objects>`_,
+and after calling all provided assertion checks on it.
 
-  If a project requires any additional clean-up processing, or should have any
-  custom checks to run after those built into ETC, then it should be done here.
+If a project requires any additional clean-up processing, or should have any
+custom checks to run after those built into ETC, then it should be done here.
 
-  This hook receives all known args/kwargs that the response assertion receives.
+This hook receives all known args/kwargs that the response assertion receives.
 
 
 Implementing Hooks