Use this operation to:
- Run a test on demand for an existing monitor (except for BirBar monitors).
- Test an arbitrary URL.
- Run a traceroute or ping from one of the AlertSite locations to your server.
The operation functionality is similar to the Test on Demand command on the AlertSite UXM Dashboard, or the Support > Site Diagnostics menu in the AlertSite 1.0 console.
Tests can be run from both public AlertSite locations and private locations that are enabled for a test on demand. Private Node Server locations support a test on demand starting from v. 2.1.4.
Request URL
GET https://api.alertsite.com/api/v3/tests[?parameters]
Authentication
The request must include the Authorization header containing a user’s access token:
Authorization: Bearer ACCESS_TOKEN
See Authentication for more information.
Parameters
Request parameters depend on the type of the test you want to run.
Test a monitor
Use this to test a specific monitor immediately. A link to the test results will be returned in the response body.
GET https://api.alertsite.com/api/v3/tests?&monitor_id=...&location_id=...&test_type=[Fullpage|Non-Fullpage]&monitor_agent=...
monitor_id
Required. The ID of the monitor to test.
location_id
Optional. The ID of an AlertSite location to run the test from. If location_id is omitted, the test will be run from the monitor’s primary location.
See Location IDs to learn where to find the location IDs.
test_type
Optional, used only when testing website and DéjàClick monitors. Possible values:
-
Fullpage – (Default) Uses the Firefox browser to download the web page, including all of its images, scripts, CSS files, and other external files.
-
Non-Fullpage – Uses the Firefox browser to download just the page’s HTML, without images or other external files.
monitor_agent
Optional, used only when testing SoapUI and API endpoint monitors. Specifies the playback engine that will be used to run the monitor. Possible values:
- ReadyAPI 1.1 (for SoapUI monitors only)
- ReadyAPI 1.9 (default)
- TestEngine
| Note: | This option is ignored if location_id specifies a Private Node Server or InSite location. |
Test a URL
Use this to test an arbitrary URL using the Firefox browser. A link to the test results will be returned in the response body.
GET https://api.alertsite.com/api/v3/tests?&url=...&location_id=...&test_type=[Fullpage|Non-Fullpage]
url
Required. The URL to test, for example, http://example.com.
location_id
Optional. The ID of an AlertSite location to test the URL from. If omitted, the test will run from the primary location configured in your AlertSite account settings.
See Location IDs to learn where to find the location IDs.
test_type
Optional. Possible values:
-
Fullpage – (Default) Uses the browser to download the web page, including all of its images, scripts, CSS files, and other external files.
-
Non-Fullpage – Uses the browser to download just the page’s HTML, without images or other external files.
Production test (“run now”)
Use this to trigger an out-of-schedule, production test of a monitor. Results will be added to the monitor run history.
GET https://api.alertsite.com/api/v3/tests?&monitor_id=...&location_id=...[&test_type=AlertSite%20Test]
monitor_id
Required. The ID of the monitor to test.
location_id
Optional. The ID of an AlertSite location to run the test from. It must be one of this monitor’s locations. If location_id is omitted, the test will be run from the monitor’s primary location.
See Location IDs to learn where to find the location IDs.
test_type
Optional. If specified, must be AlertSite Test (or AlertSite%20Test when URL-encoded).
Ping or traceroute
Use this to ping a server or run a traceroute to a server from the specified AlertSite location. Results are sent via email.
GET https://api.alertsite.com/api/v3/tests?test_type=[Ping|Traceroute]&url=...&monitor_id=...&location_id=...&recipients=...
test_type
Required. Use Ping or Traceroute.
url or monitor_id
Required. Specify the tested domain name or IP address in the url parameter. Alternatively, you can specify monitor_id to ping or traceroute the domain monitored by this monitor.
url is ignored if monitor_id is specified.
location_id
Optional. The ID of an AlertSite location to run the test from. It can be a public location, or a private location that supports a test on demand.See Location IDs to learn where to find the location IDs.
If you test monitor_id and do not specify location_id, the test will be run from the monitor’s primary location.
If you test url and do not specify location_id, the test will run from the primary location configured in your AlertSite account settings.
recipients
Required. The list of email addresses to which the ping or traceroute results will be sent. Separate multiple addresses with commas or new lines.
Response body
On success, the operation returns HTTP status 200 with one of the following response bodies.
If test_type is Fullpage or Non-Fullpage:
{
"result_url": "https://www.alertsite.com/link_to_test_results",
"test_id": 213456
}
Use the returned test ID with GET /tests/{id} to track the test progress. Once the test has finished, navigate to result_url in a browser to view the test results.
If test_type is AlertSite Test:
{
"message": "AlertSite test has been queued to be processed. Your Console will be updated once the test is complete."
}
If test_type is Ping or Traceroute:
{
"message": "Your test has been submitted for processing. The results should arrive shortly via E-mail to the recipient(s) that you specified."
}
Try it out
Click here to test this operation in AlertSite’s interactive API console.
Code examples
cURL
Test https://smartbear.com from Atlanta (location ID 20):
curl https://api.alertsite.com/api/v3/tests?url=http://smartbear.com&location_id=20&test_type=AlertSite%20Test -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 = '[email protected]' # 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')