Native Client

How to Test-Run Web Applications

This document describes how to test-run a Native Client application during development. The document assumes you are familiar with the material presented in the Technical Overview.

Browser and Pepper versions

Native Client first debuted as a default feature in Chrome 14. Each version of Chrome supports a corresponding version of the Pepper API. The following table shows Chrome versions and a sampling of the Pepper API features they support:

Browser Version Pepper Version Pepper Features
Chrome 14 Pepper 14 Messaging, file I/O, 2D graphics, keyboard and mouse input events, URL loading, audio
Chrome 15 Pepper 15 Added: 3D
Chrome 16 Pepper 16 Added: Fullscreen and mouse lock

You (and your users) must use the Chrome version equal to or higher than the Pepper API version used in your application. For example, if you compiled your application using the Pepper 15 API, you must run the application in Chrome 15 or higher. To check which version of Chrome you're using, type about:version in the Chrome address bar.

If your application requires a minimum version of Chrome, you are encouraged to include code in the application to check that the user's browser is compatible with the application. For sample code that checks the user's browser version, refer to the load_progress example in the Native Client SDK.

Test-running a NaCl application

There are three ways to test-run (run the application before release to customers) a Native Client application:

  1. Test-run the application as an unpacked hosted application. This is the recommended way to test-run an application as you are developing it.
  2. Test-run the application from the Chrome Web Store. Use this option if you want a select set of test users to use your application.
  3. Test-run the application as a locally-served application. Use this advanced mechanism for testing that your Native Client application's code works.

Note: You must deploy your application to the Chrome Web Store for general release. This requirement will help ease the process of migrating applications to the PNaCl architecture (Portable Native Client) when it becomes available. Refer to the PNaCl: Portable Native Client Executables on the Research Papers page for further information on PNaCl.

Test-running an unpacked hosted application

A hosted application is an application you host on your own Web server and access through a Chrome Web Store manifest file on the Chrome Web Store.

An unpacked hosted application is the same as a hosted application, except that the Chrome Web Store manifest (and supporting files) are located on a local machine. To test-run an unpacked hosted application:

  1. Place your NaCl application on your web server (.html, .css, .nexe, images, javascript, Native Client manifest file, and so on).
  2. Create a Chrome Web Store manifest file (manifest.json) and icons. Refer to Steps 1-3 in the Tutorial: Getting Started to learn how to create these assets. As an example, here is the Chrome Web Store manifest file for the Flocking Geese application written by the SDK team:
    {
      "name": "Flocking Geese",
      "description": "Simple flocking algorithm implemented in both JavaScript and in C++ (using Native Client)",
      "version": "1.0.1",
      "icons": {
        "128": "flocking_geese_icon.png",
        "16": "flocking_geese_icon16.png"
      },
      "app": {
        "urls": [
          "http://gonativeclient.appspot.com/dev/demos/flocking_geese/"
        ],
        "launch": {
          "web_url": "http://gonativeclient.appspot.com/dev/demos/flocking_geese/"
        }
      }
    }

    Note that the URLs in this file have specific syntax for an App Engine application, such as a trailing forward slash (/).

  3. Follow steps 1-7 in the Loading Hosted Apps section of the Hosted Apps document to load and run your application as an unpacked hosted application.

Test-running from the Chrome Web Store

Move your Chrome Web Store manifest file and icons to the the Chrome Web Store when you are ready to let some test users try your application. To test-run your application from the Chrome Web Store:

  1. Place your NaCl application on your web server (.html, .css, .nexe, images, javascript, Native Client manifest file, and so on). Note: Skip this step if you already created these assets while test-running your application as a unpacked hosted application.
  2. Create a Chrome Web Store manifest file (manifest.json) and icons. Refer to Steps 1-3 in the Tutorial: Getting Started to learn how to create these assets.
    Note: Skip this step if you already created these assets while test-running your application as a unpacked hosted application.
  3. Zip up your Chrome Web Store manifest and icons.
  4. Go to the Chrome Web Store Developer Dashboard.
  5. Log in.
  6. Click the "Edit your tester accounts" link at the bottom of the Developer Dashboard.
  7. Enter a series of email address for your testers in the "Your trusted tester accounts" field.
  8. Click the "Save Changes" button. Your Developer Dashboard settings are saved.
  9. Click "Add new item."
  10. Locate the zip file containing the manifest and icons.
  11. Click the "Upload" button. The Edit item screen appears.
  12. Click the "Publish to test accounts" button at the bottom of the screen. Refer to Publishing to test accounts for further information.
  13. Instruct your testers how to log in and download the application from the Chrome Web Store.

Test-running a locally served application

Test-running a locally served Native Client application is an advanced method for testing your Native Client code. This method is a three step process:

  1. Enable the Native Client flag in Chrome.
  2. Start a local Web server.
  3. Navigate to your application on the local server in Chrome.

Enable the Native Client flag in Chrome

Ensure you have a correct version of Chrome to support your applications features (refer to Pepper and Chrome versions). If your Chrome version is correct, enable the Native Client flag in Chrome:

  1. Type about:flags in the Chrome address bar.
  2. Scroll down to "Native Client" and click the "Enable" link.
  3. Scroll down to the bottom of the page and click the "Relaunch Now" button. Native Client will not be enabled until you relaunch your browser. All browser windows will restart when you relaunch Chrome.

If you complete these steps and Native Client still does not appear to be enabled, type about:plugins in the address bar. Scroll down to "Native Client," and verify that Native Client is enabled. If Native Client is not enabled, click the "Enable" link. You do not need to relaunch your browser after enabling Native Client.

Start a local web server

If you want to run your applications locally, you must start a web server to serve them. Dragging HTML files into your browser won't work; for security reasons, the applications must come from a server.

The Native Client SDK includes a simple Python-based HTTP server in the examples directory. Ensure you have Python installed and then run the commands below to start a local server on port 5103:

  • Windows:
    cd examples
    httpd.cmd 5103
  • Mac, Linux:
    cd examples
    python httpd.py 5103

Navigate to your application on the local server

You can run your application by typing the local URL into the browser:

  1. Move your application into the examples directory in the SDK, within a sub-directory of your choice, such as "pong."
  2. Access your application by typing the location of its HTML file in Chrome, e.g.:

    http://localhost:5103/pong/pong.html

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.