How to Translate from Gobbledygook to English

For this month’s Off Beat piece, I thought it might be fun to expand on the online research article in this magazine. That article talks about how developers do online research differently from non-coders. For example, developers usually type error messages into search engines then carefully review and test code from any page results. Other times, they go to a specific website for a programming language and search there for functions and other details about the language.

With that as a start point, and understanding these Off Beat articles are about turning my online research skills on a topic and bringing you along for the ride, with detours likely, I want to start with this excerpt from an email I received:

Recently WordPress added QUnit as a JavaScript unit testing framework and added its first JavaScript unit tests. I thought I would walk through how to run the tests and how to write tests so that we can increase our JavaScript test coverage. All of these are based upon using the develop.svn.wordpress.org checkout which is where the JS unit tests live.

Has your head exploded? Mine did. But that’s normal for developers when you don’t entirely know a topic. The email is classic gobbledygook, language made unintelligible by excessive use of technical terms. In this case, the email is intelligible only to people who know the terms.

This email is a great way to show you the process people use to learn what they don’t know. I have in mind someone maybe 10-15 years old, interested in WordPress and/or JavaScript, who wants to play around and see how the two work together.

Here’s how I break down this email, with bold for the key words, phrases, and actions we’ll explore in this article:

Recently WordPress added QUnit as a JavaScript unit testing framework and added its first JavaScript unit tests. I thought I would walk through how to run the tests and how to write tests so that we can increase our JavaScript test coverage. All of these are based upon using the develop.svn.wordpress.org checkout which is where the JS unit tests live.

In this marked up email, we can immediately tell a few things:

The software program we’re talking about is WordPress, an online publishing tool. You may or may not know it is written in the PHP programming language. As we’ll see, the PHP language is not important.
Apparently there is a JavaScript test framework called QUnit. Probably it’s software.
This email is about a walk through, a tutorial, of how to write unit tests and run unit tests with QUnit.
The WordPress JavaScript unit tests are part of the code you can checkout at developer.svn.wordpress.org. However, to get this bit you have to translate “using the develop.svn.wordpress.org checkout” into its parts. I see, for example, the “svn” bit and know it refers to Subversion, software used to store and manage code. The word checkout, as we’ll see, also is a cue we’re talking about code management. I also see JS unit tests live and guess correctly JS means JavaScript.

This is a little more clear. Here’s what we apparently need to learn more about:

What’s a unit test? (some might not know this)
What is QUnit?
How do you write a test in QUnit?
How do you checkout WordPress files?

Let’s tackle each of these questions in order. Remember, this is an adventure. There may or may not be detours. Heads will be scratched. You might have to do more research. My goal is to show you how to demystify technology in general and software programming in particular. With patience, you can learn almost anything if it interests you.

What’s a Unit Test?

Here’s the problem: someone (maybe you) writes a lot of code. How do you know if it works? You could play with the application and hope you touch every part of the software, as well as create all possible interactions, to find any bugs to fix. But that’s foolhardy at best.

An obvious way to test your code is to identify who will use your software, what tasks they’ll complete with your software, and in what order. Then test all the tasks in the order required. But what if you miss a task? Or you get the order of tasks wrong?

A better solution is to test at the lowest possible level in your code, make sure everything works, then work your way up to combinations of code. The lowest level could be a function, or a block of code within a class file if your code is object oriented.

Tests at the lowest level in your code are called unit tests.

For example, if you have a function that adds two numbers, the unit test would call your function and add two different numbers. If the function adds the number and returns the correct value, the unit test is passed. Every unit test has at least two parts, an assertion to describe the expected test outcome and a result the unit test uses to compare the result with the assertion. If there is a match, the test passes. If the assertion and result differ, the test fails.

Perhaps the best use of unit tests is to control software development. If you create your unit tests before you code, then code to the tests, you can design and test your code before it is written and have tests to use to confirm the code works as designed.

What is QUnit?

The email we started with above included a link to the QUnit website (link below) at QUnitJS.com. Exploring that site reveals QUnit is a set of files that provide a framework of code used to test JavaScript code. You add links in your web page to one or more QUnit test files, as well as a few special DIVs and your code to test. Tests can be run with a command line software tool or by calling up a web page.

Here’s some sample code from the QUnit cookbook to give an idea how the framework operates:

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>QUnit basic example</title>
<link rel="stylesheet" href="/resources/qunit.css">
</head>
<body>
    <div id="qunit"></div>
    <div id="qunit-fixture"></div>
    <script src="/resources/qunit.js"></script>
    <script>
        test( "a basic test example", function() {
            var value = "hello";
            equal( value, "hello", "We expect value to be hello" );
        });
    </script>
</body>
</html>

Notice these parts of this example code:

The <link> code (line 6) calls the qunit.css file to display the web page correctly.
The div with id=”qunit” and the div with id=”qunit-fixture” both are required (lines 9 and 10). They display the results of your JavaScript unit tests.
The <script> code calls the qunit.js file (line 11) with all the QUnit test code.
The second <script> code includes a sample JavaScript test (lines 12 to 17). You call the test(name, function) function, in the qunit.js file, where name is the name of the test and function is the function code to test.
The CSS file and <script> qunit.js file are both in the /resources folder (line 6 and line 11). You create a folder to hold your QUnit web page and in that folder create a folder called resources with the QUnit files.

These bullet items are the required bits you need to test JavaScript with QUnit.

None of this is terribly complex. And if it is new to you, as it is to me, it still makes basic sense. There’s a lot I would be curious to know. For example, I’d love to see what is in the qunit.js file to see exactly how the code tests any JavaScript code.

One other detail to note: QUnit is simply one of several JavaScript test frameworks available. The jQuery project uses QUnit, as well as WordPress (obviously). It’s highly likely other JavaScript frameworks work in the same way or similar way as QUnit. So what we’ve learned here probably applies to other frameworks.

How do you write a test in QUnit?

Well we mostly answered this question, didn’t we, in the prior answer. You’ll need a web page that includes a bunch of bits as described in the last question. Then you’ll need to add your JavaScript code to the web page, as part of the test(name, function) code, as described above, and call up the test page.

How do you checkout WordPress files?

For most people new to programming, the word checkout is mysterious. There are checkout lines at stores, for example, or you might check out a Grumpy Cat video. However, it might be less obvious how the word checkout works in software development.

Imagine this problem. You code today, tomorrow, and every day for the next month. At the end of the month, you realize somehow a bit of code disappeared from your code maybe a week ago. How do you retrieve that bit of code?

The easiest way is to store your code somewhere and pull out the code each day you do programming with the code. Pulling out your code from storage is called a checkout. When you pull or checkout code with a special type of storage software, the process of doing so captures your identity and datestamp information, at the least. The storage software also might block others from editing the code. Or your storage software might require you to create a copy (or branch) of your code and, when you’re done, merge your work back into the code (or trunk).

This is all common sense and fairly easy to explain. The nuances happen when people check code in and out.

There are several software tools used to store code and manage the maintenance of software code. Subversion and Github are two common code repository tools also called version control software. I love WordPress because the team coding the software takes time to document their process. There are at least two articles that describe in detail how to use WordPress with Subversion, the software used by the walk through mentioned in the email that got us started on this journey. But there is documentation to use WordPress with Github, as well.

Why would WordPress use a version control system like Subversion? Well, it’s an open source project. Developers all over the world contribute code, in some cases, adding code and functionality. In the case of the email that started this article, the email is for developers who want to test the JavaScript code used in WordPress and, if bugs are found, to fix the code. For people interested in software programming, subscribing to emails from an open source project is a great way to gain insight into the software development process, as well as become comfortable enough to dive in and help.

What Have We Learned?

Here again is the email I received:

Recently WordPress added QUnit as a JavaScript unit testing framework and added its first JavaScript unit tests. I thought I would walk through how to run the tests and how to write tests so that we can increase our JavaScript test coverage. All of these are based upon using the develop.svn.wordpress.org checkout which is where the JS unit tests live.

Does it make more sense after reading this article? It should. Here’s what I hope you’ve learned:

Technical instructions with difficult to understand or unknown words can be broken down into pieces and each piece researched and understood. Focus on nouns and verbs, as well as the relationships between each piece.
QUnit is a set of JavaScript files and code in an HTML web page used to test JavaScript. It’s also called a framework.
You can test JavaScript code using QUnit by calling a JavaScript function called test(name, function) where name is the name of your test and function is the function you want to test.
The email offers a walk through, or tutorial, on how to write and use QUnit tests.
WordPress, as open source software, has a way for developers to download and update their software.

Perhaps the most fun I’ve had with software programming, and computer science, is learning what I don’t know. This email, and many other bits of technical information, are doorways you can use to learn and have fun. Even if, at first, the text makes zero sense.

If you’re interested in online research skills, also read the article in this issue, How to Do Online Research.

Learn More

The Latest
View All

Update: Your beanz Magazine Subscription

Can AI Find Clues to Aliens?

Code a Choose Your Adventure Game

World Gen Mods Ramp Up Minecraft Play

How to Translate from Gobbledygook to English

What’s a Unit Test?

What is QUnit?

How do you write a test in QUnit?

How do you checkout WordPress files?

What Have We Learned?

Learn More

The WordPress Email/Post

QUnit

Unit Tests

WordPress and Subversion

WordPress and Github

The LatestView All

How to Translate from Gobbledygook to English

What’s a Unit Test?

What is QUnit?

How do you write a test in QUnit?

How do you checkout WordPress files?

What Have We Learned?

Learn More

The WordPress Email/Post

QUnit

Unit Tests

WordPress and Subversion

WordPress and Github

Related Posts

The Latest
View All