Tools & Testing
Table of contents
Vulcanize - element build tool
Vulcanization is process that turns polymers into more durable materials.
Vulcanize is a tool to concatenate a set of web components into a single file. It’s our current recommendation for a “build step”. Read more about it in “Concatenating Web Components with Vulcanize”.
Web Component Tester - element unit-testing tool
web-component-tester makes testing your web components a breeze!
web-component-tester is a tool providing a browser-based testing environment. Out of the box it includes support for Mocha, Chai, Async and Sinon. Read more about it in “Unit Testing Elements”.
Debugging user agent Shadow DOM
In Chrome, author defined Shadow DOM is inspectable using the DevTools.
To inspect Shadow DOM defined by the user agent (e.g. the Shadow DOM of <input type="date">),
turn on “Show user agent shadow DOM” in the DevTools general settings:
After reloading the DevTools, user agent Shadow DOM should be inspectable. It will render as #shadow-root (user-agent)s in element inspector.
For more information on debugging Polymer, see Debugging Tips & Tricks.
Source maps
Polymer polyfills the HTML Imports specification. In order for code to be debuggable at run-time, scripts embedded in components are injected into <head> in the main document. Tools/browsers that support source maps will identify these scripts as belonging to their source components.
Building & testing
To run build individual polyfills or run tests, you need node and grunt-cli on your system.
- install NodeJS using the instructions on their website
-
use
npmto install the GruntJS task runner for the command-linenpm install -g grunt-cli
Building individual polyfills
If you’re interested in using an individual polyfill by itself (e.g. rather that the prebuilt webcomponents.js bundle), you need to build the minified file.
Example - building the CustomElements polyfill
$ mkdir cepolyfill; cd cepolyfill
$ git clone https://github.com/Polymer/MutationObservers
$ git clone https://github.com/Polymer/tools
$ git clone https://github.com/Polymer/CustomElements
$ cd CustomElements
$ npm install
$ grunt
Note: As seen in the example above, you may need to install other repo dependencies for the build to succeed. For example, the CustomElement polyfills requires MutationObservers and the tools repos. Sometime it is useful to look in the repo’s build.json file for requirements.
Running the tests
For any repository that contains tests, in the project’s root folder (e.g. <somepath>/platform-dev/), run:
npm install
Tasks
Once things are installed, you may run the tests or use grunt to perform tasks.
Build minified project files (default):
grunt
Run tests:
grunt test
Development workflow & tooling
We are actively investigating modern front-end tooling for projects built with Polymer.
This includes using Yeoman for scaffolding out Polymer apps and elements, Grunt for building and optimizing projects and Bower for component dependency management.
While our work in this area is still evolving, take a look at the potential workflow:
You can follow along our work on Yeoman and Polymer tooling in generator-polymer. It features app scaffolds, support for Sass and rapid deployment to GitHub pages.
Using git
Note: This section is for advanced users who want to hack on Polymer or submit a pull request. If you just want to use Polymer in a project we recommend using Bower. Please follow our guide at Getting the Code.
Clone the project
You can clone Polymer’s important repositories
by running our pull-all.sh script:
mkdir polymer_local; cd polymer_local
git clone https://github.com/Polymer/tools.git
./tools/bin/pull-all.sh
Go grab a coffee. This takes a few minutes!
pull-all.sh is great for hacking on the code or if you want the individual polyfill repositories. It creates two directories, components/ and projects/, and checks out a number of sibling repositories to each folder.
components/
- components/webcomponentsjs/webcomponents.js—The platform shims and polyfills.
- components/polymer/polymer.js—Polymer core
- components/core-elements/—A folder of the meta collection of the core elements.
- A directory for each polyfill repo (CustomElements, HTMLImports, ShadowDOM).
projects/
Full and sample applications.
Test your environment
To check that your development environment is ready, try running the designer tool:
cd projects/designer
bower install
Start a web server and navigate to the designer app.
Updating checkouts
To update your local copies, re-run pull-all.sh:
./tools/bin/pull-all.sh
About the repositories
The entirety of the Polymer is composed of a many Git repositories. All of the polyfill libraries, projects, and individual elements each have their own repository.
Specification repositories (da polyfills)
Each new web platform specification has a corresponding polyfill repository. The reasoning for this is two-fold:
- make the polyfills work across all modern browsers
- each polyfill can stand on its own and be used à la carte in projects.
For example, the following repositories may be useful if you’re interested in the individual API:
CustomElementsHTMLImportsPointerEventsPointerGesturesShadowDOMweb-animations-js
Other useful repositories
/polymer - github.com/Polymer/polymer
A meta repository used to distribute polymer.js builds.
/polymer-dev - github.com/Polymer/polymer-dev
The polymer-dev repository contains the
Polymer core and its tools and tests and is used
by the project’s developers. You should not have to touch this repository unless
you’re planning to hack on Polymer.
/platform - github.com/Polymer/platform
A meta repository used to distribute webcomponents.js builds.
/platform-dev - github.com/Polymer/platform-dev
The platform-dev contains integration tests, loader, and build tools for the amalgamated polyfills. It’s used by the project’s developers. You should not have to touch this repository unless you’re planning to hack on Polymer.
/core-elements - github.com/Polymer/core-elements
A meta repository compiling the list of utility elements.
/paper-elements - github.com/Polymer/paper-elements
A meta repository compiling the list of paper (UI) elements.