Verify that an update does not reset the tracking rating to -1

.github/workflows/test.yml

@@ -110,6 +110,7 @@ jobs:
           - tests/mock_vws/test_update_target.py::TestImage::test_not_base64_encoded_not_processable
           - tests/mock_vws/test_update_target.py::TestImage::test_not_image
           - tests/mock_vws/test_update_target.py::TestImage::test_invalid_type
+          - tests/mock_vws/test_update_target.py::TestImage::test_rating_does_not_return_to_minus_one
           - tests/mock_vws/test_update_target.py::TestImage::test_rating_can_change
           - tests/mock_vws/test_update_target.py::TestTargetName::test_name_valid
           - tests/mock_vws/test_update_target.py::TestTargetName::test_name_invalid

docs/source/contributing.rst

@@ -190,6 +190,8 @@ This is because the target goes into a processing state.
 ``image`` is required for ``POST /targets``, but it is documented as not mandatory.
 
 The ``tracking_rating`` returned by ``GET /targets/<target_id>`` can be -1.
+This happens only while a newly uploaded target is processing, and it lasts for about a second.
+Updating a target returns it to the processing state but does not return the rating to -1; the new image's rating is reported straight away.
 
 The database summary from ``GET /summary`` has multiple undocumented return fields.
 

docs/source/differences-to-vws.rst

@@ -47,6 +47,10 @@ Targets are assigned a rating between 0 and 5 of how good they are for tracking
 In the mock this is calculated from the image quality, differently to how Vuforia does this.
 This is customizable with the :paramref:`~mock_vws.MockVWS.target_tracking_rater` parameter.
 
+A target which is being processed after an upload reports a rating of -1 for a short time, and then the image's rating, while it is still processing.
+An update does not start a new -1 window: it returns the target to the processing state and reports the new image's rating straight away.
+The mock does the same, in proportion to :paramref:`~mock_vws.MockVWS.processing_time_seconds` rather than to the real timings.
+
 Image targets which are not suited to detection are given 'failed' statuses.
 The criteria for these images is not defined by the Vuforia documentation.
 The mock is more forgiving than the real Vuforia Web Services.

src/mock_vws/target.py

@@ -149,16 +149,23 @@ def tracking_rating(self) -> int:
         """Return the tracking rating of the target recognition image."""
         pre_rating_time = datetime.timedelta(
             # That this is half of the total processing time is unrealistic.
-            # In VWS it is not a constant percentage.
+            # In VWS it is not a constant percentage: it was observed as
+            # roughly one second of a roughly thirty second processing time.
             seconds=float(self.processing_time_seconds) / 2,
         )
 
         timezone = self.upload_date.tzinfo
         now = datetime.datetime.now(tz=timezone)
         time_since_upload = now - self.upload_date
 
-        # The real VWS seems to give -1 for a short time while processing, then
-        # the real rating, even while it is still processing.
+        # The real VWS gives -1 for a short time after an upload, then the
+        # real rating, even while it is still processing.
+        #
+        # This is measured from the upload date rather than from the last
+        # modified date, so an update does not start a new -1 window. That
+        # matches the real VWS: an update returns a target to 'processing'
+        # and publishes the new image's rating straight away, without
+        # passing through -1 again.
         if time_since_upload <= pre_rating_time:
             return -1
 

tests/mock_vws/test_update_target.py

@@ -830,6 +830,41 @@ def test_invalid_type(
             result_code=ResultCodes.FAIL,
         )
 
+    @staticmethod
+    def test_rating_does_not_return_to_minus_one(
+        *,
+        image_file_success_state_low_rating: io.BytesIO,
+        high_quality_image: io.BytesIO,
+        vws_client: VWS,
+    ) -> None:
+        """An update does not start a new -1 tracking rating window.
+
+        A target reports a rating of -1 for a short time after it is
+        uploaded, and then the image's rating, while it is still
+        processing. An update returns the target to the processing
+        state, but the rating does not go back to -1: the new image's
+        rating is reported straight away.
+
+        Anyone who polls for an update to be processed by watching the
+        rating leave -1, rather than by watching the status, would wait
+        forever, so the mock must not offer them a window which the real
+        Vuforia does not have.
+        """
+        target_id = vws_client.add_target(
+            name=uuid.uuid4().hex,
+            width=1,
+            image=image_file_success_state_low_rating,
+            active_flag=True,
+            application_metadata=None,
+        )
+
+        vws_client.wait_for_target_processed(target_id=target_id)
+
+        vws_client.update_target(target_id=target_id, image=high_quality_image)
+
+        target_details = vws_client.get_target_record(target_id=target_id)
+        assert target_details.target_record.tracking_rating in range(6)
+
     @staticmethod
     def test_rating_can_change(
         *,