Skip to content

Latest commit

 

History

History
208 lines (147 loc) · 13.8 KB

DEVELOPING.md

File metadata and controls

208 lines (147 loc) · 13.8 KB
Raw

Development on AMP HTML

How to get started

Before you start developing in AMP, check out these resources:

Build & Test

For most developers the instructions in the Getting Started Quick Start Guide will be sufficient for building/running/testing during development. This section provides a more detailed reference.

The Quick Start Guide's One-time setup has instructions for installing Node.js, Yarn, and Gulp which you'll need before running these commands.

Command Description
gulp[1] Runs "watch" and "serve". Use this for standard local dev.
gulp dist[1] Builds production binaries.
gulp dist --fortesting[1] Indicates the production binaries are used for local testing. Without this ads, tweets and similar use cases are expected to break locally when using minified sources.
gulp lint Validates against Google Closure Linter.
gulp lint --watch Watches for changes in files, Validates against Google Closure Linter.
gulp lint --fix Fixes simple lint warnings/errors automatically.
gulp build[1] Builds the AMP library.
gulp build --fortesting[1] Builds the AMP library and will read the AMP_TESTING_HOST environment variable to write out an override AMP_CONFIG.
gulp build --css-only[1] Builds only the embedded css into js files for the AMP library.
gulp clean Removes build output.
gulp css Recompile css to build directory.
gulp extensions Build AMP Extensions.
gulp watch[1] Watches for changes in files, re-build.
gulp test[1] Runs tests in Chrome.
gulp test --verbose[1] Runs tests in Chrome with logging enabled.
gulp test --nobuild Runs tests without re-build.
gulp test --watch[1] Watches for changes in files, runs corresponding test(s) in Chrome.
gulp test --watch --verbose[1] Same as "watch" with logging enabled.
gulp test --saucelabs[1] Runs test on saucelabs (requires setup).
gulp test --safari[1] Runs tests in Safari.
gulp test --firefox[1] Runs tests in Firefox.
gulp test --files=<test-files-path-glob>[1] Runs specific test files.
gulp serve Serves content in repo root dir over http://localhost:8000/. Examples live in http://localhost:8000/examples/
npm run ava[1] Run node tests for tasks and offline/node code using ava.

[1] On Windows, this command must be run as administrator.

Manual testing

For manual testing build AMP and start the Node.js server by running gulp.

Examples

The content in the examples directory can be reached at: http://localhost:8000/examples/

For each example there are 3 modes:

  • /examples/abc.html points to prod. This file would not reflect your local changes.
  • /examples/abc.max.html points to your local unminified AMP. You want to use this during normal dev.
  • /examples/abc.min.html points to a local minified AMP. This is closer to the prod setup. Only available after running gulp dist --fortesting.

Document proxy

AMP ships with a local proxy for testing production AMP documents with the local JS version.

For any public AMP document like: http://output.jsbin.com/pegizoq/quiet

You can access is with the local JS at

When accessing min urls make sure you run gulp dist with the --fortesting flag so that we do not strip out the localhost code paths. (We do some code elimination to trim down the file size for the file we deploy to production)

If the origin resource is on HTTPS, the URLs are http://localhost:8000/max/s/output.jsbin.com/pegizoq/quiet and http://localhost:8000/min/s/output.jsbin.com/pegizoq/quiet

A4A envelope

If you are working on AMP 4 Ads (A4A), you can use the local A4A envelope for testing local and production AMP documents with the local JS version.

A4A can be run either of these two modes:

  1. Friendly iframe mode: http://localhost:8000/a4a/...
  2. 3p iframe mode: http://localhost:8000/a4a-3p/...

The following forms are supported:

When accessing min urls make sure you run gulp dist with the --fortesting flag so that we do not strip out the localhost code paths. (We do some code elimination to trim down the file size for the file we deploy to production)

If the origin resource is on HTTPS, the URLs are http://localhost:8000/a4a[-3p]/max/s/output.jsbin.com/pegizoq/quiet and http://localhost:8000/a4a[-3p]/min/s/output.jsbin.com/pegizoq/quiet

Notice that all documents are assumed to have a "fake" signature. Thus, this functionality is only available in the localDev mode.

Additionally, the following query parameters can be provided:

  • width - the width of the amp-ad (default "300")
  • height - the height of the amp-ad (default "250")

Chrome extension

For testing documents on arbitrary URLs with your current local version of the AMP runtime we created a Chrome extension.

Testing on Sauce Labs

In general local testing (i.e. gulp test) and the automatic test run on Travis that happens when you send a pull request are sufficient. If you want to run your tests across multiple environments/browsers before sending your PR you can use Sauce Labs.

To run the tests on Sauce Labs:

  • Create a Sauce Labs account. If you are only going to use your account for open source projects like this one you can sign up for a free Open Sauce account. (If you create an account through the normal account creation mechanism you'll be signing up for a free trial that expires; you can contact Sauce Labs customer service to switch your account to Open Sauce if you did this accidentally.)

  • Set the SAUCE_USERNAME and SAUCE_ACCESS_KEY environment variables. On Linux add this to your .bashrc:

    export SAUCE_USERNAME=<Sauce Labs username>
export SAUCE_ACCESS_KEY=<Sauce Labs access key>

    You can find your Sauce Labs access key on the User Settings page.

  • Install the Sauce Connect Proxy.

  • Run the proxy and then run the tests:

    # start the proxy
sc

# after seeing the "Sauce Connect is up" msg, run the tests
gulp test --saucelabs

  • It may take a few minutes for the tests to start. You can see the status of your tests on the Sauce Labs Automated Tests dashboard. (You can also see the status of your proxy on the Tunnels dashboard.

Deploying AMP on Cloud for testing on devices

For deploying and testing local AMP builds on HEROKU , please follow the steps outlined in this document.

In the meantime you can also use our automatic build on Heroku link, which is normally built with latest head on master branch (please allow delay). The first time load is normally slow due to Heroku's free account throttling policy.

To correctly get ads and third party working when testing on hosted services you will need set the AMP_TESTING_HOST environment variable. (On heroku this is done through heroku config:set AMP_TESTING_HOST=my-heroku-subdomain.herokuapp.com)

Repository Layout

  3p/             - Implementation of third party sandbox iframes.
  ads/            - Modules implementing specific ad networks used in 
  build/          - (generated) intermediate generated files
  build-system/   - build infrastructure
  builtins/       - tags built into the core AMP runtime
      *.md        - documentation for use of the builtin
      *.js        - source code for builtin tag
  contributing/   - docs for people contributing to the AMP Project
  css/            - default css
  dist/           - (generated) main JS binaries are created here. This is what
                    gets deployed to cdn.ampproject.org.
  dist.3p/        - (generated) JS binaries and HTML files for 3p embeds and ads.
                    This is what gets deployed to 3p.ampproject.net.
  docs/           - documentation about AMP
  examples/       - example AMP HTML files and corresponding assets
  extensions/     - plugins which extend the AMP HTML runtime's core set of tags
  spec/           - The AMP HTML Specification files
  src/            - source code for the AMP runtime
  test/           - tests for the AMP runtime and builtins
  testing/        - testing infrastructure

Supported browsers

In general we support the 2 latest versions of major browsers like Chrome, Firefox, Edge, Safari and Opera. We support desktop, phone, tablet and the web view version of these respective browsers.

Beyond that the core AMP library and builtin elements should aim for very wide browser support and we accept fixes for all browsers with market share greater than 1 percent.

In particular, we try to maintain "it might not be perfect but isn't broken"-support for the Android 4.0 system browser and Chrome 28+ on phones.

Eng docs

We also recommend scanning the spec. The non-element part should help understand some of the design aspects.

Code of conduct