Test HTTPS Features and HTTP/2 Websites

Important

Native Automation mode supports HTTPS and HTTP/2 websites out of the box. Refer to this guide to set up HTTPS testing with the TestCafe proxy.

Check SSL certificate validity

The TestCafe proxy can automate websites that use invalid SSL certificates. This behavior takes place because the browser does not have direct website access. If you enable native automation, the browser inspects SSL certificates, and displays a warning screen in case of an error.

Test HTTPS Websites

The TestCafe reverse proxy serves web pages over HTTP and communicates with the original web server over HTTP or HTTPS (depending on the page URL).

Connection Protocols

If the application does not use HTTPS-specific features (like Service Workers, Geolocation API, ApplePaySession, or SubtleCrypto), TestCafe can proxy it over HTTP. Otherwise, the tests fail because the page throws JavaScript errors, does not load or loads partially.

To establish a secure HTTPS-connection, Node.js requires a valid PKCS12 certificate (.pfx). We recommend that you use a certificate signed by a trusted authority. This allows a browser to open the tested page without workarounds. You can also generate and use a self-signed certificate.

Tip

Before you use HTTPS, launch testcafe with --hostname localhost CLI parameter or hostname: localhost configuration option.

Most modern browsers treat localhost as a secure origin, and some built-in browser features that require a secure origin (Service workers, GeoAPI) should work.

Third-party JS features like ApplePaySession may not work depending on implementation.

Use a Trusted Certificate

To specify a certificate when you launch TestCafe with CLI, use -ssl option:

testcafe chrome  test.js --ssl pfx=path/to/trusted/certificate.pfx;rejectUnauthorized=true;

Use a Self-Signed Certificate

Generate a self-signed certificate with openssl if you launch tests from the command line. To generate a certificate in code, use the openssl-self-signed-certificate module.

Generate a Certificate From the Command Line

In bash, you can use OpenSSL to generate a certificate chain.

  1. Issue your own CA certificate and a CA-signed certificate for the web server:

    openssl genrsa -des3 -out myCA.key 2048
    

    You will be prompted for a non-empty passphrase. Take note of it.

  2. Generate a root certificate:

    openssl req -x509 -new -nodes -key myCA.key -sha256 -days 1825 -out myCA.pem
    

    You will be prompted for additional information, press Enter to skip the questions.

  3. Create a CA-signed domain certificate and a .csr sign request:

    openssl genrsa -out testingdomain.key 2048
    openssl req -new -key testingdomain.key -out testingdomain.csr
    

    You can press Enter to skip the questions, but set a recognizable CN (Common Name) so that you can easily find this certificate in a list of others later.

  4. Create a config file testdomain.ext with the following content:

    authorityKeyIdentifier=keyid,issuer
    basicConstraints=CA:FALSE
    keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
    subjectAltName = @alt_names
    
    [alt_names]
    DNS.1 = localhost
    
  5. Now create the certificate from the .csr request, the CA private key (myCA.key), the CA certificate (myCA.pem), and a config file(testdomain.ext):

    openssl x509 -req -in testingdomain.csr -CA myCA.pem -CAkey myCA.key -CAcreateserial -out testingdomain.crt -days 825 -sha256 -extfile testdomain.ext
    
  6. Finally, export the certificate to PKCS#12 .pfx format:

    openssl pkcs12 -export -out testingdomain.pfx -inkey testingdomain.key -in testingdomain.crt -certfile myCA.pem
    

In PowerShell, install OpenSSL and update the necessary environment variables. Afterwards, proceed with the instructions above.

Run Tests

When you run tests from the command line, use --ssl flag to enable HTTPS on a proxy server. Specify options required to initialize a Node.js HTTPS server after this flag in a semicolon-separated string. The most commonly used SSL options are described in the TLS topic in the Node.js documentation.

The examples below use a previously generated .pfx file to establish an HTTPS server.

In Chrome and Chromium-Based Browsers, use the --allow-insecure-localhost flag and --hostname CLI parameter to make Chrome trust the certificate when tests are run on localhost. If you use a different URL, use the --ignore-certificate-errors flag.

testcafe "chrome --allow-insecure-localhost" --hostname localhost test.js --ssl pfx=path/to/certificate.pfx;rejectUnauthorized=true;

In Firefox, add your self-signed root authority to the trusted list. Follow the steps:

  1. Create a new profile in Firefox settings;
  2. Run Firefox with this profile and import the CA certificate (myCA.pem) you generated previously. Ensure the This certificate can identify websites checkbox is checked;
  3. Load this new profile when TestCafe launches Firefox. To do this, add -P <profile_name> to the browser’s command line arguments.
testcafe 'firefox -P testing-profile' --hostname localhost assertTest.js --ssl pfx=certificate.pfx;rejectUnauthorized=true;

Note

The certificate created in the example is valid only for localhost domain. This is why the --hostname option is used. If you want to use another domain for testing, enter it in the [alt_names] section of testdomain.ext configuration file before creating the certificate.

Important

For security reasons, only use this profile for testing purposes.

Generate a Certificate in Your Code

When you use the programming interface, generate a certificate with the openssl-self-signed-certificate module and pass the HTTPS server options to the createTestCafe function.

const createTestCafe        = require('testcafe');
const selfSignedSertificate = require('openssl-self-signed-certificate');

const sslOptions = {
    key:  selfSignedSertificate.key,
    cert: selfSignedSertificate.cert
};

const testcafe = await createTestCafe('localhost', 1337, 1338, sslOptions);
const runner   = testcafe.createRunner();

await runner
    .src('test.js')

    // Browsers restrict self-signed certificate usage unless you
    // explicitly set a flag specific to each browser.
    // For Chrome, this is '--allow-insecure-localhost'.
    .browsers('chrome --allow-insecure-localhost')
    .run();

await testcafe.close();

Test HTTP/2 Websites

TestCafe can test an HTTP/2 website only if the server can downgrade the connection to HTTPS or HTTP/1. See ALPN negotiation for details.