Get Progress of a Test on Demand

Last modified on March 25, 2021

After you have started a test on demand with test_type set to Fullpage or Non-Fullpage, use this operation to check the test progress or completion status (success or error). Call this operation repeatedly until you get a progress value other than 1 (which means “test in progress”), then examine the response to find out the test status.

Request URL

GET https://api.alertsite.com/api/v3/tests/{id}

where {id} is the test ID returned by GET /tests.

Authentication

The request must include the Authorization header containing a user’s access token:

Authorization: Bearer ACCESS_TOKEN

See Authentication for more information.

Response body

A successful check returns HTTP status 200 and with one of the following response bodies.

  • The test is in progress:

    {
      "progress": 1,
      "progress_desc": "Test In Progress",
      "status": -1,
      "status_desc": ""
    }

  • The test has finished successfully:

    {
      "progress": 2,
      "progress_desc": "Test Successful",
      "status": 0,
      "status_desc": "Site is OK Now!"
    }

    To view the test results, navigate to result_url returned by the GET /tests request you used to start the test.

  • The test has finished with an error. Here, status is the AlertSite error code and status_desc is the description of the error:

    {
      "progress": 3,
      "progress_desc": "Test Failed",
      "status": 51,
      "status_desc": "Warning-Unable to resolve IP"
    }

    To view the test results, navigate to result_url returned by the GET /tests request you used to start the test.

  • The specified test ID was not found:

    {
      "progress": 0,
      "progress_desc": "Test Not Found",
      "status": -1,
      "status_desc": ""
    }

Try it out

Click here to test this operation in AlertSite’s interactive API console.

Code examples

cURL

Checks the status of test 1234:

curl https://api.alertsite.com/api/v3/tests/1234 -H "Authorization: Bearer ACCESS_TOKEN"

Python

This code runs a test on demand for https://smartbear.com and outputs the test status.

Python

# Python 3.5+
import requests  # Requests library http://docs.python-requests.org
import json

baseUrl = 'https://api.alertsite.com/api/v3'
username = 'demo@example.com'  # Replace with your AlertSite login email
password = 'pa55w0rd'          # Replace with your AlertSite password

tod_params = {
    'url': 'https://smartbear.com',  # URL to test
    'test_type': 'Fullpage'
}

# Log in
payload = {'username': username, 'password': password}
r = requests.post(baseUrl + '/access-tokens', data=json.dumps(payload), headers={'Content-Type': 'application/json'})
token = r.json()['access_token']

print('Starting a test on demand with parameters:')
for param in tod_params:
    print('  ', param, ':', tod_params[param])

# Run a test on demand
r = requests.get(baseUrl + '/tests', params=tod_params, headers=auth_header)
if r.ok:
    if 'message' in r.json():
        # The test has started but its progress cannot be checked.
        # Test results will be added to the run history or sent via email.
        print(r.json()['message'])
        quit()
    else:
        test_id = r.json()['test_id']
        print('Test ID:', test_id)
        result_url = r.json()['result_url']

        # Check the test progress repeatedly until the test has finished
        tod_status_url = baseUrl + '/tests/' + str(test_id)
        while True:
            r = requests.get(tod_status_url, headers=auth_header)
            if not r.ok or r.json()['progress'] != 1:
                break
            print('Checking test progress...')
            time.sleep(1.5)

        # Check if the test passed or failed
        if r.ok:
            progress = r.json()['progress']
            if progress == 2:
                print('Test has finished successfully.')
                print('Navigate to this page to see the test results:\n', result_url, sep='\n')
            elif progress == 3:
                print('Test has finished with error {status}: {status_desc}'.format(**r.json()))
                print('Navigate to this page to see the test results:\n', result_url, sep='\n')
            elif progress == 0:
                print('Invalid test ID:', test_id)
            else:
                print('Unexpected error')
        else
            print('An error occurred while running a test on demand.', *r.json()['errors'], sep='\n')
else:
    print('Could not start a test on demand.', *r.json()['errors'], sep='\n')

See Also

Test on Demand Operations

Highlight search results