new-tool debt, part 2

In my last post I described something called new-tool debt which you incur each time you add someone else’s module to your project; you now owe a debt of research into this new tool to determine how it works.  I continue here to describe everything I’m learning about the behind-the-scenes code within Google’s Polymer Starter Kit.

The Development Cycle

A typical development cycle then looks like the following collection of commands.

$ gulp serve

This will run a gulp session using the gulpfile.js file to rebuild the code in your app folder into a temporary folder and then to serve it up via your browser using http://localhost:5000/ as the URL.

$ vi app/index.html

I don’t actually use the vi text editor but you get the gist.  With each save of the file gulp knows that it should rebuild and then refresh your browser session.  You continue with this edit + save + review behavior in this fashion.

The Production Push

I like to mark my code with git before pushing to production and it’s a good habit to follow.

$ git status
$ git add app/index.html
$ git commit -m "Edited to cleanup home page"

The first command will show you the status of what file(s) have changed.  It would have reported that I’d edited the home page.  The second command then checks the home page into source control and the third labels that collection.

Now we’re ready to rebuild, upload to production and review the results.

$ gulp

This command then rebuilds the code in your app folder to the dist folder.

$ firebase deploy

This command uploads your code from the dist folder to your Firebase website location.

$ firebase open

This command will open a browser so that you may review your production website.


You may find that you need to order your edits so that gulp serve is happy.  The gulp session can crash if you attempt to reference, say, a custom element in your home page before you’ve saved your edits in the file(s) which create and reference your new element. In this case, save all the files in question and then run gulp serve again.


Google has included a test platform within the code they’ve distributed.  They call it the Elements Tests Runner and it’s yet another thing that’s part of your new-tool debt.  So let’s try to see how you use it.

$ gulp serve

As usual, have gulp rebuild and serve up your website.  In your browser you’ll need to manually visit the http://localhost:5000/test/index.html URL by editing your browser’s location.  At the moment, my test produces the following page when it’s completed.

Output of /test/index.html

For reasons which still remain a mystery to me, Google decided to run each custom element test twice.  This will explain what appears to be a doubling of tests.

Under-the-hood when I review the app/test/index.html file it’s pulling in a bower_components/web-component-tester.js file and then calling the WCT.loadSuites() method to list which tests it wants to run.


So we can see why each test ran twice.  There appears to be some argument that’s been selected in each pair which wants a shadow DOM, whatever that is.  This page seems to know what this is about.  I guess I’ll add a bookmark for myself and research that later to find out how it impacts my testing.

Since I’ve been radically modifying my Polymer Starter Kit to suit my own needs, I quickly broke the initial sets of tests.  I immediately dropped the greeting custom element they included, so this broke the included test.  I found it was then necessary to alter the tests being run and to even create my own custom elements and write tests for them.  And yet even though there is some coverage for my new custom elements, I get the feeling that I have only scratched the surface for what my tests should include to adequately test the boundaries.  And I don’t really know this test platform yet, to be honest.  Again, I’m confronted with my own new-tool debt for this project which I owe it before I should consider it a “safe” project.

I’d say, it’s not bad for a weekend’s worth of work but you can see the production site for yourself to see what it looks like.

In my next post, I’ll review an edit I had to make in the source code for the web-component-tester bower element.  I discovered an outstanding issue that hasn’t yet been fixed on their github site.  By altering my local version I was able to get the test suite to report the correct completion percentage.