django/tests/admin_docs/test_views.py

import sys
import unittest

from django.conf import settings
from django.contrib import admin
from django.contrib.admindocs import utils, views
from django.contrib.admindocs.views import get_return_data_type, simplify_regex
from django.contrib.sites.models import Site
from django.db import models
from django.db.models import fields
from django.test import SimpleTestCase, modify_settings, override_settings
from django.test.utils import captured_stderr
from django.urls import include, path, reverse
from django.utils.functional import SimpleLazyObject

from .models import Company, Person
from .tests import AdminDocsTestCase, TestDataMixin


@unittest.skipUnless(utils.docutils_is_available, "no docutils installed.")
class AdminDocViewTests(TestDataMixin, AdminDocsTestCase):

    def setUp(self):
        self.client.force_login(self.superuser)

    def test_index(self):
        response = self.client.get(reverse('django-admindocs-docroot'))
        self.assertContains(response, '<h1>Documentation</h1>', html=True)
        self.assertContains(response, '<h1 id="site-name"><a href="/admin/">Django administration</a></h1>')
        self.client.logout()
        response = self.client.get(reverse('django-admindocs-docroot'), follow=True)
        # Should display the login screen
        self.assertContains(response, '<input type="hidden" name="next" value="/admindocs/">', html=True)

    def test_bookmarklets(self):
        response = self.client.get(reverse('django-admindocs-bookmarklets'))
        self.assertContains(response, '/admindocs/views/')

    def test_templatetag_index(self):
        response = self.client.get(reverse('django-admindocs-tags'))
        self.assertContains(response, '<h3 id="built_in-extends">extends</h3>', html=True)

    def test_templatefilter_index(self):
        response = self.client.get(reverse('django-admindocs-filters'))
        self.assertContains(response, '<h3 id="built_in-first">first</h3>', html=True)

    def test_view_index(self):
        response = self.client.get(reverse('django-admindocs-views-index'))
        self.assertContains(
            response,
            '<h3><a href="/admindocs/views/django.contrib.admindocs.views.BaseAdminDocsView/">/admindocs/</a></h3>',
            html=True
        )
        self.assertContains(response, 'Views by namespace test')
        self.assertContains(response, 'Name: <code>test:func</code>.')
        self.assertContains(
            response,
            '<h3><a href="/admindocs/views/admin_docs.views.XViewCallableObject/">'
            '/xview/callable_object_without_xview/</a></h3>',
            html=True,
        )

    def test_view_index_with_method(self):
        """
        Views that are methods are listed correctly.
        """
        response = self.client.get(reverse('django-admindocs-views-index'))
        self.assertContains(
            response,
            '<h3><a href="/admindocs/views/django.contrib.admin.sites.AdminSite.index/">/admin/</a></h3>',
            html=True
        )

    def test_view_detail(self):
        url = reverse('django-admindocs-views-detail', args=['django.contrib.admindocs.views.BaseAdminDocsView'])
        response = self.client.get(url)
        # View docstring
        self.assertContains(response, 'Base view for admindocs views.')

    @override_settings(ROOT_URLCONF='admin_docs.namespace_urls')
    def test_namespaced_view_detail(self):
        url = reverse('django-admindocs-views-detail', args=['admin_docs.views.XViewClass'])
        response = self.client.get(url)
        self.assertContains(response, '<h1>admin_docs.views.XViewClass</h1>')

    def test_view_detail_illegal_import(self):
        url = reverse('django-admindocs-views-detail', args=['urlpatterns_reverse.nonimported_module.view'])
        response = self.client.get(url)
        self.assertEqual(response.status_code, 404)
        self.assertNotIn("urlpatterns_reverse.nonimported_module", sys.modules)

    def test_view_detail_as_method(self):
        """
        Views that are methods can be displayed.
        """
        url = reverse('django-admindocs-views-detail', args=['django.contrib.admin.sites.AdminSite.index'])
        response = self.client.get(url)
        self.assertEqual(response.status_code, 200)

    def test_model_index(self):
        response = self.client.get(reverse('django-admindocs-models-index'))
        self.assertContains(
            response,
            '<h2 id="app-auth">Authentication and Authorization (django.contrib.auth)</h2>',
            html=True
        )

    def test_template_detail(self):
        response = self.client.get(reverse('django-admindocs-templates', args=['admin_doc/template_detail.html']))
        self.assertContains(response, '<h1>Template: <q>admin_doc/template_detail.html</q></h1>', html=True)

    def test_missing_docutils(self):
        utils.docutils_is_available = False
        try:
            response = self.client.get(reverse('django-admindocs-docroot'))
            self.assertContains(
                response,
                '<h3>The admin documentation system requires Python’s '
                '<a href="https://docutils.sourceforge.io/">docutils</a> '
                'library.</h3>'
                '<p>Please ask your administrators to install '
                '<a href="https://docutils.sourceforge.io/">docutils</a>.</p>',
                html=True
            )
            self.assertContains(response, '<h1 id="site-name"><a href="/admin/">Django administration</a></h1>')
        finally:
            utils.docutils_is_available = True

    @modify_settings(INSTALLED_APPS={'remove': 'django.contrib.sites'})
    @override_settings(SITE_ID=None)    # will restore SITE_ID after the test
    def test_no_sites_framework(self):
        """
        Without the sites framework, should not access SITE_ID or Site
        objects. Deleting settings is fine here as UserSettingsHolder is used.
        """
        Site.objects.all().delete()
        del settings.SITE_ID
        response = self.client.get(reverse('django-admindocs-views-index'))
        self.assertContains(response, 'View documentation')

    def test_callable_urlconf(self):
        """
        Index view should correctly resolve view patterns when ROOT_URLCONF is
        not a string.
        """
        def urlpatterns():
            return (
                path('admin/doc/', include('django.contrib.admindocs.urls')),
                path('admin/', admin.site.urls),
            )

        with self.settings(ROOT_URLCONF=SimpleLazyObject(urlpatterns)):
            response = self.client.get(reverse('django-admindocs-views-index'))
            self.assertEqual(response.status_code, 200)


@unittest.skipUnless(utils.docutils_is_available, 'no docutils installed.')
class AdminDocViewDefaultEngineOnly(TestDataMixin, AdminDocsTestCase):

    def setUp(self):
        self.client.force_login(self.superuser)

    def test_template_detail_path_traversal(self):
        cases = ['/etc/passwd', '../passwd']
        for fpath in cases:
            with self.subTest(path=fpath):
                response = self.client.get(
                    reverse('django-admindocs-templates', args=[fpath]),
                )
                self.assertEqual(response.status_code, 400)


@override_settings(TEMPLATES=[{
    'NAME': 'ONE',
    'BACKEND': 'django.template.backends.django.DjangoTemplates',
    'APP_DIRS': True,
}, {
    'NAME': 'TWO',
    'BACKEND': 'django.template.backends.django.DjangoTemplates',
    'APP_DIRS': True,
}])
@unittest.skipUnless(utils.docutils_is_available, "no docutils installed.")
class AdminDocViewWithMultipleEngines(AdminDocViewTests):

    def test_templatefilter_index(self):
        # Overridden because non-trivial TEMPLATES settings aren't supported
        # but the page shouldn't crash (#24125).
        response = self.client.get(reverse('django-admindocs-filters'))
        self.assertContains(response, '<title>Template filters</title>', html=True)

    def test_templatetag_index(self):
        # Overridden because non-trivial TEMPLATES settings aren't supported
        # but the page shouldn't crash (#24125).
        response = self.client.get(reverse('django-admindocs-tags'))
        self.assertContains(response, '<title>Template tags</title>', html=True)


@unittest.skipUnless(utils.docutils_is_available, "no docutils installed.")
class TestModelDetailView(TestDataMixin, AdminDocsTestCase):

    def setUp(self):
        self.client.force_login(self.superuser)
        with captured_stderr() as self.docutils_stderr:
            self.response = self.client.get(reverse('django-admindocs-models-detail', args=['admin_docs', 'Person']))

    def test_method_excludes(self):
        """
        Methods that begin with strings defined in
        ``django.contrib.admindocs.views.MODEL_METHODS_EXCLUDE``
        shouldn't be displayed in the admin docs.
        """
        self.assertContains(self.response, "<td>get_full_name</td>")
        self.assertNotContains(self.response, "<td>_get_full_name</td>")
        self.assertNotContains(self.response, "<td>add_image</td>")
        self.assertNotContains(self.response, "<td>delete_image</td>")
        self.assertNotContains(self.response, "<td>set_status</td>")
        self.assertNotContains(self.response, "<td>save_changes</td>")

    def test_methods_with_arguments(self):
        """
        Methods that take arguments should also displayed.
        """
        self.assertContains(self.response, "<h3>Methods with arguments</h3>")
        self.assertContains(self.response, "<td>rename_company</td>")
        self.assertContains(self.response, "<td>dummy_function</td>")
        self.assertContains(self.response, "<td>suffix_company_name</td>")

    def test_methods_with_arguments_display_arguments(self):
        """
        Methods with arguments should have their arguments displayed.
        """
        self.assertContains(self.response, "<td>new_name</td>")

    def test_methods_with_arguments_display_arguments_default_value(self):
        """
        Methods with keyword arguments should have their arguments displayed.
        """
        self.assertContains(self.response, '<td>suffix=&#x27;ltd&#x27;</td>')

    def test_methods_with_multiple_arguments_display_arguments(self):
        """
        Methods with multiple arguments should have all their arguments
        displayed, but omitting 'self'.
        """
        self.assertContains(self.response, "<td>baz, rox, *some_args, **some_kwargs</td>")

    def test_instance_of_property_methods_are_displayed(self):
        """Model properties are displayed as fields."""
        self.assertContains(self.response, '<td>a_property</td>')

    def test_instance_of_cached_property_methods_are_displayed(self):
        """Model cached properties are displayed as fields."""
        self.assertContains(self.response, '<td>a_cached_property</td>')

    def test_method_data_types(self):
        company = Company.objects.create(name="Django")
        person = Person.objects.create(first_name="Human", last_name="User", company=company)
        self.assertEqual(get_return_data_type(person.get_status_count.__name__), 'Integer')
        self.assertEqual(get_return_data_type(person.get_groups_list.__name__), 'List')

    def test_descriptions_render_correctly(self):
        """
        The ``description`` field should render correctly for each field type.
        """
        # help text in fields
        self.assertContains(self.response, "<td>first name - The person's first name</td>")
        self.assertContains(self.response, "<td>last name - The person's last name</td>")

        # method docstrings
        self.assertContains(self.response, "<p>Get the full name of the person</p>")

        link = '<a class="reference external" href="/admindocs/models/%s/">%s</a>'
        markup = '<p>the related %s object</p>'
        company_markup = markup % (link % ("admin_docs.company", "admin_docs.Company"))

        # foreign keys
        self.assertContains(self.response, company_markup)

        # foreign keys with help text
        self.assertContains(self.response, "%s\n - place of work" % company_markup)

        # many to many fields
        self.assertContains(
            self.response,
            "number of related %s objects" % (link % ("admin_docs.group", "admin_docs.Group"))
        )
        self.assertContains(
            self.response,
            "all related %s objects" % (link % ("admin_docs.group", "admin_docs.Group"))
        )

        # "raw" and "include" directives are disabled
        self.assertContains(self.response, '<p>&quot;raw&quot; directive disabled.</p>',)
        self.assertContains(self.response, '.. raw:: html\n    :file: admin_docs/evilfile.txt')
        self.assertContains(self.response, '<p>&quot;include&quot; directive disabled.</p>',)
        self.assertContains(self.response, '.. include:: admin_docs/evilfile.txt')
        out = self.docutils_stderr.getvalue()
        self.assertIn('"raw" directive disabled', out)
        self.assertIn('"include" directive disabled', out)

    def test_model_with_many_to_one(self):
        link = '<a class="reference external" href="/admindocs/models/%s/">%s</a>'
        response = self.client.get(
            reverse('django-admindocs-models-detail', args=['admin_docs', 'company'])
        )
        self.assertContains(
            response,
            "number of related %s objects" % (link % ("admin_docs.person", "admin_docs.Person"))
        )
        self.assertContains(
            response,
            "all related %s objects" % (link % ("admin_docs.person", "admin_docs.Person"))
        )

    def test_model_with_no_backward_relations_render_only_relevant_fields(self):
        """
        A model with ``related_name`` of `+` shouldn't show backward
        relationship links.
        """
        response = self.client.get(reverse('django-admindocs-models-detail', args=['admin_docs', 'family']))
        fields = response.context_data.get('fields')
        self.assertEqual(len(fields), 2)

    def test_model_docstring_renders_correctly(self):
        summary = (
            '<h2 class="subhead"><p>Stores information about a person, related to <a class="reference external" '
            'href="/admindocs/models/myapp.company/">myapp.Company</a>.</p></h2>'
        )
        subheading = '<p><strong>Notes</strong></p>'
        body = '<p>Use <tt class="docutils literal">save_changes()</tt> when saving this object.</p>'
        model_body = (
            '<dl class="docutils"><dt><tt class="'
            'docutils literal">company</tt></dt><dd>Field storing <a class="'
            'reference external" href="/admindocs/models/myapp.company/">'
            'myapp.Company</a> where the person works.</dd></dl>'
        )
        self.assertContains(self.response, 'DESCRIPTION')
        self.assertContains(self.response, summary, html=True)
        self.assertContains(self.response, subheading, html=True)
        self.assertContains(self.response, body, html=True)
        self.assertContains(self.response, model_body, html=True)

    def test_model_detail_title(self):
        self.assertContains(self.response, '<h1>admin_docs.Person</h1>', html=True)

    def test_app_not_found(self):
        response = self.client.get(reverse('django-admindocs-models-detail', args=['doesnotexist', 'Person']))
        self.assertEqual(response.context['exception'], "App 'doesnotexist' not found")
        self.assertEqual(response.status_code, 404)

    def test_model_not_found(self):
        response = self.client.get(reverse('django-admindocs-models-detail', args=['admin_docs', 'doesnotexist']))
        self.assertEqual(response.context['exception'], "Model 'doesnotexist' not found in app 'admin_docs'")
        self.assertEqual(response.status_code, 404)


class CustomField(models.Field):
    description = "A custom field type"


class DescriptionLackingField(models.Field):
    pass


class TestFieldType(unittest.TestCase):
    def test_field_name(self):
        with self.assertRaises(AttributeError):
            views.get_readable_field_data_type("NotAField")

    def test_builtin_fields(self):
        self.assertEqual(
            views.get_readable_field_data_type(fields.BooleanField()),
            'Boolean (Either True or False)'
        )

    def test_custom_fields(self):
        self.assertEqual(views.get_readable_field_data_type(CustomField()), 'A custom field type')
        self.assertEqual(
            views.get_readable_field_data_type(DescriptionLackingField()),
            'Field of type: DescriptionLackingField'
        )


class AdminDocViewFunctionsTests(SimpleTestCase):

    def test_simplify_regex(self):
        tests = (
            (r'^a', '/a'),
            (r'^(?P<a>\w+)/b/(?P<c>\w+)/$', '/<a>/b/<c>/'),
            (r'^(?P<a>\w+)/b/(?P<c>\w+)$', '/<a>/b/<c>'),
            (r'^(?P<a>\w+)/b/(?P<c>\w+)', '/<a>/b/<c>'),
            (r'^(?P<a>\w+)/b/(\w+)$', '/<a>/b/<var>'),
            (r'^(?P<a>\w+)/b/(\w+)', '/<a>/b/<var>'),
            (r'^(?P<a>\w+)/b/((x|y)\w+)$', '/<a>/b/<var>'),
            (r'^(?P<a>\w+)/b/((x|y)\w+)', '/<a>/b/<var>'),
            (r'^(?P<a>(x|y))/b/(?P<c>\w+)$', '/<a>/b/<c>'),
            (r'^(?P<a>(x|y))/b/(?P<c>\w+)', '/<a>/b/<c>'),
            (r'^(?P<a>(x|y))/b/(?P<c>\w+)ab', '/<a>/b/<c>ab'),
            (r'^(?P<a>(x|y)(\(|\)))/b/(?P<c>\w+)ab', '/<a>/b/<c>ab'),
            (r'^a/?$', '/a/'),
        )
        for pattern, output in tests:
            with self.subTest(pattern=pattern):
                self.assertEqual(simplify_regex(pattern), output)