29 May, 2024

Developers

Automate Web Map and Map Service Testing with Postman

29 May, 2024

Developers

Ensuring consistency across environments.

One of the challenges when creating custom software in a multi-environment setup is ensuring that the environments are all in sync with each other. As an example, when working with ArcGIS Enterprise and ensuring that a web map is the same in the development environment as it is in the test, pre-production and production environments.

This becomes more evident when you have an application that relies on specific layers being in a map, popups being configured in a particular way, certain fields or all the correct fields being in a service.

We faced this challenge recently when working on a project based on Esri's Experience Builder. We had four environments, and we needed to ensure that as new layers were added to a map, popups configured, and services changed, that everything was the same across each environment before we could release the app in to that environment.

To achieve this, we used Postman to run a series of tests in a build pipeline to make sure that everything was configured as we expected.

I had used Postman previously for simple tasks such as interrogating an API and viewing the resulting data, however, you can take it further and add in tests for a request, group your requests together and run them in a CI/CD pipeline.

Prerequisites

Postman installed
An ArcGIS Enterprise environment

Create an Environment

An environment is a way within Postman to create a series of variables that can be applied to a collection of requests.

1. To create a new environment, open Postman and in the left sidebar, select Environments and then click the + button to create a new environment.

2. Give your new environment a meaningful name, and then we can start adding variables.

3. Add in five new variables:

baseURL - the base URL to your Enterprise environment (without the web adaptor).
username - The username to connect to enterprise with.
password - The password for the user.
itemId - The itemId of your web map
token - Leave this blank, we will assign a value to it.

Getting a token

Now that we have an environment, we can start creating our requests. We group these together in a collection.

1. Within Postman, in the sidebar, select Collections and then use the plus button to add a new collection.

2. Give your collection a meaningful name

3. The first thing we need to do in order to access ArcGIS Enterprise, is get a token that we can use in all our requests. Find the collection in the list of collections and select Add a request.

5. Name the new request Get Token and set it as a POST request.

6. Set the environment to the one we created earlier; the drop down is in the top right corner of Postman.

7. Enter the following for the URL of the request.

https://{{baseURL}}/portal/sharing/rest/generateToken?f=json

The curly brackets indicate that we are substituting in our baseURL from the environment.

8. Next select the body tab, ensure that form-data is selected and enter the following.

Again, we are pulling values from our environment to make the request.

9. Save the request and hit the Send button to see if everything is working as expected.

You should hopefully see something like the below in the response pane.

10. So now we can generate a token, we want to assign it to our environment so we can use it in all subsequent requests we make. To do this, select the Tests tab.

11. The tests tab allows us to write tests against the response from the request, it also allows us to extract information from the response and assign it to our environment. Copy and paste the following in to the tests section.

pm.test("The response has all properties", () => {
    const responseJson = pm.response.json();
    pm.expect(responseJson).to.have.all.keys('token', 'expires','ssl');
    pm.expect(responseJson.ssl).to.eql(true);
    pm.environment.set("token",responseJson.token)
});

The above is a single test with some assertions, where pm is the Postman object.

We can get the response as a JSON object by calling:
pm.response.json()

Using the object returned, we can then test the response, we check that we have the expected keys.
pm.expect(responseJson).to.have.all.keys('token', 'expires','ssl');

We then test that the sll key is set to true.
pm.expect(responseJson.ssl).to.eql(true);

Then if all this is correct, we then set the "token" variable of our environment to the returned token.
pm.environment.set("token",responseJson.token)

12. Save the request with the new test and run it again, this time you should see the tests running.

Now we have a token, we can move on to testing our web map.

Testing a web map item

1. Add a new request to the collection, by clicking the ellipsis next to the collection name, call it Test Web Map Item.

2. Leave the request as a GET and add in the following URL.

https://{{baseURL}}/portal/sharing/rest/content/items/{{itemId}}/?token={{token={{token}}&f=json

3. Save the request and send it. You should see the item details of your web map returned.

4. We can test to make sure that these values match what we expect, one useful thing to test is that the initial extent is what we expect. This ensures that the map will always open at the expected extent in each environment. To do that, switch to the Tests tab, and add in a const at the top of the screen with what we expect the extent to be.

const extent =   [
        [
            163,
            -47
        ],
        [
            180,
            -33
        ]
    ]

5. With this in place, we can then extract the results from our web map item and check that it matches what we expect.

pm.test("Map has the correct lower longtitude", () => {
const responseJson = pm.response.json();
pm.expect(responseJson.extent[0][0]).equals(extent[0][0])
});

pm.test("Map has the correct lower latitude", () => {
const responseJson = pm.response.json();
pm.expect(responseJson.extent[0][1]).equals(extent[0][1])
});

pm.test("Map has the correct upper longtitude", () => {
const responseJson = pm.response.json();
pm.expect(responseJson.extent[1][0]).equals(extent[1][0])

});

pm.test("Map has the correct upper latitude", () => {
const responseJson = pm.response.json();
pm.expect(responseJson.extent[1][1]).equals(extent[1][1])
});

6. Save the request and send it again to see the results. If a test fails, it will give an error similar to the following, this is why it is important to use descriptive names for your tests.

Testing web map data

Now we know how to test the item details of a web map, we can take this further and start to test that the layers, tables, popups and bookmarks within the web map match what we expect.

1. As above, add a new request to your collection and call it Test Web Map Content and add the following URL.

https://{{baseURL}}/portal/sharing/rest/content/items/{{itemId}}/data?token={{token}}&f=json

2. Save and send the request, you should see the web map JSON returned.

3. As above we can now create some constants in the Tests section and ensure that we have the number of layers and tables:

We have the correct layer ids:

We have the correct default layer visibility:

That the visibility settings are correct:

The popup matches what we expect (note this is a pretty high-level test you could get really detailed if you wanted).

As you can see below, you can add any number of tests to ensure that you are always using the expected web map.

Running a collection

You can run all requests within a collection in a single operation, by selecting Run Collection.

A new page will open which will let you set the number of iterations of the test you would like to run, and let you rearrange the order in which your tests will run. (You should probably run the generate token request first though).

After hitting Run, you will see a summary of the results of the requests and tests.

Testing Services

Using the same methods, you can also test services in your web map to ensure that they have the correct renderers, correct number of fields, that the correct domains exist and so forth.

1. Add a new request to your collection (or create a new one for the services) and call it Test Sample World Cities and set the URL to the following.

https://{{baseURL}}/server/rest/services/SampleWorldCities/MapServer?f=json&token={{token}}

2. At the service level we can now add tests to check if the correct number of layers exist in the map.

pm.test("Service has the correct number of layers", () => {
const responseJson = pm.response.json();
pm.expect(responseJson.layers.length).equals(3)
});

3. The name of the layer matches our expectation.

pm.test("First layer is named Cities", () => {
const responseJson = pm.response.json();
pm.expect(responseJson.layers[0].name).equals("Cities")
});

4. The geometry of the layer is correct.

pm.test("First layer is a point layer", () => {
const responseJson = pm.response.json();
pm.expect(responseJson.layers[0].geometryType).equals("esriGeometryPoint")
});

Once you understand how to extract the data and test it, the possibilities are endless... You can test other service types, e.g., Geoprocessing services to check the correct parameters, send requests and get results.

Running in a DevOps Pipeline

As I mentioned at the top of the page, if you are working in a multi environment situation, it can be useful to test that each environment is in sync, before pushing out any application that relies on the web map data and services data being correct.

To do this we can export our environment and collection from Postman and run them within an Azure DevOps build pipeline.

1. To export a collection, click the ellipsis next to the name and select Export.

2. You can do the same for an Environment:

3. These will produce JSON files that you can add to your repository, which can then be consumed in a pipeline. You can create a different environment for each environment that you want to test, eg dev, test, preprod and production.

4 Within Azure DevOps you can then add a Postman task to your build pipeline which will run your tests. You may need to add the Postman task to Azure DevOps from the Market Place first. https://marketplace.visualstudio.com/items?itemName=carlowahlstedt.NewmanPostman&targetId=a5f85cc1-9452-446a-a1c6-1984f3d63846

5. Once added use the assistant and search for Postman.