How to Test GPS End to End

Owned by Diarmid Mackenzie
Last updated: Aug 06, 2020
10 min read

This is quite a technical article, which covers lots of detail about different possible set-ups for PathCheck GPS Test Environments, how to choose between them and how to set them up.

If you just want a basic intro to GPS end to End Function, try this link instead:

GPS Function End to End - Basic Intro Video

 

Key Concepts

Safe Places & PathCheck GPS Mobile App

Safe Places is a Web Application deployed at Health Departments for use by Contact Tracers to analyze, redact and publish location data shared by community members.

The PathCheck GPS Mobile App (referred to later as “Mobile App”) is the Mobile App (Android and iOS) that community members use to privately store their location history, share that history with Health Department Contact Tracers, and monitor published “points of concern” for Exposure Notifications.

For historical reasons, in some contexts the PathCheck GPS Mobile App may be referred to as “Safe Paths” - though we are trying to phase out this name.

End-to-End Testing

By this, we mean testing the Mobile App, together with an instance of the Safe Places software. It is possible (and sometimes desirable) to test the Mobile App in isolation, or Safe Places in isolation - See this article for some notes on what other options are available: Testability of Safe Places - PathCheck GPS Mobile App interactions

Integration Points

There are 2 key functions of the Mobile App that interact with Safe Places

  • Location Data Sharing. This requires that a key is generated by the Safe Places user, and entered into the Mobile App by the user who wants to share their data. The data can then be viewed and managed within Safe Places.

  • Exposure Notifications. This depends on the Mobile App downloading a set of “points of concern” from the Health Department. These points of concern are published by Safe Places.

SafePlaces Endpoints

SafePlaces Endpoints are URLs that offer a particular service. For end-to-end testing, there are 2 key Endpoints, corresponding to the 2 integration points above.

  • Location Data Sharing uses the Ingest API URL

  • Exposure Notifications use the Cursor URL

These URLs will take different values for each Safe Places instance.

YAML file

YAML files contain the data about the Health Departments that are available, including the Safe Places instance and API Endpoints that are available.

We have several YAML files, for example

Each YAML file lists a number of Health Departments, each of which has a Safe Places instance, and details of the API Endpoints used by that Safe Places Instance.

The “public_api” parameter points to the Ingest API for the Safe Places instance

The “cursor_url” parameter points to the Cursor URL for the Safe Places instance

Which YAML file does the Mobile App use?

The YAML file to use is hardcoded in the App.

  • Alpha, Beta and Production builds all point to the Production YAML file

  • Developer & Develop builds point to the Staging YAML file.

    • Note that while these builds can easily be distributed on Android as APKs, there are technical difficulties distributing these builds on iOS.

  • Custom builds can be created to point to bespoke YAML files.

  • It is also possible, using a Feature Flag, to manually conigure any YAML file in the app. When this is configured, this YAML file is used in addition to to the data in the hardcoded YAML file.

Data

You can enable Feature Flags in the “About” screen by tapping 10x on “PathCheck GPS” to then add data points into the app, see Getting 14d of data onto a phone (or into Safe Places)

Examples:

10 data points: https://diarmidmackenzie.pythonanywhere.com/location-data?latitude=42&longitude=13&points=10

4032 data points: https://diarmidmackenzie.pythonanywhere.com/location-data?longitude=42&latitude=13&points=4032

Privacy and Safe Places

At the time of writing (July 8 2020) Safe Places is implemented in such a way that any user who has access to the system, has access to all the location data that has been uploaded to the system.

While this is not a huge concern in production (where only vetted Contact Tracers should have log-in details), on test systems this means that any tester who has access to the system, has access to all the location data uploaded to the system.

For Privacy reasons, we want to take some care not to give wide open access to a very large number of testers.

Therefore, when we bring in crowdsource test organizations like Applause, to protect both their testers, and our testers, we prefer to have them work with their own private Safe Places instance.

Individual testers with particular privacy concerns may prefer to work with a personal Safe Places instance, rather than a shared instance. If you’d like help or support here, or have other privacy-related concerns, please talk to @Diarmid Mackenzie or @Adam Leon Smith

Testing End-to-End - Example Setups

Key decisions

To test end to end, you need to make some key decisions:

  1. Which Safe Places instance am I using?

  2. Which YAML file will I use to provide the App woth the details of this Safe Places instance

  3. How will the App be set up to use this YAML file?

Example 1 - Testing with a HD’s Production Deployment

This is a straightforward set-up:

  1. You will be using the HD’s Production Safe Places instance

  2. You will use the Production YAML

  3. Any Alpha, Beta or Production App build will automatically read the production YAML file.

So setup is easy - however this kind of testing will quickly hit restrictions:

  • When you come to share data, you will need someone from the HD to provide you with an access code for data sharing. (we assume that HDs will not be giving out Safe Places login credentials to PathCheck testers!).

  • If you want to test Exposure Notifications, you’ll only be able to test against the data that the Health Department publishes (i.e. real data about real COVID patients). This will limit Exposure Notification testing, especially if you are not in the geographic area served by the HD.

Example 2 - Testing with a HD’s Pre-production Deployment

Some HDs may be doing testing with their own pre-production Safe Places instance.

Depending on the situation…

  • Testers may have access to the Safe Places system

  • It may be OK for testers to push test points of concern (i.e. points that don’t correspond to a real COVID infection) to the Safe Places published points of concern.

In terms of the 3 key setup questions…

  1. The tester will be using the HD’s Pre-production Safe Places instance

  2. The details of this Safe Places instance won’t be in the Production YAML, so they will need to be included in some other YAML file. This could be…

    • A bespoke YAML file created just for this HD. It just needs to be hosted somewhere where it can be downloaded over HTTPS - e.g. GitHub, or any other web server with HTTPS

    • An entry in the Staging YAML file. (note this file is in version control, so changes require a PR, which is not super-convenient).

  3. There are a few options here:

    • Use a Development build, which natively points towards the Staging YAML file.

    • Using any build, use the Feature Flag capability, and manually enter the URL of the YAML file. This will work whatever YAML file is used (even with the Staging or Production YAML files).

    • Note that Feature Flags are available in all Mobile App builds, even the one you get from the production App Store.

Example 3 - Testing with our internal Safe Places instances

We have 3 internal Safe Places instances

  • Dev - intended for us by the Development team. Might be unstable.

  • Staging - intended for use by Test/QA. We try to keep this fairly stable.

  • Demo - intended for use for Demos. Must remain very stable. Do not fill this with junk data!

Access details for these can be found on Slack in a pinned post in the “scrum_team_safe_places” channel, and also the “safe_places_testing” channel.

At time of writing, details are as follows, but if these don’t work, please check the Slack channels for latest info:

Username : safeplaces@extremesolution.com
Password : Wx$sRj3E

On slack you can also find details of the API endpoints, but you shouldn’t need to worry about those details, because they should all be kept up-to-date in the Staging YAML.

To test with one of these…

  1. Pick the Safe Places instance that is suitable for your needs. Typically Staging for testers, but there may be good reasons to use Dev or Demo.

  2. The Staging YAML file contains all the details you need.

  3. If you use an Alpha, Beta or Production build, this will natively point to the Production YAML file, so the best solution is to use the Feature Flag to manually add the Staging YAML file as well.

    • Here’s a URL to copy/past for that purpose:

    • https://raw.githubusercontent.com/Path-Check/trusted-authorities/master/staging/authorities.1.0.1.yaml

    • (you can get this by clicking the “Raw” button in the top right of the fiel viewer in GitHub)

Example 4 - Testing with a private Safe Places instances (e.g. Applause)

By “private” Safe Places instance, we mean an instance which is reserved for use by a specific known group of testers. This is distinct from a “personal” Safe Places instance (see below), which is used by just a single tester.

For Applause, we have set up a private Safe Places instance. We may do the same for other groups of testers that we want to partition from the main test setup, for mutual privacy reasons.

For these testers

  1. They will use a Private Safe Places instance

  2. We create a bespoke YAML file for these testers

  3. These testers are directed to configure this YAML file using the available Feature Flag.

In future we may move to an alternative design whereby:

  • This system is included in the Staging YAML file

  • These testers have a build which natively points to the Staging YAML file.

This would simplify things for these testers (no need to configure a YAML file manually, and no need to use Feature Flags. However it complicates our build system…

Until we have the ability to provide a build that points natively to the Staging YAML, there’s no point in putting instances like the Appluase instance into the Staging YAML: those testers will have to configure a manual YAML file anyway, and it’s as easy for them to configure a bespoke YAML file with just their Safe Places instance.

Example 5 - Testing with a personal Safe Places instance

Some testers may wish to run a personal Safe Places instance, for their own sole use. This may be for privacy reasons, or becuase they want to test out some bespoke code changes, some new infrastructure arrangements etc.

Setting up a personal Safe Places instance is not trivial, and it’s beyond the scope of this article to explain how to do that - there is some guidance in the Safe Places repos:
https://github.com/Path-Check/safeplaces-backend
https://github.com/Path-Check/safeplaces-frontend

For end-to-end testiness with a personal Safe Places instance, answers to the setup questions will typically be:

  1. Use a personalSafe Places instance

  2. Create a bespoke YAML file for this instance or add this instance to the staging YAML file.

  3. EIther use a Development / Develop app build that natively uses the staging YAML, or configure the relevant YAML file using the available Feature Flag.

Testing End-to-End - How to Test

Sharing Location Data

For details & screenshots see here: GPS Mobile App - Overview of Function

In summary:

If Health Department is already available in the App for Location Sharing:

Note that at this point you could also “Create Record Manually” by selecting location points on the map. The following instructions relate to “Check Data Upload”

  • In the Mobile App, click “Share Location History” icon, allow Location Sharing (if you haven’t done so already), select the appropriate Health Department, then enter the code that was generated by Safe Places

  • Agree to all the various consents, until you get to “Done”

  • Back in Safe Places, click on “Check Data Upload” - if all is well, you should now see the data points on a map.

If Health Department is not yet available in the App:

  • Enable Feature Flags in the “About” screen by tapping 10x on “PathCheck GPS”

  • Under More / Feature Flags, enable “Custom Yaml URL”

  • Under Health Departments, choose “Manually Add Via URL”

  • Enter the URL of the YAML file that contains details of the Health Department (see “Key Concepts” and “Example Setups” above if you aren’t clear what this means!)

  • Once this is entered, your Health Department should now be available in the App for Location Sharing, so you can now perform the process above.


Publishing Location Data

To add details (Safe Places not working right now to confirm exact flows and grab screenshots.

(note you can also manually add data points).

  • Once the data is loaded, click “Stage All Data For Publishing”, then “Yes, I received consent” as below

  • Select “Publish Data” from the top menu

  • Click “Load Data For Publishing”

  • A popup will appear, select the correct data record and click “Open Selected Data”

  • Select “Submit All Data For Publishing” and the following popup screen will appear..

  • Select “Submit All Data For Publishing”

  • You are now all done!

Note: You can change the API endpoint in the Configuration screen here: https://safeplaces.extremesolution.com/settings/configuration

 

 

Generating Exposure Notifications

In the Health Departments screen in the Mobile App, click on the relevant Health Department so that a green check appears.

The App should now download this published location data.

If you published location data that came from this device, then it should generate Exposure Notifications for all the times that it had recorded locations (except for any data you may have redacted in Safe Places).

If you published location data that came from a different device, or was created manually, then results will vary depending on the level of overlap with location points stored on this device.

Note that Exposure Notifications only trigger if > 66% of points within a 30 minute period match (i.e. 4 or more points in a 30 minute period). These parameters can be changed in the data published by Safe Places, but there is not yet any Safe Places function to configure these.