When you’re writing code that other developers have to use or maintain, you ought to provide some amount of documentation. Your code is simply not self-documenting enough.
My favorite doc tool right now is jsduck developed by Sencha Labs for their Ext JS 4 docs. It basically consumes JSDoc-style comments (with some extras for namespaces, etc.) and generates beautiful documentation. Super easy to install and use:
Use the Gradle wrapper
Using the Gradle wrapper allows users to build your project without installing Gradle, which is beautiful because it removes a very significant dependency for building and running your project.
Here’s how to use it. Add this to your
Then you just have to run in your shell:
and Gradle will add a few files to the project, most importantly
gradlew.bat (for Windows). These are binaries that your can run in lieu of
gradle, and it wraps (obviously) the execution of Gradle such that it will download the correct version of Gradle and execute it locally.
I recommend that you switch to the Gradle wrapper when you have consumers of your project that may not have Gradle. I’m going to be doing this for all of my OSS projects from now on.
Introducing the Gradle Web Suite
And now we can use the tasks provided by these plugins:
|Gradle CSS Plugin
|Gradle JS Plugin
One tool I hadn’t paid enough attention to until recently was JsTestDriver. The awesome thing about it is that it has adapters for other JS testing frameworks like Jasmine. This is great because I don’t have to convert my tests (mostly) to JsTestDriver’s test API and I get crazy speed and reporting I wouldn’t otherwise get.
In a nutshell, JSTD is a testing tool developed by Google whereby you start as server and then “capture” browsers so that JSTD uploads tests to them, the browser runs tests and then sends back test results. This is awesome because it’s super fast and you can have it run every major browser simultaneously!
Here’s how you can use it. First, we need to download JsTestDriver and the coverage plugin JARs. Then we need a configuration file for JsTestDriver:
then we need to start the JSTD server:
java -jar path/to/JsTestDriver.jar --port 4224
Now we want to capture a browser by navigating it to
http://localhost:4224/capture. Finally, run our tests with all captured browsers:
java -jar path/to/JsTestDriver.jar --tests all
and you should see something like this:
Total 17 tests (Passed: 17; Fails: 0; Errors: 0) (13.00 ms)
Chrome 17.0.942.0 Mac OS: Run 17 tests (Passed: 17; Fails: 0; Errors 0) (13.00 ms)
/Users/eric/src/eriwen.com/test/spec/PageSpec.js: 95.789474% covered
/Users/eric/src/eriwen.com/test/lib/jasmine.js: 51.640926% covered
/Users/eric/src/eriwen.com/test/lib/sinon-1.2.0.js: 22.916668% covered
/Users/eric/src/eriwen.com/test/lib/jasmine-sinon.js: 73.333336% covered
/Users/eric/src/eriwen.com/test/lib/JasmineAdapter.js: 64.83517% covered
/Users/eric/src/eriwen.com/js/main.js: 60.15037% covered
And here’s how you can run it with Gradle:
Notice the coverage numbers? JSTD has generated a report in lcov format, but this isn’t very readable to humans.
I couldn’t find any working scripts on the interwebs to convert the coverage file to Cobertura XML for reporting, so I wrote an lcov-to-cobertura-xml converter so we can report code coverage with Jenkins!
And again with Gradle:
What about PhantomJS?
PhantomJS is still very necessary because JsTestDriver does NOT allow page or DOM interaction like Phantom does. I’m really excited about CasperJS as it looks like a really nice way to do more functional testing with Phantom. I recommend you check it out.
You can see all of this in action in the build for this very site.
That’s all I have for now. Let me know your experiences with these things or if there is something I missed, comment it up! Cheers!