Skip to content

Commit 6cd8bb5

Browse files
adamtheturtleadamtheturtle
authored
Merge pull request #776 from adamtheturtle/remove-mock
Continue removing the mock
2 parents 269cb72 + bb9d19b commit 6cd8bb5

File tree

2 files changed

+4
-314
lines changed

2 files changed

+4
-314
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 3 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Contributing to VWS Python Mock
2-
===============================
1+
Contributing to VWS Python
2+
==========================
33

44
Contributions to this repository must pass tests and linting.
55

@@ -45,148 +45,18 @@ To fix some lint errors, run the following:
4545
Running tests
4646
-------------
4747

48-
Create an environment variable file for secrets:
49-
50-
.. code:: sh
51-
52-
cp vuforia_secrets.env.example vuforia_secrets.env
53-
54-
Some tests require Vuforia credentials.
55-
To run these tests, add the Vuforia credentials to the file ``vuforia_secrets.env``.
56-
See “Connecting to Vuforia”.
57-
58-
Then run ``pytest``:
48+
Run ``pytest``:
5949

6050
.. code:: sh
6151
6252
pytest
6353
64-
Connecting to Vuforia
65-
---------------------
66-
67-
To connect to Vuforia, Vuforia target databases must be created via the Vuforia Web UI.
68-
Then, secret keys must be set as environment variables.
69-
70-
The test infrastructure allows those keys to be set in the file ``vuforia_secrets.env``.
71-
See ``vuforia_secrets.env.example`` for the environment variables to set.
72-
73-
Do not use a target database that you are using for other purposes.
74-
This is because the test suite adds and deletes targets.
75-
76-
To create a target database, first create a license key in the `License Manager <https://developer.vuforia.com/targetmanager/licenseManager/licenseListing>`__.
77-
Then, add a database from the `Target Manager <https://developer.vuforia.com/targetmanager>`__.
78-
79-
To find the environment variables to set in the ``vuforia_secrets.env`` file, visit the Target Database in the Target Manager and view the “Database Access Keys”.
80-
81-
Two databases are necessary in order to run all the tests.
82-
One of those must be an inactive project.
83-
To create an inactive project, delete the license key associated with a database.
84-
85-
Targets sometimes get stuck at the “Processing” stage meaning that they cannot be deleted.
86-
When this happens, create a new target database to use for testing.
87-
88-
Skipping some tests
89-
-------------------
90-
91-
Set either ``SKIP_MOCK`` or ``SKIP_REAL`` to ``1`` to skip tests against the mock, or tests against the real implementation, for tests which run against both.
92-
9354
Travis CI
9455
---------
9556

9657
Tests are run on Travis CI.
9758
The configuration for this is in ``.travis.yml``.
9859

99-
Travis CI is set up with secrets for connecting to Vuforia.
100-
These variables include those from ``vuforia_secrets.env.example``.
101-
102-
To avoid hitting request quotas and to avoid conflicts when running multiple tests in prallel, we use multiple target databases.
103-
104-
Travis builds use a different credentials file depending on the build number.
105-
For example, build 2045.1 will use a different credentials file to build 2045.2.
106-
This should avoid conflicts, but in theory the same credentials file may be run across two Pull Request builds.
107-
This may cause errors.
108-
109-
How to set Travis CI secrets
110-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111-
112-
Create environment variable files for secrets:
113-
114-
.. code:: sh
115-
116-
mkdir -p ci_secrets
117-
cp vuforia_secrets.env.example ci_secrets/vuforia_secrets_1.env
118-
cp vuforia_secrets.env.example ci_secrets/vuforia_secrets_2.env
119-
...
120-
121-
Add Vuforia credentials for different target databases to the new files in the ``ci_secrets/`` directory.
122-
Add as many credentials files as there are builds in the Travis matrix.
123-
All credentials files can share the same credentials for an inactive database.
124-
125-
Install the Travis CLI:
126-
127-
.. code:: sh
128-
129-
gem install travis --no-rdoc --no-ri
130-
131-
Add the encrypted secrets files to the repository and Travis CI:
132-
133-
.. code:: sh
134-
135-
make update-secrets
136-
137-
Note that the `Travis CI documentation <https://docs.travis-ci.com/user/encrypting-files/#Caveat>`__ warns that this might not work on Windows.
138-
139-
Travis CI Settings
140-
~~~~~~~~~~~~~~~~~~
141-
142-
All targets are deleted from the database between each test.
143-
Therefore there may be conflicts if the test suite is run concurrently as Travis CI is configured to connect to one Vuforia database.
144-
As such, Travis CI is configured not to run multiple instances of the test suite concurrently.
145-
146-
Learnings about VWS
147-
-------------------
148-
149-
Vuforia Web Services, at the time of writing, does not behave exactly as documented.
150-
151-
The following list includes details of differences between VWS and expected or documented behaviour.
152-
153-
When attempting to delete a target immediately after creating it, a ``FORBIDDEN`` response is returned.
154-
This is because the target goes into a processing state.
155-
156-
``image`` is required for ``POST /targets``, but it is documented as not mandatory.
157-
158-
The ``tracking_rating`` returned by ``GET /targets/<target_id>`` can be -1.
159-
160-
The database summary from ``GET /summary`` has multiple undocumented return fields.
161-
162-
The database summary from ``GET /summary`` has is not immediately accurate.
163-
164-
Some of the `Vuforia Web Services documentation <https://library.vuforia.com/articles/Training/Image-Target-Guide>`__ states that “The size of the input images must 2 MB or less”.
165-
However, other `Vuforia Web Services documentation <https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query>`__ is more accurate: “Maximum image size: 2.1 MPixel.
166-
512 KiB for JPEG, 2MiB for PNG”.
167-
168-
The documentation page `How To Perform an Image Recognition Query`_ states that the ``Content-Type`` header must be set to ``multipart/form-data``.
169-
However, it must be set to ``multipart/form-data; boundary=<BOUNDARY>`` where ``<BOUNDARY>`` is the boundary used when encoding the form data.
170-
171-
The documentation page `How To Perform an Image Recognition Query`_ states that ``Content-Type`` will be the only response header.
172-
This is not the case.
173-
174-
The documentation page `How To Perform an Image Recognition Query`_ states that 10 is the maximum allowed value of ``max_num_results``.
175-
However, the maximum allowed value is 50.
176-
177-
A response to an invalid query may have an ``application/json`` content type but include text (not JSON) data.
178-
179-
After deleting a target, for up to approximately 30 seconds, matching it with a query returns a 500 response.
180-
181-
A target with the name ``\uffff`` gets stuck in processing.
182-
183-
The documentation page `How To Perform an Image Recognition Query`_ states that "The API accepts requests with unknown data fields, and ignore the unknown fields.".
184-
This is not the case.
185-
186-
The documentation page `How To Perform an Image Recognition Query`_ states "Maximum image size: 2.1 MPixel. 512 KiB for JPEG, 2MiB for PNG".
187-
However, JPEG images up to 2MiB are accepted.
188-
189-
.. _How To Perform an Image Recognition Query: https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query
19060

19161
Performing a release
19262
--------------------

‎README.rst‎

Lines changed: 1 addition & 181 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
vws-python
44
==========
55

6-
Python mock for the Vuforia Web Services (VWS) API and the Vuforia Web Query API.
6+
Python library for the Vuforia Web Services (VWS) API and the Vuforia Web Query API.
77

88
Contributing
99
------------
@@ -24,186 +24,6 @@ For now it is possible to install the work in progress:
2424
This requires Python 3.6+.
2525
Get in touch with ``adamdangoor@gmail.com`` if you would like to use this with another language.
2626

27-
Mocking Vuforia
28-
---------------
29-
30-
Requests made to Vuforia can be mocked.
31-
Using the mock redirects requests to Vuforia made with ``requests`` to an in-memory implementation.
32-
33-
.. code:: python
34-
35-
import requests
36-
from mock_vws import MockVWS
37-
38-
with MockVWS():
39-
# This will use the Vuforia mock.
40-
requests.get('https://vws.vuforia.com/summary')
41-
42-
However, an exception will be raised if any requests to unmocked addresses are made.
43-
44-
Allowing HTTP requests to unmocked addresses
45-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46-
47-
This can be done by setting the parameter ``real_http`` to ``True`` in either the context manager’s instantiation.
48-
49-
For example:
50-
51-
.. code:: python
52-
53-
import requests
54-
from mock_vws import MockVWS
55-
56-
with MockVWS(real_http=True):
57-
# This will use the Vuforia mock.
58-
requests.get('https://vws.vuforia.com/summary')
59-
# No exception is raised when a request is made to an unmocked address.
60-
requests.get('http://example.com')
61-
62-
Authentication
63-
~~~~~~~~~~~~~~
64-
65-
Connecting to the Vuforia Web Services requires an access key and a secret key.
66-
The mock also requires these keys as it provides realistic authentication support.
67-
68-
By default, the mock uses random strings as the access and secret keys.
69-
70-
It is possible to access these keys when using the context manager as follows:
71-
72-
.. code:: python
73-
74-
from mock_vws import MockVWS
75-
76-
with MockVWS() as mock:
77-
access_key = mock.server_access_key
78-
secret_key = mock.server_secret_key
79-
80-
To set custom keys, set any of the following parameters in the context manager’s instantiation:
81-
82-
- ``server_access_key``
83-
- ``server_secret_key``
84-
- ``client_access_key``
85-
- ``client_secret_key``
86-
87-
The mock does not check whether the access and secret keys are valid.
88-
It only checks whether the keys used to set up the mock instance match those used to create requests.
89-
90-
Setting the database name
91-
~~~~~~~~~~~~~~~~~~~~~~~~~
92-
93-
This can be done with the ``database_name`` parameter.
94-
By default this is a random string.
95-
96-
Mocking error states
97-
~~~~~~~~~~~~~~~~~~~~
98-
99-
Sometimes Vuforia is in an error state, where requests don’t work.
100-
You may want your application to handle these states gracefully, and so it is possible to make the mock emulate these states.
101-
102-
To change the state, use the ``state`` parameter when calling the mock.
103-
104-
.. code:: python
105-
106-
import requests
107-
from mock_vws import MockVWS, States
108-
109-
def my_function():
110-
with MockVWS(state=States.PROJECT_INACTIVE) as mock:
111-
...
112-
113-
The states available in ``States`` are:
114-
115-
- ``WORKING``.
116-
This is the default state of the mock.
117-
- ``PROJECT_INACTIVE``.
118-
This happens when the license key has been deleted.
119-
120-
The mock is tested against the real Vuforia Web Services.
121-
This ensures that the implemented features of the mock behave, at least to some extent, like the real Vuforia Web Services.
122-
However, the mocks of these error states are based on observations as they cannot be reliably reproduced.
123-
124-
Custom base URLs
125-
~~~~~~~~~~~~~~~~
126-
127-
``MockVWS`` mocks the Vuforia Web Services (VWS) API and the Vuforia Web Query API.
128-
These APIs have base URLs ``https://vws.vuforia.com`` and ``https://cloudreco.vuforia.com`` respectively.
129-
130-
``MockVWS`` takes the optional parameters ``base_vws_url`` and ``base_vwq_url`` to modify the base URLs of the mocked endpoints.
131-
132-
Processing time
133-
~~~~~~~~~~~~~~~
134-
135-
Vuforia Web Services processes targets for varying lengths of time.
136-
The mock, by default, processes targets for half a second.
137-
To change the processing time, use the ``processing_time_seconds`` parameter.
138-
139-
Differences between the mock and the real Vuforia Web Services
140-
--------------------------------------------------------------
141-
142-
The mock attempts to be realistic, but it was built without access to the source code of the original API.
143-
Please report any issues `here <https://github.com/adamtheturtle/vws-python/issues>`__.
144-
There is no attempt to make the image matching realistic.
145-
146-
Speed and summary accuracy
147-
~~~~~~~~~~~~~~~~~~~~~~~~~~
148-
149-
The mock responds much more quickly than the real Vuforia Web Services.
150-
151-
Targets in the mock are set to ‘processing’ for half a second by default.
152-
This is customisable, with the ``processing_time_seconds`` parameter.
153-
In the real Vuforia Web Services, the processing stage takes varying lengths of time.
154-
155-
The database summary in the real Vuforia Web Services takes some time to account for images.
156-
Sometimes the real summary skips image states such as the processing state.
157-
The mock is accurate immediately.
158-
159-
Image quality and ratings
160-
~~~~~~~~~~~~~~~~~~~~~~~~~
161-
162-
Targets are assigned a rating between 0 and 5 of how good they are for tracking purposes.
163-
In the mock this is a random number between 0 and 5.
164-
165-
Image targets which are not suited to detection are given ‘failed’ statuses.
166-
The criteria for these images is not defined by the Vuforia documentation.
167-
The mock is more forgiving than the real Vuforia Web Services.
168-
Therefore, an image given a ‘success’ status by the mock may not be given a ‘success’ status by the real Vuforia Web Services.
169-
170-
When updating an image for a target on the real Vuforia Web Services, the rating may stay the same.
171-
The mock changes the rating for a target to a different random number when the image is changed.
172-
173-
Matching targets in the processing state
174-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175-
176-
Matching a target which is in the processing state sometimes returns a successful response with no results.
177-
Sometimes a 500 (INTERNAL SERVER ERROR) response is given.
178-
The mock always gives a 500 response.
179-
180-
Matching deleted targets
181-
~~~~~~~~~~~~~~~~~~~~~~~~
182-
183-
Matching a target which has been deleted returns a 500 (INTERNAL SERVER ERROR) response within the first few seconds.
184-
This timeframe is not consistent on the real Vuforia Web Services.
185-
On the mock, this timeframe is three seconds by default.
186-
``MockVWS`` takes a parameter ``query_recognizes_deletion_seconds`` to change this.
187-
188-
Accepted date formats for the Query API
189-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190-
191-
The Query API documentation is not clear on which date formats are expected exactly in the ``Date`` header.
192-
The mock is strict.
193-
That is, it accepts only a few date formats, and rejects all others.
194-
If you find a date format which is accepted by the real Query API but rejected by the mock, please create a GitHub issue.
195-
196-
Targets stuck in processing
197-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
198-
199-
On the real Vuforia Web Services, targets sometimes get stuck in the processing state.
200-
For example, targets with the name ``\uffff`` get stuck in the processing state.
201-
On the mock, no targets get stuck in the processing state.
202-
203-
Database summary quotas
204-
~~~~~~~~~~~~~~~~~~~~~~~
205-
206-
The database summary endpoint returns quotas which match the quotas given for a free license.
20727

20828
.. |Build Status| image:: https://travis-ci.org/adamtheturtle/vws-python.svg?branch=master
20929
:target: https://travis-ci.org/adamtheturtle/vws-python

0 commit comments

Comments
 (0)