search

catchpoint / WebPageTest.api-nodejs

WebPageTest API wrapper for NodeJS
MIT License
1.64k stars 173 forks source link

readme

WebPageTest Logo

Learn about more WebPageTest API Integrations in our docs

WebPageTest API Wrapper for NodeJS

NPM Version NPM Downloads

WebPageTest API Wrapper is a NPM package that wraps WebPageTest API for NodeJS as a module and a command-line tool.

For a better understanding of WebPageTest API Wrapper, here are some sample Node Recipies

Getting started

npm install webpagetest -g

Basics

Command line

webpagetest test https://docs.webpagetest.org/api/integrations/ -k YOURAPIKEY

Docker

Build

docker build -t webpagetest-api .

Run

docker run -it --rm webpagetest-api -k YOURAPIKEY test https://docs.webpagetest.org/api/integrations/

Module

const WebPageTest = require("webpagetest");

const wptServer = "www.webpagetest.org";
const wpt = new WebPageTest(wptServer, "YOUR_API_KEY");

const siteToTest = "https://docs.webpagetest.org/api/integrations/";
wpt.runTest(siteToTest, (err, data) => {
  console.log(err || data);
});

Command Line

Help

webpagetest --help

Commands

Options

Common (works for all commands)

_The default WPT server can also be specified via environment variable WEBPAGETEST_SERVER_

Test (works for test command only)

API Key (works for test, restart,locations, testBalance and cancel commands)

Request (works for status, results, locations, testers and test commands)

Results (works for results and test commands)

Run (works for pagespeed, utilization, request, timeline, netlog, chrometrace, console, googlecsi, response, waterfall and screenshot commands)

Image (works for waterfall and screenshot commands)

Screenshot (works for screenshot command only)

Waterfall (works for waterfall command only)

Video (works for video command only)

Response (works for response command only)

Listen (works for listen command only)

Examples

1. Get API available locations

$ webpagetest locations -k YOURAPIKEY
{
  "response": {
    "statusCode": 200, "statusText": "Ok",
    "data": {
      "location": [
        ...
        {
          "id": "SanJose_IE9",
          "Label": "San Jose, CA USA (IE 9,Chrome,Firefox)",
          "location": "SanJose_IE9",
          "Browser": "IE 9",
          "PendingTests": {
            "p1": 0, "p2": 0, "p3": 0, "p4": 0, "p5": 2, "p6": 2, "p7": 0,
            "p8": 0, "p9": 0, "Total": 7, "HighPriority": 2, "LowPriority": 4,
            "Testing": 1, "Idle": 0
          }
        },
        ...
      ]
    }
  }
}

2. Run test on https://docs.webpagetest.org/api/integrations/ from San Jose on IE9

webpagetest test https://docs.webpagetest.org/api/integrations/ -k YOURAPIKEY --location SanJose_IE9
{
  "statusCode": 200,
  "statusText": "Ok",
  "data": {
    "testId": "121025_PT_N8K",
    "ownerKey": "868cb2813a0f376a977dd1a24ab041b4f12361b3",
    "jsonUrl": "https://www.webpagetest.org/results.php?test=121025_PT_N8K&f=json",
    "xmlUrl": "https://www.webpagetest.org/xmlResult.php?test=121025_PT_N8K",
    "userUrl": "https://www.webpagetest.org/results.php?test=121025_PT_N8K",
    "summaryCSV": "https://www.webpagetest.org/csv.php?test=121025_PT_N8K",
    "detailCSV": "https://www.webpagetest.org/csv.php?test=121025_PT_N8K&requests=1"
  }
}

3. Check current test status

webpagetest status 121025_PT_N8K -k YOURAPIKEY
{
  "statusCode": 101,
  "statusText": "Test Pending",
  "data": {
    "statusCode": 101,
    "statusText": "Test Pending",
    "testId": "121025_PT_N8K",
    "runs": 1,
    "fvonly": 0,
    "location": "SanJose_IE9"
  }
}

4. Get test results

webpagetest results 121025_PT_N8K -k YOURAPIKEY 
{
  "response": {
    "statusCode": 200, "statusText": "Ok",
    "data": {
      "testId": "121025_PT_N8K",
      "summary": "https://www.webpagetest.org/result/121025_PT_N8K/",
      "testUrl": "https://docs.webpagetest.org/api/integrations/",
      "location": "SanJose_IE9",
      "connectivity": "DSL",
      "bwDown": 1500, "bwUp": 384, "latency": 50, "plr": 0,
      "completed": "Thu, 25 Oct 2012 23:42:11 +0000",
      "runs": 1, "successfulFVRuns": 1,
      "average": {
        "firstView": {
          "loadTime": 3942, "TTFB": 1518,
          "bytesIn": 963405, "bytesInDoc": 431612,
          "requests": 32, "requestsDoc": 19,
          "render": 2509, "fullyLoaded": 7765,
          "docTime": 3942, "domTime": 0,
          "titleTime": 1641, "avgRun": 1
        }
      },
      ...
    }
  }
}

5. Get remaining tests count for the account

webpagetest testBalance -k YOURAPIKEY
{
    "data": {
        "remaining": 1175
    }
}

Run test on https://docs.webpagetest.org/api/integrations/ and poll results every 5 seconds timing out in 60 seconds

webpagetest test https://docs.webpagetest.org/api/integrations/ --poll 5 --timeout 60

Or run test on https://docs.webpagetest.org/api/integrations/ and wait for results listening on localhost* port 8000**

webpagetest test https://docs.webpagetest.org/api/integrations/ --wait 8000
{
  "response": {
    "statusCode": 200, "statusText": "Ok",
    "data": {
      "testId": "121025_PT_N8K",
      "testUrl": "https://docs.webpagetest.org/api/integrations/",
      ...
      "median": {
        "firstView": {
          "loadTime": 3942, "TTFB": 1518,
          "render": 2509, "fullyLoaded": 7765,
          ...
        }
      },
      ...
    }
  }
}

* hostname and port are optional, defaults to \<system hostname>:\<8000> ** localhost and port must be reacheable from WebPageTest server

Module

Methods and options (including the one letter shorthands) are the same when using as a Node module, however a more verbose version of both commands (methods) and options (parameters) are available and encouraged to use for code clarity.

Methods

Parameters

[
  {command1: 'value1'},
  {command2: 123},
  {command3: ['value1', 'value2', ... , 'valueN']},
  ...
  'commandN'}
]

Notes

const script = wpt.scriptToString([
  { logData: 0 },
  { navigate: "http://foo.com/login" },
  { logData: 1 },
  { setValue: ["name=username", "johndoe"] },
  { setValue: ["name=password", "12345"] },
  { submitForm: "action=http://foo.com/main" },
  "waitForComplete",
]);

wpt.runTest(script, (err, data) => {
  console.log(err || data);
});

Options

Common (works for all methods with options parameter)

Test (works with runTest and runTestAndWait)

API Key (works for runTest, runTestAndWait, restartTest and cancelTest methods)

Request (works for getTestStatus getResults getLocations getTesters runTest and runTestAndWait methods)

Results (works for getResults runTest and runTestAndWait methods)

Run (works for getPageSpeedData, getUtilizationData, getRequestData, getTimelineData, getNetLogData, getChromeTraceData, getConsoleLogData, getGoogleCsiData, getResponseBody, getWaterfallImage and getScreenshotImage methods)

Image (works for getWaterfallImage and getScreenshotImage methods)

Screenshot (works for getScreenshotImage method only)

Waterfall (works for getWaterfallImage method only)

Video (works for createVideo method only)

Response (works for getResponseBody method only)

Listen (works for listen method only)

Location (works for getLocations method only)

Examples

1. Instantiating

const WebPageTest = require("webpagetest");

const wpt = new WebPageTest("my-wpt.foo.com"); // default: www.webpagetest.org
const wptPublic = new WebPageTest("www.webpagetest.org", "MY_API_KEY");

2. Get available locations

wpt.getLocations((err, data) => {
  console.log(err || data);
});

3. Run test on https://docs.webpagetest.org/api/integrations/ from San Jose on IE9

wpt.runTest(
  "https://docs.webpagetest.org/api/integrations/",
  { location: "SanJose_IE9" },
  (err, data) => {
    console.log(err || data);
  }
);

4. Check current test status

wpt.getTestStatus("121025_PT_N8K", (err, data) => {
  console.log(err || data);
});

5. Get test results

wpt.getTestResults("121025_PT_N8K", (err, data) => {
  console.log(err || data);
});

6. Get test waterfall thumbnail from repeat view as data URI

wpt.getWaterfallImage(
  "121025_PT_N8K",
  {
    thumbnail: true,
    repeatView: true,
    dataURI: true,
  },
  (err, data, info) => {
    console.log(err || data, info);
  }
);

Run test on https://docs.webpagetest.org/api/integrations/ and poll results every 5 seconds timing out in 60 seconds

wpt.runTest(
  "https://docs.webpagetest.org/api/integrations/",
  { pollResults: 5, timeout: 60 },
  (err, data) => {
    console.log(err || data);
  }
);

Or run test on https://docs.webpagetest.org/api/integrations/ and wait results listening on localhost* port 8000**

wpt.runTest(
  "https://docs.webpagetest.org/api/integrations/",
  { waitResults: "localhost:8000" },
  (err, data) => {
    console.log(err || data);
  }
);

* hostname and port are optional, defaults to \<system hostname>:\<8000>

** localhost:8000 must be reacheable from WebPageTest server

Server mode

WebPageTest API Wrapper comes with a handy RESTful API proxy

Command Line

webpagetest listen 8080 --server wpt.foo.com
server listening on port 8080
http://localhost:8080
curl http://localhost:8080/help
curl http://localhost:8080/test/webpagetest.org/?location=SanJose_IE9
webpagetest listen 8443 --key key.pem --cert cert.pem --server wpt.foo.com
server listening on port 8443
https://localhost:8443

Notes

Module

const server = wpt.listen(8080, (err, data) => {
  if (err) throw err;
  console.log("listening on " + data.url);
}); // listen on port 8080 (optional), default port is 7791

setTimeout(() => {
  server.close(() => {
    console.log("server closed");
  });
}, 10000); // wait for 10s before stop listening

Batch

Batch command is available as command line only and loads a batch file containing one WebPageTest CLI command with options per line. It runs all commands in parallel, but returns an array of results in order as they appear in the batch file once all results are ready. The exit status code is the sum of all individual commands' exit status code.

By running

webpagetest batch commands.txt

where commands.txt contains:

test https://docs.webpagetest.org/api/integrations/ --first --location foo
test https://docs.webpagetest.org/api/integrations/ --first --location bar

It schedules the 2 tests above returning an array of size 2 in the same order as in commands.txt file:

[
  {
    "statusCode": 200, "statusText": "Ok",
    "data": {
      "testId": "130715_AB_C1D",
      ...
    }
  },
  {
    "statusCode": 200, "statusText": "Ok",
    "data": {
      "testId": "130715_CD_E2F",
      ...
    }
  }
]

With exit status 0 in case none of commands returns an error:

echo $?
0

By running multiple sync tests, i.e. with either --poll or --wait, all tests are scheduled and results are polled or wait in parallel; meaning, if tests are set to run in different locations or same location with multiple agents, the final result might come together, but the result array will only return once all tests are done. e.g.:

commands.txt:

test https://docs.webpagetest.org/api/integrations/ --first --location foo --poll --timeout 60
test https://docs.webpagetest.org/api/integrations/ --first --location bar --poll --timeout 60

Test Specs (Continuous Integration)

WebPageTest API Wrapper provides a simple seamless way to integrate WebPageTest with Continuous Integration tools.

See dedicated page

Tests

npm test

Issues

Have a bug/feature request? Please create an issue here on GitHub!

https://github.com/WebPageTest/webpagetest-api/issues

Author

WebPageTest

License

Copyright 2013 Twitter Inc. Copyright 2020 Google Inc. Copyright 2020 Marcel Duran and other contributors

Licensed under the MIT License

Learn about more WebPageTest API Integrations in our docs