Test limit/offset and marker pagination

autoreleasefool · autoreleasefool · commit 7650e2152a8d · 2017-07-12T14:29:01.000-07:00
diff --git a/test/unit/object/test_folder.py b/test/unit/object/test_folder.py
@@ -13,6 +13,8 @@
 from boxsdk.object.file import File
 from boxsdk.object.collaboration import Collaboration, CollaborationRole
 from boxsdk.object.folder import Folder, FolderSyncState
+from boxsdk.pagination.limit_offset_based_object_collection import LimitOffsetBasedObjectCollection
+from boxsdk.pagination.marker_based_object_collection import MarkerBasedObjectCollection
 from boxsdk.session.box_session import BoxResponse
 
 
@@ -139,6 +141,16 @@ def test_get_items(test_folder, mock_box_session, mock_items_response, limit, of
     assert all([i.id == e.object_id for i, e in zip(items, expected_items)])
 
 
+def test_get_items_marker_returns_marker_instance(test_folder):
+    limit_offset_object_collection = test_folder.get_items_limit_offset()
+    assert isinstance(limit_offset_object_collection, LimitOffsetBasedObjectCollection)
+
+
+def test_get_items_limit_offset_returns_limit_offset_instance(test_folder):
+    marker_object_collection = test_folder.get_items_marker()
+    assert isinstance(marker_object_collection, MarkerBasedObjectCollection)
+
+
 @pytest.mark.parametrize('is_stream', (True, False))
 def test_upload(
         test_folder,
diff --git a/test/unit/pagination/__init__.py b/test/unit/pagination/__init__.py
@@ -0,0 +1,3 @@
+# coding: utf-8
+
+from __future__ import unicode_literals
diff --git a/test/unit/pagination/box_object_collection_test_base.py b/test/unit/pagination/box_object_collection_test_base.py
@@ -0,0 +1,109 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+from abc import ABCMeta, abstractmethod
+from six import add_metaclass
+from six.moves import range   # pylint:disable=redefined-builtin
+import pytest
+
+from boxsdk.util.translator import Translator
+
+
+@add_metaclass(ABCMeta)
+class BoxObjectCollectionTestBase(object):
+    NUM_ENTRIES = 25
+
+    @pytest.fixture()
+    def translator(self):
+        return Translator()
+
+    @pytest.fixture()
+    def entries(self):
+        all_entries = []
+        for i in range(self.NUM_ENTRIES):
+            all_entries.append({
+                "type": "file",
+                "id": str(1000 + i),
+                "sequence_id": str(i),
+                "etag": str(10 + i),
+                "name": "file_{0}.txt".format(i),
+            })
+        return all_entries
+
+    @abstractmethod
+    @pytest.fixture()
+    def mock_items_response(self, entries):
+        raise NotImplementedError
+
+    @abstractmethod
+    @pytest.fixture()
+    def mock_session(self, translator, mock_items_response):
+        raise NotImplementedError
+
+    @abstractmethod
+    def _object_collection_instance(self, session, limit, return_full_pages=False, starting_pointer=None):
+        """
+        :type session: :class:`BoxSession`
+        :type limit: `int`
+        :type return_full_pages: `bool`
+        :type starting_pointer: varies
+        :rtype: :class:`BoxObjectCollection`
+        """
+        raise NotImplementedError
+
+    def _assert_items_dict_and_objects_same(self, expected_items_dict, returned_item_objects):
+        """
+        A fixture very specific to this test class. Asserts that the list of items in dictionary form are the
+        same (at least in name, and in quantity) as a list of BaseObjects.
+
+        :param expected_items_dict: List of expected items, represented as a dictionary.
+        :type expected_items_dict: `list` of `dict`
+        :param returned_item_objects: List of item instances (BaseObject) returned by SUT.
+        :type returned_item_objects: `list` of class:`BaseObject`
+        """
+        expected_num = len(expected_items_dict)
+        actual_num = len(returned_item_objects)
+        assert actual_num == expected_num, 'Expected {0} items, got {1}'.format(expected_num, actual_num)
+        returned_item_names = [item.name for item in returned_item_objects]
+        for expected_item_dict in expected_items_dict:
+            assert expected_item_dict['name'] in returned_item_names, 'Missing item: {0}'.format(expected_item_dict['name'])
+
+    @pytest.mark.parametrize('return_full_pages', (True, False))
+    @pytest.mark.parametrize('limit', (1, 3, 5, NUM_ENTRIES, 1000))
+    def test_object_collection_pages_through_all_entries(self, mock_session, entries, limit, return_full_pages):
+        """
+        Tests the basic iteration functionality of the box object collection.
+        """
+        object_collection = self._object_collection_instance(mock_session, limit, return_full_pages)
+        iterated_items = []
+        for item_or_page in object_collection:
+            if return_full_pages:
+                iterated_items.extend(item_or_page)
+            else:
+                iterated_items.append(item_or_page)
+        self._assert_items_dict_and_objects_same(entries, iterated_items)
+
+    def test_new_object_collection_starts_off_from_last_pointer(self, mock_session, entries):
+        """
+        Start paging with one object collection instance, and then finish paging with a new object collection
+        instance, starting off from the next_pointer() of the previous instance.
+
+        The iterated items should be identical as if it were iterated through with just one object collection
+        instance.
+        """
+        iterated_items = []
+        object_collection = self._object_collection_instance(mock_session, limit=5, return_full_pages=True)
+        iterated_items.extend(object_collection.next())
+        next_pointer = object_collection.next_pointer()
+
+        # Create a new object collection, starting off where the previous collection left off.
+        new_object_collection = self._object_collection_instance(
+            mock_session,
+            limit=5,
+            return_full_pages=True,
+            starting_pointer=next_pointer
+        )
+        for page in new_object_collection:
+            iterated_items.extend(page)
+
+        self._assert_items_dict_and_objects_same(entries, iterated_items)
diff --git a/test/unit/pagination/test_limit_offset_based_object_collection.py b/test/unit/pagination/test_limit_offset_based_object_collection.py
@@ -0,0 +1,106 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+import json
+from mock import Mock, PropertyMock
+import pytest
+
+from boxsdk.network.default_network import DefaultNetworkResponse
+from boxsdk.pagination.limit_offset_based_object_collection import LimitOffsetBasedObjectCollection
+from boxsdk.session.box_session import BoxResponse, BoxSession
+from .box_object_collection_test_base import BoxObjectCollectionTestBase
+
+
+class TestLimitOffsetBasedObjectCollection(BoxObjectCollectionTestBase):
+    DEFAULT_LIMIT = 100
+
+    @pytest.fixture()
+    def mock_items_response(self, entries):
+        """Baseclass override."""
+        # pylint:disable=redefined-outer-name
+        def get_response(limit, offset):
+            mock_box_response = Mock(BoxResponse)
+            mock_network_response = Mock(DefaultNetworkResponse)
+            mock_box_response.network_response = mock_network_response
+            mock_box_response.json.return_value = mock_json = {
+                'entries': entries[offset:limit + offset],
+                'total_count': len(entries),
+                'limit': limit,
+            }
+            mock_box_response.content = json.dumps(mock_json).encode()
+            mock_box_response.status_code = 200
+            mock_box_response.ok = True
+            return mock_box_response
+        return get_response
+
+    @pytest.fixture()
+    def mock_session(self, translator, mock_items_response):
+        """Baseclass override."""
+        mock_box_session = Mock(BoxSession)
+        type(mock_box_session).translator = PropertyMock(
+            return_value=translator
+        )
+
+        def mock_items_side_effect(_, params):
+            limit = min(params.get('limit', self.DEFAULT_LIMIT), self.DEFAULT_LIMIT)
+            offset = params.get('offset', 0)
+            return mock_items_response(limit, offset)
+
+        mock_box_session.get.side_effect = mock_items_side_effect
+        return mock_box_session
+
+    def _object_collection_instance(self, session, limit=None, return_full_pages=False, starting_pointer=None):
+        """Baseclass override."""
+        if starting_pointer is None:
+            starting_pointer = 0
+        return LimitOffsetBasedObjectCollection(
+            session,
+            '/some/endpoint',
+            limit=limit,
+            return_full_pages=return_full_pages,
+            offset=starting_pointer,
+        )
+
+    @pytest.mark.parametrize('return_full_pages', (True, False))
+    def test_object_collection_sets_next_pointer_correctly(self, mock_session, return_full_pages):
+        page_size = 10
+        object_collection = LimitOffsetBasedObjectCollection(
+            mock_session,
+            '/some/endpoint',
+            limit=page_size,
+            return_full_pages=return_full_pages,
+        )
+
+        assert object_collection.next_pointer() == 0
+        object_collection.next()
+        assert object_collection.next_pointer() == page_size
+
+        # Iterate to the last page, which doesn't return a full page.
+        [_ for _ in object_collection]  # pylint:disable=pointless-statement
+        assert object_collection.next_pointer() == self.NUM_ENTRIES
+
+    def test_object_collection_raises_stop_iteration_when_starting_offset_is_too_far(self, mock_session, entries):
+        """
+        If the specified initial offset for the object collection is higher than the total number of items,
+        then the first call to next() on the object collection should raise a StopIteration.
+        """
+        starting_offset = len(entries) + 10
+        object_collection = self._object_collection_instance(
+            mock_session,
+            limit=5,
+            return_full_pages=False,
+            starting_pointer=starting_offset
+        )
+        with pytest.raises(StopIteration):
+            object_collection.next()
+
+    def test_object_collection_sets_limit_to_returned_value_if_originally_none(self, mock_session):
+        # No limit specified
+        object_collection = self._object_collection_instance(mock_session)
+        object_collection.next()
+        assert object_collection._limit == self.DEFAULT_LIMIT   # pylint:disable=protected-access
+
+    def test_object_collection_sets_limit_to_returned_value_if_originally_too_high(self, mock_session):
+        object_collection = self._object_collection_instance(mock_session, limit=(1 + self.DEFAULT_LIMIT))
+        object_collection.next()
+        assert object_collection._limit == self.DEFAULT_LIMIT   # pylint:disable=protected-access
diff --git a/test/unit/pagination/test_marker_based_object_collection.py b/test/unit/pagination/test_marker_based_object_collection.py
@@ -0,0 +1,109 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+import json
+from mock import Mock, PropertyMock, ANY
+import pytest
+
+from boxsdk.network.default_network import DefaultNetworkResponse
+from boxsdk.pagination.marker_based_object_collection import MarkerBasedObjectCollection
+from boxsdk.session.box_session import BoxResponse, BoxSession
+from .box_object_collection_test_base import BoxObjectCollectionTestBase
+
+
+class TestMarkerBasedObjectCollection(BoxObjectCollectionTestBase):
+    """
+    In order to conveniently mimic marker based paging for the purposes of this test, the markers ('next_marker' in
+    the response) returned by the mock_session object is always going to be of the convention: "marker_i", where
+    i is the starting 0-index based offset of the element.
+    """
+
+    NO_NEXT_MARKER = object()
+
+    @pytest.fixture(params=['', None, NO_NEXT_MARKER])
+    def next_marker_value_for_last_page(self, request):
+        return request.param
+
+    @pytest.fixture()
+    def mock_items_response(self, entries, next_marker_value_for_last_page):
+        """Baseclass override."""
+        # pylint:disable=redefined-outer-name
+        def get_response(limit, marker):
+            mock_box_response = Mock(BoxResponse)
+            mock_network_response = Mock(DefaultNetworkResponse)
+            mock_box_response.network_response = mock_network_response
+
+            mock_json = {}
+            # The marker string should be of format: "marker_i", where i is the offset. Parse that out.
+            # If the marker is None, then begin paging from the start of the entries.
+            offset = 0
+            if marker is not None:
+                offset = int(marker.split('_')[1])
+            mock_json['entries'] = entries[offset:limit + offset]
+
+            # A next_marker is only returned if there are more pages left.
+            if (offset + limit) < len(entries):
+                mock_json['next_marker'] = 'marker_{0}'.format(offset + limit)
+            elif next_marker_value_for_last_page is not self.NO_NEXT_MARKER:
+                mock_json['next_marker'] = next_marker_value_for_last_page
+
+            mock_box_response.json.return_value = mock_json
+            mock_box_response.content = json.dumps(mock_json).encode()
+            mock_box_response.status_code = 200
+            mock_box_response.ok = True
+            return mock_box_response
+        return get_response
+
+    @pytest.fixture()
+    def mock_session(self, translator, mock_items_response):
+        """Baseclass override."""
+        mock_box_session = Mock(BoxSession)
+        type(mock_box_session).translator = PropertyMock(return_value=translator)
+
+        def mock_items_side_effect(_, params):
+            limit = params['limit']
+            marker = params.get('marker', None)
+            return mock_items_response(limit, marker)
+
+        mock_box_session.get.side_effect = mock_items_side_effect
+        return mock_box_session
+
+    def _object_collection_instance(  # pylint:disable=arguments-differ
+            self,
+            session,
+            limit,
+            return_full_pages=False,
+            starting_pointer=None,
+            supports_limit_offset_paging=False
+    ):
+        """Baseclass override."""
+        return MarkerBasedObjectCollection(
+            session,
+            '/some/endpoint',
+            limit=limit,
+            return_full_pages=return_full_pages,
+            marker=starting_pointer,
+            supports_limit_offset_paging=supports_limit_offset_paging,
+        )
+
+    @pytest.mark.parametrize('return_full_pages', (True, False))
+    def test_object_collection_sets_next_pointer_correctly(self, mock_session, return_full_pages):
+        object_collection = self._object_collection_instance(mock_session, limit=5, return_full_pages=return_full_pages)
+        assert object_collection.next_pointer() is None
+        object_collection.next()
+        assert object_collection.next_pointer() == 'marker_5'
+
+    @pytest.mark.parametrize('supports_limit_offset_paging', (True, False))
+    def test_object_collection_specifies_marker_param(self, mock_session, supports_limit_offset_paging):
+        object_collection = self._object_collection_instance(
+            mock_session,
+            limit=100,
+            supports_limit_offset_paging=supports_limit_offset_paging
+        )
+        object_collection.next()
+
+        # Assert
+        expected_params = {'limit': 100}
+        if supports_limit_offset_paging:
+            expected_params['useMarker'] = True
+        mock_session.get.assert_called_with(ANY, params=expected_params)
diff --git a/test/unit/pagination/test_page.py b/test/unit/pagination/test_page.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# coding: utf-8`
	`2`	`+`
	`3`	`+from __future__ import unicode_literals`