“What do you mean by “software engineering practices?” — was the developer’s response.

When I explain what I mean by these three words (apparently, I took for granted), the person starts listing technologies. This conversation has been repeating a bit too frequently for my liking recently.

Look, I get it. Technologies knowledge and experience are vital for a software engineer. However, the fundamental practices of software engineering are insanely important nevertheless.

Let’s discover why.

Holy Grail of Software Development

Why do these practices exist in the first place, and why are countless books written on them? And why is the industry trying to improve on the existing ones and invent new ones?

Why just a bunch of technology skills is not enough?

That’s because we all want to get stuff done fast. And we want it done with a high level of quality. And we want it to be valuable.

The “Holy Grail of Software Development” is the ability to deliver fast and with high quality.

While innovative programming language or framework can improve speed and reduce the chance of making mistakes, the improvement effect is negligible in “speed x quality x value.”

What matters then?

How the software is developed creates a tremendous effect on speed and quality.

It’s the processes applied, techniques used, disciplines practiced.

Whether You Know it or Not, You’re Still Using Practices.

Just not necessarily the good ones.

Slap some code together, use a lot of copy-paste from StackOverflow and your previous project, and get it to production as quickly as possible? — That’s a software engineering practice.

It gives you great speed (at first) and, of course, reduces quality substantially. Do that for a few weeks, and you’ll inevitably slow down because you’ll constantly be debugging all the bugs produced.

Then, on the other hand, there is another practice of unit-testing and integration-testing the code and refactoring it until it becomes “Clean Code.” — This is a simple example of a few good practices applied:

• Automated testing.
• Refactoring.
• Clean Code.

Not Every “Best” Practice is Always Good — Context is King

Let’s say that you’ve committed to using a whole bunch of best practices, such as keeping your code decoupled and flexible using design patterns. Moreover, you’ve decided to exhaustively implement and test all the different scenarios that you think could happen in the future.

These are all that many would consider best practices.

That sounds quite reasonable, however, applied in the wrong context, that could lead to the following:

• The business never leveraged that extra flexibility because no need in the future came to pass.
• You still had to maintain more code that was more complex to support these flexibilities for many years. That’s an extra cost — WASTE.
• It took you originally longer to implement the functionality — WASTE.
• Oh, and half of the scenarios you came up with also never happened. The feature changed significantly after customer feedback, so most cases became impossible later on. — WASTE.
• Additionally, one of the flexibilities constrained the implementation of another flexibility that became required later on. So the business had to go for a trade-off and deliver less value to the customer. — ACTUAL BUSINESS VALUE DAMAGE.

As you can see, the idea was to increase quality, increase speed in the future, and deliver as much customer and business value as possible.

What happened instead?

The quality was excellent — that’s all good!

Now, the speed was initially slower, and it kept being slower in the future because none of the expected came to pass.

The best thing you can expect in software development is change (not the one you expected). Also, prepare to have your expectations and assumptions hammered all the time.

Finally, too much flexibility harmed the business value.

The same set of practices could’ve been fantastic in another context, where you, for example, precisely know what will happen in the future. An example scenario is when you’re rebuilding an existing successful system.

In that case, you would have gotten lots of speed, quality, and business value throughout the endeavor.

Software Engineering Practices Are Based on Principles

What are these practices based on? How to detect whether the context is proper or not? When to apply and when not? How to apply?

You guide the choice of practices and patterns by the software engineering principles!

When you adopt multiple principles (such as YAGNI, DRY, SOLID, etc.), they will guide you when you need to act in specific ways (e.g., apply one practice or another, or make this or that choice).

The challenge would be when multiple principles you’ve adopted conflict with each other.

That’s when you’ll have to make trade-offs.

Where do Principles Come From? How to choose?

Principles should be based on values. The values that you, your team, and your organization adopts.

For example, when I was talking about the “Holy Grail of SWE,” I’ve mentioned the “speed x quality x value” as the three most important ones. That’s a value statement.

Also, who said that these three values are the silver bullet to success? Nobody knows. Every person and organization can have its own set of values.

However, for any organization or group to achieve a big goal and execute a complex strategy, it would need to align everybody involved on the same set of values.

Once you and your group have agreed on what values you should adopt to achieve the challenging long-term goals, you must pick or create the principles that will get you there.

Picking existing principles that are tried and tested to improve software engineering in terms of the values you’ve chosen is the most straightforward approach. However, that shouldn’t deter you from thinking about a custom set of principles that would work for your group’s values in particular.

Example Values That I Like to Optimize For

I’ll give you a few values that I usually go for in most software products where the only constant is the change itself:

• Shortest lead time — how long does it take from idea inception to value delivery to the hands of the user.
• Lowest inventory — how much work is “done” but isn’t being used by anybody (by users, other developers, or other team members).
• Highest quality — how many bugs or failures the software has. It should behave precisely as the development team expects it to.
• Largest valuable impact — how valuable is the software to the user, customer, and the business.

Once these values are defined, it’s pretty simple to pick the principles to guide the decisions.

Example Software Engineering Principles

• LEAN product and development
• YAGNI/KISS
• Evolutionary Design
• Simple Design
• SOLID
• High-coverage automated testing (no manual QA)
• No throwing responsibilities over to another department — Extreme ownership
• Code stewardship (next level after ownership)

And given the principles, you can pick or design your software engineering practices.

Example Software Engineering Practices

• TDD & BDD & ATDD
• Continuous Refactoring
• CI/CD
• Trunk-Based Development (TBD) & “Live on Main”
• Clean Code
• Slicing work items as small as possible
• Instant Code Review (aka Pair-programming)
• Ensemble programming
• Rolling pair rotation
• Spike & PoC (for experimentation)
• Design Patterns

Most of these are parts of original Extreme Programming, and this is no surprise because the values I have listed above are almost the same as values of XP.

Moreover, there are a few more principles and practices that are modern, and they could be considered as the evolution of XP.

Values, Principles & Practices Are Technology-Agnostic

Now I want to return to that situation where the developer responded with a list of technologies when asked about practices.

Here’s the thing: the practices, principles, and values are universal. No matter which technology you use, you can rely on your practices, given that your principles and values haven’t changed.

Moreover, when you master the practices and principles, you’ll be able to change technologies and tools like gloves while maintaining high parameters on all your values and delivering excellent results!

Conclusion

Of course, if you are starting in software engineering, knowing specific technologies is most essential for you.

That’s because your effectiveness is a product of your tools experience and the practices you apply. And to use and understand the practices, you need to have at least a bit of skill with the programming language and basic problem-solving.

However, beyond that, the equation:

TOOLS SKILL x PRACTICES SKILL x SOFT SKILLS

kicks in!

So the most effective way to develop as a software engineer is to have both a robust set of hard and soft skills and learn and apply the best software engineering practices (that are applicable in your context).

Thank you for reading!

If you have other ideas on the topic, feel free to send me a Tweet!

• Find a more exciting team or company.
• Start something on the side in our free time.
• Bring more advanced concepts to the current team and codebase.

It’s the third one that is the most worrying because it happens way too often, and it’s probably more harmful than you think.

This article isn’t preaching against new technologies, architectures, etc.

Instead, I’d like to point out that in about 95% of the cases, they are introduced years before they are actually necessary. Instead of making the software more straightforward, this makes the software more complex.

What should we do instead if we want to learn more new stuff then?

Well, one thing is to invert your focus. Instead of chasing something more complex, take on the challenge of making what you have much simpler.

In fact, making the existing codebase and architecture more straightforward than it already is — is a considerable challenge, in the process of which you are guaranteed to learn new things!

Suppose you feel the urge to learn something new and deal with a more complex task. Perhaps, you should talk to your business stakeholders to see if they have an idea that they don’t even want to mention to product & engineering. (Because they think it’s too challenging or impossible)

These types of ideas are where there is real gold for learning, innovation, and valuable complexity!

If you have other ideas on the topic, feel free to send me a Tweet!

First, let me give you some context.

Pairing ~100% of the Time

At Pivotal we pair all the time. It is very rare to see anyone solo. Pairing does not end with pair-programming, it also includes other roles such as design and product. Also, pairing is, at times, cross-functional, e.g.: product designer pairs with a software engineer, or product designer pairs with a product manager, etc. I love that.

With pairing, not everything is so shiny.

Chemistry

Now and then, you need to pair with someone, you have never paired with before. That happens in the event of new hires, team member rotations between teams, and cross-team pairing sessions.

We are all humans, so, from time to time, it feels like you are not getting along very well with your pair. There is a certain amount of tension. Of course, that harms your productivity, and, also, drains your energy.

On the contrary side, the chemistry between pairs might be so good, that you are just having fun the whole day and enjoy the pairing session, and the amount of work being done is suboptimal.

The pairing session might go not so well not only because of chemistry. Pairs could have chosen a non-suitable style of pairing (one of: ping-pong, switch on red, driver-navigator, etc.). From time to time, how pairs solve the problem, can also be improved.

Five Minutes Feedback Time

That is a technique that we are utilizing all the time when we have such problems. First, ask your pair if they want to apply this technique and reserve 5 minutes at the end of the pairing session (end of the work day is the most suitable). Then, when the time comes, give each other the feedback in the format of “Pluses and Deltas”:

• First, tell what went well.
• Second, describe what could be improved.

When both pairs are proficient with this technique, then most of the problems can be resolved in 2-4 pairing sessions. By “proficient” we mean here: both are open to receiving the feedback, and are capable of calling out complicated things without triggering defensiveness on the receiving side.

If the whole team applies this technique daily for two or three weeks, they will have to stop using it because there will be nothing to talk about anymore. That means that the team has solved most of the problems, and there is no longer need in a daily application of such technique.

Conclusion

All these problems are not unique to pairing. They are inherent to the collaboration. Essentially, any team will have these problems. It is just that, in non-pairing environments, these problems will become apparent only after months of work. That is all while they continue harming productivity and people’s happiness for these long months.

With pairing these problems become apparent immediately. So you can start fixing them on the day one, and not after the half a year of the broken collaboration.

If you pair often, or if you have any other sort of collaboration within the team, I recommend trying out this technique. It will take some time to get proficient at giving feedback.

There is a marvelous talk from Dan North on how to provide an effective feedback in different contexts.

Thanks

Thank you for reading, my dear reader. If you liked it, please share this article on social networks, Reddit, and Hacker News, and follow me on Twitter: @tdd_fellow.

If you have any questions or feedback for me, don’t hesitate to reach me out on Twitter: @tdd_fellow.

Mornings That Start with a Lunch

A year ago and before I was pulling out late nights almost every single day. Making an open-source contribution, working on the astounding side project idea, writing a blog post, watching a conference talk or a fun video. As an owl type, I have a lot of bright ideas at that time of day. Also, my productivity is at its top. Or at least it feels that way.

That usually meant, that I would go to work next day somewhere between 10 AM and 12 PM. Mostly, that was okay because a lot of other developers around me did the same thing.

So, imagine having your work day (for your employer, client or yourself) start this way:

1. Come to the work
2. Drink coffee and eat breakfast, because, obviously you didn’t have time to do that at home
3. Chit chat with your colleagues (offline or online), go through the email inbox
4. Do some work for half an hour
5. It is a lunch time
6. Food coma for 1 hour
7. Be not-so-productive (because you’re tired and an owl type) for what you have left in a day (2-4 hours)
8. Maybe pull out overtime because there are things to deliver and you are the most productive in the evening/night

You can see, that my work day wasn’t as productive as it should. One may say that I’m just shifting focus to my activities and invest less productivity into the work for my employer/client/etc. And I have another story to tell here.

A Lot of Rework

I have been noticing for some time that all the work that I do in the late evenings and the night for myself needs to be re-worked all the time. To put it simply, quality of my most “productive” work was not as good as I would expect it to be.

Additionally, since I was working in a pair-programming environment and everybody started their work day at a different time, it was hard to pair-program all the time - there was a lot of time I had to solo. When I have joined Pivotal I was amazed by the fact that they pair-program nearly 100% of the time. I was enjoying that right from the first day. Pairing 100% of the time also means that the whole team has to start the work day and end it at the same time. We are starting early in the morning, and ending our work day at 5 PM every day.

Also, at Pivotal we finish all of our daily meetings in 10 minutes right at the beginning of the day. We’re off to work right after. That builds a crazy momentum of making things done and makes us productive.

Productive Mornings with Momentum

That kind of momentum results in a lot of done work. The amount of work being done before lunch ultimately exceeds the amount of work I remember doing after lunch and, especially, in the evening.

Even though I feel more productive in the late evening, and in the night, practical results show that most productive work is done in the morning if I maintain that kind of momentum.

Maybe it is only about work, what about personal things that I need to do? - One might ask. I have another story for you. A couple of months ago I started developing a “mini habit”: wake up every day at 6 AM. That gives me about 50 minutes of free time before I need to go to the office. Add to that 35-45 minutes commute on the subway. Now and then, when I am talking to my pair during our break (we are using the pomodoro productivity technique), I realize that at 9:05 AM I have done all the personal things that I have to do today. These things include morning exercise, household chores, contributing to open-source, writing a blog post, reading a book, sending a letter, etc. By the way, most of these things are also mini habits.

Another thing that I am experiencing right now is that the quality of the work is much higher than before - I have to do much less reworking. I still get the most remarkable ideas in the evening and before going to sleep, so what do I do about them? Note them down, and go through them next morning or later.

Thanks

I am amazed so far, how waking up in the morning every day, earlier than you normally have to, allows to build up a significant momentum, complete all the personal tasks that need to be done and transfer that increased momentum to my work. It works very well for me, and I recommend trying it, even if you are an owl type.

Thank you for reading, my dear reader. If you liked it, please share this article on social networks and follow me on Twitter: @tdd_fellow.

If you have any questions or feedback for me, don’t hesitate to reach me out on Twitter: @tdd_fellow.

Or did you ever had an incident happening in production, and half of your vocabulary at that time was not normative? Also, did you feel stressed and down afterward?

Or did you ever had to converse with a difficult person or someone holding a strong opinion, and thought not very good about them? Or even dismissed a valid argument just because you didn’t like the conversation?

Did you ever felt or did something negative, and thought afterward that it would be better not to? Then the technique described in this article is perfect for you!

Shall we get the ball rolling?

Drake’s Challenge

About one year ago I was talking to Daniel Irvine at the Software Craftsmanship meetup in Berlin about the technique that he was applying daily. I was amazed by how challenging it is and what results it can potentially yield. Since then I’m using this technique to increase awareness of how I feel, what I think, and what I am about to say.

It gives me the ability to respond to events around me instead of reacting to them. The reaction is the immediate reply executed by the subconscious part of our brain. The response is the delayed reply produced by the concious part of our brain. Responding is much better because it gives us time to think what would be the best response to the current situation. Especially it is better when something negative or weird is happening around us.

Enough preaching, let me tell you the challenge itself. For twenty-four hours do not say anything negative and do not think negatively.

How I Apply It

1. Get the stopwatch application running on my smartphone.
2. Start the stopwatch and leave the app in the background.
3. Every time I notice a negative thought, or I am saying something negative, reset the stopwatch.

My Experience So Far

Over this year, I felt like I can detect the negative feeling before it manifests as a negative thought, judgement, or a phrase. That helps me to be calmer, be more patient, and not spend time on insignificant things. If I know that something makes me unhappy or confuses me, I can call it out, and fix the problem without causing people around me to feel bad about it. Additionally, it makes me feel better.

Another thing that I have learned that, as soon as I am tired, I lose these abilities and fall back to reacting instead of responding. Good night sleep helps a lot with that ;)

I highly recommend you try this challenge. Caution: it is very hard.

Thanks

Thank you for reading, my dear reader. If you liked it, please share this article on social networks and follow me on Twitter: @tdd_fellow.

If you have any questions or feedback for me, don’t hesitate to reach me out on Twitter: @tdd_fellow.

This article is the sixth one of the series “Build Your Own Testing Framework” so make sure to stick around for next parts! Find all posts of these series here.

Shall we get started?

Verify All Tests Run

We will start from the RunTestSuiteTest and run the test suite with the single test. Then we are going to assert that for that the test with the name testOk has been reported as passing:

1
2
3
4
5
6
7
8
9
10
11

// test/RunTestSuiteTest.js

this.testItOutputsOkForThePassingTest = function () {
    runTestSuite(function (t) {
        this.testOk = function () {
            t.assertTrue(true);
        };
    }, {reporter: reporter});

    reporter.assertHasReportedPassingTest("testOk");
};

If we run this test suite, we can see that only one test executes!

1
2
3
4

RunTestSuiteTest
    testItCallsAllTestMethods

Process finished with exit code 0

Oh, that is interesting. This test suite does not run. Upon investigating, it turns out, that process.exit(0) is being called during the runTestSuite(...) function run. That is because of the latest feature that we have implemented - “exit with an appropriate exit code (zero for success, and one for failure).” We should be able to fix that by providing the process spy in the options of the runTestSuite function that we are calling from the inside of the individual tests in the RunTestSuiteTest test suite. And we ought to alleviate this kind of mistake somehow - we need a mechanism that would alert us if not all tests have been run. Maybe something like verifyAllTestsRun: true option for the runTestSuite. For that let’s write a test:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

this.testVerifyAllTestsRun = function () {
    t.assertThrow("Expected all tests to run", function () {

        runTestSuite(function SuiteWithTwoTests(t) {

            this.testWithRunTestSuite = function () {
                runTestSuite(function (t) {
                    this.testOne = function () {};
                }, {reporter: reporter});
            };

            this.testThatShouldAlsoRun = function () {};

        }, {reporter: reporter,
            process: process,
            verifyAllTestsRun: true});

    });
};

That might be a bit complex at first. Let’s take a closer look how this test is supposed to work:

1. First of all, we do assert that there was an assertion failure about all tests required to run.
2. Inside of the action for this assertion we create and run the new test suite with two tests:
   • test with the runTestSuite without process spy provided
   • empty test that should also execute

If we run this test, it will pass. That is unexpected because we wanted it to fail. Apparently, most inner runTestSuite is doing process.exit(0).

For that to work, we will need to be able to provide a hook into process.exit(code) function. For that, we would need to create a SimpleProcess class, that allows installation of such hooks. Let’s test-drive it!

process.exit with hooks

First, we should start from the normal behavior without any hooks:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// test/SimpleProcessTest.js
var runTestSuite = require("../src/TestingFramework");
var SimpleProcess = require("../src/TestingFramework").SimpleProcess;
var ProcessSpy = require("./ProcessSpy");

runTestSuite(function SimpleProcessTest(t) {
    this.testWithoutHooks = function () {
        var globalProcess = new ProcessSpy();
        var process = new SimpleProcess(globalProcess);

        process.exit(0);

        t.assertEqual(0, globalProcess.hasExitedWithCode);
    };
});

When running this test, we will get a failure about SimpleProcess being undefined. So let’s define it:

1
2
3
4
5
6
7
8
9
10
11

// src/TestingFramework.js

// ...
// define the class itself
function SimpleProcess(globalProcess) {

}

// ..
// and don't forget to export it
module.exports.SimpleProcess = SimpleProcess;

If we run our test suite now, we will get an error TypeError: process.exit is not a function. To fix that failure we will have to define the exit(code) method on our newly created class SimpleProcess:

1
2
3
4
5

function SimpleProcess(globalProcess) {
    this.exit = function (code) {

    };
}

After doing that we will get an assertion failure Error: Expected to equal 0, but got: null, as expected. To make the test pass, it would be enough to call globalProcess.exit(0):

1
2
3

this.exit = function (code) {
    globalProcess.exit(0);
};

If we run our test suite now, we will get no failures. That is great! Now, we can see that globalProcess.exit(0) is probably not exactly what we want to have there. We ought to pass the code parameter to the exit function. To test-drive this properly, we will have to triangulate, i.e.: add another test with the different value of the code parameter:

1
2
3
4
5
6
7
8

this.testWithoutHooks_andDifferentExitCode = function () {
    var globalProcess = new ProcessSpy();
    var process = new SimpleProcess(globalProcess);

    process.exit(1);

    t.assertEqual(1, globalProcess.hasExitedWithCode);
};

That fails as expected: Error: Expected to equal 1, but got: 0. To make it pass we can either write some weird “if” statement or we could pass the code parameter to the globalProcess.exit function. The second option is simpler. According to the third rule of test-driven development, we should go for it:

1
2
3

this.exit = function (code) {
    globalProcess.exit(code);
};

That change makes our test suite pass. We probably should refactor the test suite to reduce the level of the duplication by extracting common variables from the tests:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

runTestSuite(function SimpleProcessTest(t) {
    var globalProcess = new ProcessSpy();
    var process = new SimpleProcess(globalProcess);

    this.testWithoutHooks = function () {
        process.exit(0);

        t.assertEqual(0, globalProcess.hasExitedWithCode);
    };

    this.testWithoutHooks_andDifferentExitCode = function () {
        process.exit(1);

        t.assertEqual(1, globalProcess.hasExitedWithCode);
    };
});

At that point, we should move on to tests for the hook installation functionality. Because right now we need only at most one hook we will not support multiple hooks at the same time - only one:

1
2
3
4
5
6
7
8

this.testCanInstallOneHook = function () {
    var aSpy = t.spy();

    process.installHook(aSpy);
    process.exit(0);

    aSpy.assertCalled();
};

When we run this test, it fails because installHook function is not defined: TypeError: process.installHook is not a function. So we should define it:

1
2
3
4
5
6

function SimpleProcess(globalProcess) {
    // ..
    this.installHook = function (aHook) {

    };
}

Upon running these tests, we get Error: Expected to be called because we didn’t call this hook yet. The simplest way to make it pass is to just call the hook from the installHook function:

1
2
3
4
5
6

function SimpleProcess(globalProcess) {
    // ...
    this.installHook = function (aHook) {
        aHook();
    };
}

While that will make the tests pass it is not the behavior that we are after. To drive out the correct behavior, we ought to check that the function is being called only after process.exit(..), not earlier. For that we will need to have a sanity-check assertion:

1
2
3
4
5
6
7
8
9
10

this.testCanInstallOneHook = function () {
    var aSpy = t.spy();

    process.installHook(aSpy);
    aSpy.assertNotCalled();

    process.exit(0);

    aSpy.assertCalled();
};

That fails as expected with the error Error: Expected not to be called. To make it pass we need to store the function in the variable and call it from the process.exit(..):

1
2
3
4
5
6
7
8
9
10
11
12
13
14

function SimpleProcess(globalProcess) {
    var hook = null;

    this.exit = function (code) {
        if (hook !== null)
            hook();

        globalProcess.exit(code);
    };

    this.installHook = function (aHook) {
        hook = aHook;
    };
}

All the tests pass now! Finally, we want to be able to uninstall the hook, so let’s write the test for it:

1
2
3
4
5
6
7
8
9
10

this.testCanUninstallTheHook = function () {
    var aSpy = t.spy();

    process.installHook(aSpy);
    process.uninstallHook();

    process.exit(0);

    aSpy.assertNotCalled();
};

To make it work it is enough to introduce this function and set hook variable back to null in it:

1
2
3
4
5
6

function SimpleProcess(globalProcess) {
    // ...
    this.uninstallHook = function () {
        hook = null;
    };
}

And all the tests will pass. Now we, also, want to replace the default value for the options.process option with the instance of SimpleProcess object. And all the tests should work as they were working before:

1
2
3
4
5
6
7
8
9
10

var simpleProcess = new SimpleProcess(global.process);

function TestSuiteRunContext(testSuiteConstructor, options) {
    // ...

    var process = options.process || simpleProcess;
    // instead of just "global.process"

    // ...
}

Installing the “verify all tests run” hook

Now, we can get back to our “verify all tests run” test. It still doesn’t fail as expected, so we need to install the hook, count all tests, count tests that had already run and compare them in the hook:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

function TestSuiteRunContext(testSuiteConstructor, options) {
    // ...
    var verifyAllTestsRun = options.verifyAllTestsRun || false;
    var testCount = 0;
    var testRun = 0;

    this.invoke = function () {
        if (verifyAllTestsRun)
            installVerifyAllTestsRunHook();  // <---

        reportTestSuite();
        countAllTests();                     // <---
        runAllTests();
        finishTestRun();
    };

    function installVerifyAllTestsRunHook() {
        simpleProcess.installHook(function () {
            if (testRun < testCount) {
                throw new Error("Expected all tests to run");
            }
        });
    }

    // ...

    function countAllTests() {
        for (var testName in createTestSuite())
            if (testName.match(/^test/))
                testCount++;
    }

    // ...

    function handleTest(testName) {
        testRun++;                            // <---
        reportTest(testName);
        runTest(createTestSuite(), testName);
    }
}

At this point, this throws an error Expected all tests to run and finishes the test fully without reaching our assertThrow(..) assertion. That happens because we catch this error in the function runTest, where we mark the test as failed, log the error and ignore the error object itself from there. One way to solve this problem is to have a particular error, that can propagate up the stack:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

function installVerifyAllTestsRunHook() {
    simpleProcess.installHook(function () {
        if (testRun < testCount) {
            var error = new Error("Expected all tests to run");
            error.bubbleUp = true;
            throw error;
        }
    });
}

// ...

function runTest(testSuite, testName) {
    try {
        testSuite[testName]();
    } catch (error) {
        if (error.bubbleUp) throw error;  // <---
        if (!silenceFailures) console.log(error);
        status.markAsFailed();
    }
}

Now our current test is passing, and the next test is failing with the error Expected all tests to run. That happens because we have not uninstalled the hook as soon as it has triggered. Let’s do that:

1
2
3
4
5
6
7
8
9
10
11

function installVerifyAllTestsRunHook() {
    simpleProcess.installHook(function () {
        if (testRun < testCount) {
            simpleProcess.uninstallHook();   // <---

            var error = new Error("Expected all tests to run");
            error.bubbleUp = true;
            throw error;
        }
    });
}

That makes the next test run, succeed and exit immediately after that with error code zero. Let’s see what will happen if we put verifyAllTestsRun: true on the top test suite here:

1
2
3

runTestSuite(function RunTestSuiteTest(t) {
    // ...
}, {verifyAllTestsRun: true});

That doesn’t work because we re-install different hook inside of this test and as soon as this test finishes, we uninstall it. So we have two ways out of this situation: allow multiple hooks, or move that single test to its own test suite file. I think the second options is much simpler. Also, we will add the test for the negative case, where all tests run correctly (when we provide proper process spy):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// test/VerifyAllTestsRunTest.js
var runTestSuite = require("../src/TestingFramework");
var ReporterSpy = require("./ReporterSpy");
var ProcessSpy = require("./ProcessSpy");

runTestSuite(function VerifyAllTestsRunTest(t) {
    var reporter = new ReporterSpy(t);
    var process = new ProcessSpy(t);

    this.testVerifyAllTestsRun = function () {
        t.assertThrow("Expected all tests to run", function () {

            runTestSuite(function SuiteWithTwoTests(t) {

                this.testWithRunTestSuite = function () {
                    runTestSuite(function (t) {
                        this.testOne = function () {};
                    }, {reporter: reporter});
                };

                this.testThatShouldAlsoRun = function () {};

            }, {reporter: reporter,
                process: process,
                verifyAllTestsRun: true});

        });
    };

    this.testVerifyAllTestsRun_withoutFailure = function () {
        t.assertNotThrow(function () {

            runTestSuite(function SuiteWithTwoTests(t) {

                this.testWithRunTestSuite = function () {
                    runTestSuite(function (t) {
                        this.testOne = function () {};
                    }, {reporter: reporter,
                        process: process});
                };

                this.testThatShouldAlsoRun = function () {};

            }, {reporter: reporter,
                process: process,
                verifyAllTestsRun: true});

        });
    };
});

And this new test suite passes as expected. Just to double-check that these tests verify anything, we can break them (change expected error message and change assertNotThrow to assertThrow) and see if there is a failure and if it looks as expected:

1
2
3
4
5
6
7
8
9
10
11
12
13

// was: t.assertThrow("some error", ...);
t.assertThrow("some error", function () {
    // ...
});
// => Error: Expected to equal some error,
//    but got: Expected all tests to run

// was: t.assertNotThrow(...);
t.assertThrow("some error", function () {
    // ...
});
// => Error: Expected to throw an error,
//    but nothing was thrown

And it fails as expected, which means that our refactored tests still work as they should.

We have just applied a neat technique here: whenever we do a major refactoring in tests, we need to make sure they are still functioning correctly. For that, we break every single one of them (by changing the assertion or breaking the production code). Then we see if they fail as we expect them to. When they don’t, we know that refactoring didn’t quite work.

Fixing test suites to run all tests

Now we can go back to the RunTestSuiteTest and see if it works as expected without that test. And it does: Error: Expected all tests to run. To fix that we need to provide a process spy in every inner call to runTestSuite. For that we will first extract {reporter: reporter} as a common variable of the test suite:

1
2
3
4
5
6
7

var options = {reporter: reporter};

// ...
// all the inner calls to "runTestSuite":
runTestSuite(function(t) {
    // ...
}, options);

And to make the error go away, we now can create a process spy and provide it through options:

1
2
3
4
5

var process = new ProcessSpy(t);
var options = {
    reporter: reporter,
    process: process
};

If we run tests now, they all pass. And we can see that they all execute. Now we just need to double-check that all tests, that have inner calls to runTestSuite have verifyAllTestsRun option enabled. The only other test suite is the FailureTest. Adding the option does not produce a failure because this test suite already uses process spy in all inner calls to runTestSuite.

Conclusion

Today we learned that it is tricky to work with process.exit or any function that can exit our program in the middle of the test. Such functions need to be mocked out completely inside of the tests. Also, we learned that it is possible to make sure we don’t forget to do that. That is quite important because, if we do forget, everything runs smoothly, and we don’t know that we made a mistake.

There is still a lot to go through. In a few next episodes we will:

• Report OK and FAIL for each test;
• Output carefully formatted failures to the STDERR;
• Enable our testing framework to run multiple test suite files at once;
• Enable our testing framework to run in a browser (it is javascript after all).

See you reading the next exciting article of the series: “Formatting the Output”!

Thanks

Thank you for reading, my dear reader. If you liked it, please share this article on social networks and follow me on Twitter: @tdd_fellow.

If you have any questions or feedback for me, don’t hesitate to reach me out on Twitter: @tdd_fellow.

Today we are going to learn the basic principles behind the Test-Driven Development Discipline. We will learn three rules of TDD. We will learn what are the benefits of doing Test-Driven Development. And we will take a look at the example application of these laws.

" feedback "  (CC BY-SA 2.0)  by Sonti Malonti

Articles of these series have exercises and going through them would make for more effective learning. Also, if you feel stuck with these exercises, fell free to shoot me an email or get in touch on Twitter: @tdd_fellow.

“Learning Test-Driven Development with Javascript” is a series of articles and you, my dear reader, can shape the content by providing an invaluable feedback. To do that, shoot me an email - oleksii@tddfellow.com.

Basics of Test-Driven Development

A test is a single program, procedure or function, that executes our system under the test and verifies that it works as expected. The system under the test is any other program, part of the program or library, procedure or function. The system under the test is called SUT for short.

SUT is the code that executes with a purpose of satisfying needs of our end users. Using the term “end user” we mean actual people using our system via the user interface (graphical and non-graphical), and other automated systems using our system via application programming interface (for short, API). A different term for the “end user” is “consumer of the system.” Another term for the SUT is “production code” - we are going to use the latter, as it is used in Test-Driven Development much more often.

Test-Driven Development is based on a simple concept of writing production code only when there is a failing test that demands that production code for it to pass.

We call a test failing when there is some error happening when we execute it. Possible failures are the following: there is a syntax error, or code does not compile, or there is a runtime failure during test setup or production code execution, or there is an assertion error. The assertion failure is the particular kind of error that happens during the final phase of the test, where we are verifying the outcomes after running the production code under the test. An assertion error signals that the production code executed successfully, but it produced incorrect results or changed the state of the system in a wrong fashion.

We call a test passing when there are no errors happen when we execute it. We, also, call the failing test “a red test” and we call the passing test “a green test.” That is because we can not deliver the code to our customers or consumers when there are “red” tests - think of red traffic light, and we are free to go when all the tests are “green” - think of green traffic light. Most of the testing tools and frameworks format their output to present failing tests in the red color and passing tests in the green color.

Multiple tests aiming to test single SUT or a particular feature of the system are usually called test suite. Depending on the context, test suite could mean that collection of tests all testing the same thing, or it could mean all tests of the entire system. For example, in the sentence “Let’s read User class’ test suite” that phrase means a collection of tests testing class User. On the other hand, in the sentence “Let’s run the whole test suite and see if we can deploy that right now” that phrase means all tests of the entire system. The latter, sometimes, is called “suite of tests.”

When the system behaves in an unexpected way, and the expected behavior was previously defined or present in the code, it is called a “bug.” For example, the behavior that is specified by the development team and not implemented correctly considered a bug. The behavior that is defined by the development team and implemented correctly, but now it is not working, considered a bug. And, finally, the behavior that was not defined may or may not be considered as a bug. The latter depends on the produced results - if it harms or brings any value. This phenomenon is called a “bug” for historical reasons: the first bug in computing was a real bug, that stuck in the computer’s hardware and was causing short circuits which made the computer misbehave.

Three Rules of Test-Driven Development

In the core of Test-Driven Development there are three steps that we need to follow:

1. We start with a failing test. We consider any error a failure, including compilation and syntax errors. Meaning, that our first test for any part of the production code will fail for the reason that there is no production code to execute yet. For example class, method or function is undefined.
2. Then, we resolve the failure by writing the production code. For example: in the case of missing class, we would create a class; in the event of a missing method, we would create it; and in the instance of a failing assertion error, we would fix the logic to pass the test.
3. We write no more than the simplest production code, which makes our current failing test pass, and, also, still passes all other tests.

We repeat these steps over and over until we finish the implementation of the system under the test. Strictly following these steps will lock us in a very tight loop, where we will be switching between test code and production code all the time: write one or two lines of the test code and write or change one or two lines of the production code, repeat. This cycle is, probably, twenty or thirty seconds long. It, of course, depends on how fast we can run our tests. Ideally, we want our test suite for the current system under the test to run as fast as one clap of hands, or blink of an eye.

Feedback Loop Benefits

This tight cycle gives us following benefits:

• Alerts us to the mistakes we do while coding immediately. Usually, it is enough to do one or two “Undo” commands in our editor to get back to the “green” state of the system - when all our tests are passing (occasionally, except for the last test we have added, as we will undo the incorrect implementation for it).
• Provides the safety net from bugs for the future development thanks to the fact, that no single line of production code is written other than to pass a failing test. Meaning, that whenever production code is broken in any fashion, there is a test that will point it out via failure. When adding new features or modifying the behavior of the existing ones, we might inadvertently introduce a bug. Our suite of tests will detect that bug as soon as we run all our tests, which we would certainly do during development and, especially, before the deployment or release of our systems. This is, basically, a near 100% test coverage. Surely, there are subtle and complex bugs that involve whole sub-systems and 3rd-party systems to come together in some special edge case to appear - rarely, such bugs are not prevented by Test-Driven Development. Of course, we are talking about 1-3 such bugs per year - this is much better than having a bug tracker, that contains thousands of unresolved bugs. Who said it was a good idea to have a database that stores the bugs in our system? - When we apply TDD correctly, and our bug counts are so small, as 1-3 per year, we should treat bugs as “Red Alerts” and concentrate all the effort on shooting them down. Writing a test for these bugs when we already figured them out allows us to programmatically prove, that the system, indeed, does misbehave in a certain edge case, and prevents this bug from reoccurring after we have fixed it.
• Gives the confidence to refactor freely and ruthlessly. Essentially, allows changing the software design of the system on the go without applying the big design upfront (BDUF). Let’s take a look at the example. Imagine, we have a system with a perfect design and without any tests. Over time the design will degrade until the code becomes nearly impossible to work with. Now, imagine, we have a system with bad design and close to 100% test coverage. Over time we can improve the design of the application gradually while responding to the changes in the needs of our end users. And we will be faster as the time passes.
• Makes the development team always ready to deploy. While practicing test-driven development, development teams will keep latest implemented features in the version control system for the source code in the state, that is well-known to be “green.” This condition of the system is deliverable to the end users with one push of the button. That, also, enables teams to do continuous delivery: as soon as the code is checked-in in the version control system (VCS), it is going to be automatically deployed to production and our end users will get the value out of it sooner.
• Promotes simplicity and alleviates the scope creep. “Oh, we don’t need that yet” is the most used phrase in the vocabulary of the typical test-driven development practitioner. Tests that we write specify only the useful functionality that we need to deliver the value to our end users. These tests don’t talk about performance optimizations, security concerns, rare edge cases, “re-usable” abstractions (that, usually, are harder to understand and are difficult to re-use), etc. These things need to be implemented only when there is an actual end user value to be achieved, or the system is obviously running slower than it should, or there is an actual security concern. In that case, a very specific test (or tests) will be written to drive out that additional functionality. Since the most software development cost is in the maintenance of the existing functionality leaving out as much functionality (and code) as possible is a good idea.
• Promotes cleaner interfaces. As in test-driven development, we have to write the usage example before we implement (or even design) the API in the production code, it will be optimized for ease and clarity of use and less so with the internal implementation details of that production code. Generally speaking, test-driven production code is easier to use and understand.
• Tests that call the production code serve as usage examples of that code. Essentially, in a test-driven code base, to know how a particular API can be used, it is enough to read and understand its test suite. These tests are the perfect low-level documentation for the APIs in our code base that developers can understand and read best. And that documentation is so precise that it can be executed and verified that it is still in sync with the actual code it is describing. Therefore this documentation is always up-to-date.

The most important of these benefits is the confidence to make any change to the software and know in one minute or two, if that change is good to be delivered to the end user or not, with a simple push of the button. No quality assurance (QA) manual testing cycles are required. Let’s take a look at the example of the application of three rules of test-driven development. We will start from a very simple example, so that we don’t have to touch more advanced TDD techniques.

English Numbers Kata

Given an integer number
When I call the system with that number
Then I receive a string representation of that number in an English language

For example:

• for number 37 I receive "thirty-seven"
• for number -17451 I receive "minus seventeen thousand four hundred fifty-one"

According to the first rule of TDD, we have to start the implementation from the test. In test-driven development it is important to start from the simplest tests, that can be implemented via a small, simple change to production code. For example: with number zero we expect the result to be “zero.” When writing the first test for the new functionality we are going to design its API. In our case we are going to come up with the function name and its argument list:

1
2
3
4
5
6
7
8
9

describe("toEnglishNumber", function() {
    it("converts 0 to zero", function() {
        // ARRANGE
        var number = 0;

        // ACT
        var englishNumber = toEnglishNumber(number);
    });
});

As soon as we write toEnglishNumber(number) we have designed the function’s signature, at least, for the single simplest case. Also, the test suite is failing now, because toEnglishNumber is not a function - in fact, it is undefined. That means that we have entered the red stage of test driven development and according to the second rule of TDD we have to switch back to the production code. And according to the third rule, we have to write just enough of it to make the failing test pass. That means writing the simplest and easiest code possible to make it succeed. In this case, we could just return nothing (null in javascript):

1
2
3

function toEnglishNumber(number) {
    return null;
}

This is going to turn our test suite back to the green stage. At this point it is a good idea to look at both test code and production code and see if there are any opportunities for refactoring, such as better names, extracting methods/functions, clarifying variable names, de-duplication, etc. Because we are currently in a green state, we can safely apply any refactoring, automated or manual, and see if it was successful by running the test again. If for some reason, the test is failing after the refactoring, we always have an option to CTRL/CMD+Z back to the green state, back to safety. At this point, we have finished applying one cycle of rules of TDD. Now we need to start over. We go back to our test code. There we extend the existing test to be more specific. Or we add more tests. Since we didn’t finish writing the test yet - we have only “arrange” and “act” parts, and we are missing the “assert” part of the test, - we ought to extend the current test to make it more specific. So what can we assert about the result of the toEnglishNumber call? We probably ought to return the string “zero”, aren’t we? So, let’s make an appropriate assertion:

1
2
3
4
5
6
7
8
9
10
11

it("converts 0 to zero", function() {
    // ARRANGE
    var number = 0;

    // ACT
    var englishNumber = toEnglishNumber(number);

    // ASSERT
    var expected = "zero";
    expect(englishNumber).toEqual(expected);
});

If we run our tests right now, they will fail. We should take a careful look at the failure and see if the failure message is readable and it is what we expected. In the current situation, we will receive an assertion failure, telling us that null was not equal to “zero.” Imagine now, that we are working on some other feature and we are not in the context of the English number conversion feature. What would be our reaction, when we run this test and see this failure? - We will probably be confused for a moment and will resort to jump to the line in the source code of the test suite that produces that error and try to understand what happened there. That is a huge context switch, and it will disrupt our current flow. So we can do better and make the failure much more readable by just adding a small thing - a cue, what that null was supposed to be: “english number”:

1

expect(englishNumber).toEqual(expected, "english number");

In Jasmine, the second argument to the toEqual matching function is the description of the failure. I think our test looks great, and so is the failure in the test output. And because we are having a good failing test, according to the second rule, we don’t have to write any of test code. Now, we should make the test pass according to the third rule. And what would be the simplest way to make it work? - Return “zero”:

1
2
3

function toEnglishNumber(number) {
    return "zero";
}

At this point, we should look out for the refactoring opportunities, and I don’t think there are any yet. So let’s start the cycle over. To apply the first rule, we might just copy the existing test and change the input and the expected output accordingly. In that case, we would want to test another simple one-digit number - “one”:

1
2
3
4
5
6
7
8
9
10
11

it("converts 1 to one", function() {
    // ARRANGE
    var number = 1;

    // ACT
    var englishNumber = toEnglishNumber(number);

    // ASSERT
    var expected = "one";
    expect(englishNumber).toEqual(expected, "english number");
});

Now, because the test is failing, we apply the second rule and switch back to the production code. To make the test pass, according to the third rule, we will need to introduce the simplest change possible: in that case, an “if” statement (and we will use === instead of == for comparison to avoid implicit type conversions in javascript):

1
2
3
4
5
6
7

function toEnglishNumber(number) {
    if (number === 1) {
        return "one";
    }

    return "zero";
}

That is going to make all our tests pass. If we continue adding tests for the single-digit numbers while following these three rules, we will wind up with something like that:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

function toEnglishNumber(number) {
    if (number === 1) {
        return "one";
    }

    if (number === 2) {
        return "two";
    }

    if (number === 3) {
        return "three";
    }

    if (number === 4) {
        return "four";
    }

    if (number === 5) {
        return "five";
    }

    if (number === 6) {
        return "six";
    }

    if (number === 7) {
        return "seven";
    }

    if (number === 8) {
        return "eight";
    }

    if (number === 9) {
        return "nine";
    }

    return "zero";
}

At this point, we can see a clear pattern: one-to-one correspondence of a single-digit integer to the string. This code can be simplified as a pre-defined array of strings at the corresponding indices:

1
2
3
4
5
6
7
8
9
10
11
12

var singleDigitNumbers = [
    "zero",
    "one",
    "two",
    "three",
    "four",
    "five",
    "six",
    "seven",
    "eight",
    "nine"
];

We also include string “zero” in that array because return "zero" is only happening when the number is equal to zero since we don’t have any other tests right now - only from zero to nine. And the function itself will look much simpler:

1
2
3

function toEnglishNumber(number) {
    return singleDigitNumbers[number];
}

Since we are done with the refactoring, we should proceed using the first rule of test-driven development, which means we need to write a test that fails. So let’s increase the complexity of our tests and go for teen numbers. We’ll start from ten:

1
2
3
4
5
6
7
8
9
10
11

it("converts 10 to ten", function() {
    // ARRANGE
    var number = 10;

    // ACT
    var englishNumber = toEnglishNumber(number);

    // ASSERT
    var expected = "ten";
    expect(englishNumber).toEqual(expected, "english number");
});

That will fail because so far our production code tries to fetch a string representation of the english number from the array using the number itself as an index. At the index ten, we don’t have anything, so our function returns nothing. According to the second rule of test-driven development, we need to switch to production code to make it pass. There are a few ways to fix the current problem: add specific if statement to the production code, or add a string “ten” to the array. Second seems to be simpler, and we know that we can do it for the teen numbers because they can not be composed of any other small parts. So, according to the third rule, we should go for it because it is a much simpler solution:

1
2
3
4

var singleDigitNumbers = [
    // ...
    "ten"
];

That makes our tests pass. And I think we have a refactoring opportunity: variable name singleDigitNumbers does not make any sense anymore - it contains not only single digit numbers, but, also, number “ten,” which is a two-digit number. So what is common between single digit numbers and ten? They are simple numbers, i.e.: can not be composed out of other english number string representations. Let’s just call them simpleNumbers in this case:

1
2
3
4
5
6
7

var simpleNumbers = [
    // ...
];

function toEnglishNumber(number) {
    return simpleNumbers[number];
}

After making this refactoring, we need not forget to run the test suite to see if we didn’t make a mistake. When we run it, then all our tests pass. So we can go back to the first rule of test-driven development again. Going through this cycle again for a few times will produce tests for numbers from eleven to nineteen. The production code will only have those numbers’ english string representations added to the simpleNumbers array:

1
2
3
4
5
6
7
8
9
10
11

var simpleNumbers = [
    "zero", "one", "two", "three", "four",
    "five", "six", "seven", "eight", "nine",

    "ten", "eleven", "twelve", "thirteen", "fourteen",
    "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"
];

function toEnglishNumber(number) {
    return simpleNumbers[number];
}

Now it is time to introduce the concept of a complex number, such as twenty-three. It is a number that consists of the “tens” part and single-digit part. According to the first rule we have to start with the failing test, and I think we should just go for the number twenty-three:

1
2
3
4
5
6
7
8
9
10
11

it("converts 23 to twenty-three", function() {
    // ARRANGE
    var number = 23;

    // ACT
    var englishNumber = toEnglishNumber(number);

    // ASSERT
    var expected = "twenty-three";
    expect(englishNumber).toEqual(expected, "english number");
});

If we run our test suite, that test will fail. According to the second rule of test-driven development, now we have to switch to the production code. According to the third rule, we will have to choose the simplest code that makes this test pass (and doesn’t break any other test). In our case, we have multiple options, which are similar in their simplicity. One of them is to return “twenty-three” if the number is greater than or equal to twenty:

1
2
3
4
5
6
7

function toEnglishNumber(number) {
    if (number >= 20) {
        return "twenty-three";
    }

    return simpleNumbers[number];
}

If we run our test suite, all tests will pass. Now we should see if there are any opportunities for making the code more readable and easier to understand. While the whole if statement returning a constant might feel strange, there is a concept that we can already give a name to in there: “three.” We already can obtain a string “three” from number three using the method toEnglishNumber(number). Let’s try this refactoring:

1
2
3
4
5
6
7

function toEnglishNumber(number) {
    if (number >= 20) {
        return "twenty-" + toEnglishNumber(3);
    }

    return simpleNumbers[number];
}

That code now looks interesting. And it passes all its tests. Since, of course, we are not done yet with the implementation, according to the first rule of test-driven development, we ought to write another failing test. And we have a multitude of choices what it could be, we can just come up with other random two-digit number, such as forty-two, or we could leave the “twenty-” part in and change the “three” part to “seven,” for example. Also, we could change “twenty-” part to “thirty-.” Generally, in test-driven development it is better to go for the test, that will cause the smallest change to the production code, - later we will explore more on why that is. So, we could go for twenty-seven, as it will cause the smallest change to our production code:

1
2
3
4
5
6
7
8
9
10
11

it("converts 27 to twenty-seven", function() {
    // ARRANGE
    var number = 27;

    // ACT
    var englishNumber = toEnglishNumber(number);

    // ASSERT
    var expected = "twenty-seven";
    expect(englishNumber).toEqual(expected, "english number");
});

This test is failing, as expected. According to the second rule, we have to switch to the production code and make it pass. Also, the simplest change (third rule) that we could do is to change “3” to the last digit of the number, the remainder of the division by ten - “number % 10”:

1
2
3
4
5
6
7

function toEnglishNumber(number) {
    if (number >= 20) {
        return "twenty-" + toEnglishNumber(number % 10);
    }

    return simpleNumbers[number];
}

Now if we run our test suite all the tests will pass. “The remainder of division by ten” part looks right and “twenty-” constant still feels like it is not gonna work for every two-digit number. I think it is time to write a new failing test (first rule). That will be the test that will prove that “twenty-” is not correct code. In that case, we just need to change the first digit of the number so that we could go for forty-two:

1
2
3
4
5
6
7
8
9
10
11

it("converts 42 to forty-two", function() {
    // ARRANGE
    var number = 42;

    // ACT
    var englishNumber = toEnglishNumber(number);

    // ASSERT
    var expected = "forty-two";
    expect(englishNumber).toEqual(expected, "english number");
});

As soon as we finish writing the assertion we will have a test failure: we are returning “twenty-two” instead of “forty-two.” So it is time to switch to the production code (second rule). And we need to write just enough of it to make this test pass (third rule). We can do that by having yet another if statement:

1
2
3
4
5
6
7
8
9
10
11

function toEnglishNumber(number) {
    if (number >= 20) {
        if (number / 10 == 2) {
            return "twenty-" + toEnglishNumber(number % 10);
        }

        return "forty-" + toEnglishNumber(number % 10);
    }

    return simpleNumbers[number];
}

And this will make the test pass. It looks very similar to what we had with one-digit numbers, where we had an “if” statement checking that some value is equal to some number and returning an appropriate string. That is where we converted it to an array with string values, and in the function, we were fetching these strings by their index. To see if that pattern applies here we could write another similar test that will make us write another if statement:

1
2
3
4
5
6
7
8
9
10
11

it("converts 39 to thirty-nine", function() {
    // ARRANGE
    var number = 39;

    // ACT
    var englishNumber = toEnglishNumber(number);

    // ASSERT
    var expected = "thirty-nine";
    expect(englishNumber).toEqual(expected, "english number");
});

And this fails as expected because our production code in no case can return “thirty-.” So let’s write the simplest if statement to make it pass. Also, to make it uniform, we would wrap “forty-” case in its appropriate if statement as a refactoring after we have a passing test suite:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

function toEnglishNumber(number) {
    if (number >= 20) {
        if (number / 10 == 2) {
            return "twenty-" + toEnglishNumber(number % 10);
        }

        if (number / 10 == 3) {
            return "thirty-" + toEnglishNumber(number % 10);
        }

        if (number / 10 == 4) {
            return "forty-" + toEnglishNumber(number % 10);
        }
    }

    return simpleNumbers[number];
}

Certainly, there is a fair bit of duplication right now: “number / 10” and “number % 10”. Let’s extract them as variables. Also, let’s extract “twenty”, “thirty”, “forty” and “toEnglishNumber(lastDigit)” parts as variables:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

function toEnglishNumber(number) {
    if (number >= 20) {
        var firstDigit = number / 10;
        var lastDigit = number % 10;

        var firstPart;
        if (firstDigit == 2) {
            firstPart = "twenty";
        }

        if (firstDigit == 3) {
            firstPart = "thirty";
        }

        if (firstDigit == 4) {
            firstPart = "forty";
        }

        var secondPart = toEnglishNumber(lastDigit);

        return firstPart + "-" + secondPart;
    }

    return simpleNumbers[number];
}

Now, we could extract the function for conversion of the first digit to the first english part, such as twenty or thirty:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

function convertTens(digit) {
    if (digit == 2) {
        return "twenty";
    }

    if (digit == 3) {
        return "thirty";
    }

    if (digit == 4) {
        return "forty";
    }
}

function toEnglishNumber(number) {
    if (number >= 20) {
        var firstDigit = number / 10;
        var lastDigit = number % 10;

        var firstPart = convertTens(firstDigit);
        var secondPart = toEnglishNumber(lastDigit);

        return firstPart + "-" + secondPart;
    }

    return simpleNumbers[number];
}

Now, it looks like the function convertTens can be simplified through usage of array in the same way as we did before with toEnglishNumber:

1
2
3
4
5

var tens = ["", "", "twenty", "thirty", "forty"];

function convertTens(digit) {
    return tens[digit];
}

At this point, we can write more tests to cover all different first digits, for example fifty-seven, sixty-five, seventy-three, eighty-nine and ninety-one. To make them pass we will have to add corresponding “tens” number to our array:

1
2
3
4
5
6

var tens = [
    "", "",

    "twenty", "thirty", "forty", "fifty",
    "sixty", "seventy", "eighty", "ninety"
];

So, that is how we apply three rules of test-driven development. Here is the full code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

describe("toEnglishNumber", function() {

    it("converts 0 to zero", function() {
        // ARRANGE
        var number = 0;

        // ACT
        var englishNumber = toEnglishNumber(number);

        // ASSERT
        var expected = "zero";
        expect(englishNumber).toEqual(expected);
    });

    it("converts 1 to one", function() {
        // ARRANGE
        var number = 1;

        // ACT
        var englishNumber = toEnglishNumber(number);

        // ASSERT
        var expected = "one";
        expect(englishNumber).toEqual(expected, "english number");
    });

    it("converts other one-digit numbers", function() {
        expect(toEnglishNumber(2)).toEqual("two", "english number");
        expect(toEnglishNumber(3)).toEqual("three", "english number");
        expect(toEnglishNumber(4)).toEqual("four", "english number");
        expect(toEnglishNumber(5)).toEqual("five", "english number");
        expect(toEnglishNumber(6)).toEqual("six", "english number");
        expect(toEnglishNumber(7)).toEqual("seven", "english number");
        expect(toEnglishNumber(8)).toEqual("eight", "english number");
        expect(toEnglishNumber(9)).toEqual("nine", "english number");
    });

    it("converts 10 to ten", function() {
        // ARRANGE
        var number = 10;

        // ACT
        var englishNumber = toEnglishNumber(number);

        // ASSERT
        var expected = "ten";
        expect(englishNumber).toEqual(expected, "english number");
    });

    it("converts other teen numbers", function() {
        expect(toEnglishNumber(11)).toEqual("eleven", "english number");
        expect(toEnglishNumber(12)).toEqual("twelve", "english number");
        expect(toEnglishNumber(13)).toEqual("thirteen", "english number");
        expect(toEnglishNumber(14)).toEqual("fourteen", "english number");
        expect(toEnglishNumber(15)).toEqual("fifteen", "english number");
        expect(toEnglishNumber(16)).toEqual("sixteen", "english number");
        expect(toEnglishNumber(17)).toEqual("seventeen", "english number");
        expect(toEnglishNumber(18)).toEqual("eighteen", "english number");
        expect(toEnglishNumber(19)).toEqual("nineteen", "english number");
    });

    it("converts 23 to twenty-three", function() {
        // ARRANGE
        var number = 23;

        // ACT
        var englishNumber = toEnglishNumber(number);

        // ASSERT
        var expected = "twenty-three";
        expect(englishNumber).toEqual(expected, "english number");
    });

    it("converts 27 to twenty-seven", function() {
        // ARRANGE
        var number = 27;

        // ACT
        var englishNumber = toEnglishNumber(number);

        // ASSERT
        var expected = "twenty-seven";
        expect(englishNumber).toEqual(expected, "english number");
    });

    it("converts 42 to forty-two", function() {
        // ARRANGE
        var number = 42;

        // ACT
        var englishNumber = toEnglishNumber(number);

        // ASSERT
        var expected = "forty-two";
        expect(englishNumber).toEqual(expected, "english number");
    });

    it("converts 39 to thirty-nine", function() {
        // ARRANGE
        var number = 39;

        // ACT
        var englishNumber = toEnglishNumber(number);

        // ASSERT
        var expected = "thirty-nine";
        expect(englishNumber).toEqual(expected, "english number");
    });

    it("converts other two-digit numbers", function() {
        expect(toEnglishNumber(57)).toEqual("fifty-seven", "english number");
        expect(toEnglishNumber(65)).toEqual("sixty-five", "english number");
        expect(toEnglishNumber(73)).toEqual("seventy-three", "english number");
        expect(toEnglishNumber(89)).toEqual("eighty-nine", "english number");
        expect(toEnglishNumber(91)).toEqual("ninety-one", "english number");
    });

});

var simpleNumbers = [
    "zero", "one", "two", "three", "four",
    "five", "six", "seven", "eight", "nine",

    "ten", "eleven", "twelve", "thirteen", "fourteen",
    "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"
];

var tens = [
    "", "",

    "twenty", "thirty", "forty", "fifty",
    "sixty", "seventy", "eighty", "ninety"
];

function convertTens(digit) {
    return tens[digit];
}

function toEnglishNumber(number) {
    if (number >= 20) {
        var firstDigit = number / 10;
        var lastDigit = number % 10;

        var firstPart = convertTens(firstDigit);
        var secondPart = toEnglishNumber(lastDigit);

        return firstPart + "-" + secondPart;
    }

    return simpleNumbers[number];
}

Exercises

1. Do you see the missing edge case for two-digit numbers? Write a test for it and make it pass using three rules of test-driven development.
2. Add support for three-digit numbers.
3. Add support for negative numbers.
4. Add support for numbers with the floating point.

Conclusion

Today we have learned a lot of concepts from testing and test-driven development. Also, we have learned the essence of TDD - three rules of TDD. We have learned how to apply these rules on a very simple example. We have touched on how beneficial test-driven development can be when applied well.

In the next article of the series, we will discuss what different kinds of tests exist, how and when to write them and how to apply TDD in these tests. Also, we will get back to our application and implement a new feature.

Thanks

Thank you for reading, my dear reader. If you liked it, please share this article on social networks and follow me on twitter: @tdd_fellow.

If you have any questions or feedback for me, don’t hesitate to reach me out on Twitter: @tdd_fellow.

“Learning TDD with Javascript” is the series of articles where we learn basics of automated testing and test-driven development. While the language of choice for the code examples is Javascript, all described concepts are language-agnostic and are applicable in various technological stacks. In these articles, a reader is expected to do small exercises after each major topic to reinforce that theoretical knowledge with practice. Some of these exercises are practical and will involve coding, or simple writing; others will be food for thought. Also, a reader might want to get their feedback on these exercises, so don’t hesitate to send the results my way: oleksii@tddfellow.com - feedback on the practice is quite important as it helps to improve quicker, when you know what is well and what can be improved and how. Also, don’t hesitate to send any questions and feedback regarding the content of these articles. Your questions, feedback, and your practical results will help authors shape this content better.

Today we are going to learn how to write tests that imitate real user interaction for the whole application. We are going to build a small web application using Vanilla Javascript. Vanilla Javascript is a plain Javascript without any framework or library. Such tests that imitate real user interaction via User Interface (UI) are called End-to-End Tests. These tests are the most simple to write because we only need to think about our application in the same way user does:

• Imitating the user clicking on the button would mean for us to trigger a button click;
• Imitating the user typing text in the input field would mean for us to change input’s value;
• Imitating the user clicking on the link would mean for us to trigger a link click;
• And so on.

We don’t need to think about specific implementation details, such as: which functions and classes do we have in our code and how they interact with each other, is there any interaction with the back-end server or 3rd-party API. Also, we don’t need to be proficient with interaction testing - this is the topic for the future series.

Of course, for that kind of simplicity we are trading something off. In the case of End-to-End tests, they are slower, suffer concurrency, wait, and timeout problems, and are harder to maintain in the long run. We don’t have to worry about that just yet because we want to learn how to write tests in general, and this kind of simplicity is perfect for us in this case.

Such simplicity stems from the fact that End-to-End tests, mostly, are direct translations of user stories (use case scenarios) into the UI manipulation code.

User Story

User stories are scenarios describing an individual feature of the software via user story context, sequences of user interactions and user expectations. User story context is the description of the situation the user and the software system are in at the beginning of the scenario. An example of the system context: “user John is registered in the system with password ‘welcome’.” An example of the user context: “user is at the login page.” User interaction is the description of a particular action user takes inside of the system, usually, doing something within the UI, for example: “User enters email ‘john@example.org’ in the email input field” or “User clicks on the submit button.” Finally, user expectation is the description of what particular information user should receive from the system, for example: “User sees the success message on the page” or “User receives the email with the verification code.”

User stories come in different flavor and formats. It can be a free-form text, describing three parts: context, interactions, and expectations; or it can be in a formal “Given-When-Then” form. “Given” part is the sequence of the user story context descriptions, “When” part is the sequence of the user interaction descriptions, and “Then” part is the sequence of user expectation descriptions. Both forms can be used interchangeably, and some software companies use one or another formal version of the user story format consistently.

Let’s take a look at the example of the free-form user story together with the example of the Given-When-Then user story for the same feature:

As we can see, free-form can be very vague and is very flexible, and formal form is more strict and precise. The free-form on its own doesn’t have much upsides or downsides - it is as good as it is written. On the other hand, the formal form does give us some value and also trades something off for that value. They are generally easy to write and, because they are so specific, are easy to translate to the automated test. On the other hand, they may hamper creativity either while creating the user story or when implementing it.

It is important to mention that these use case scenarios are not full user stories or features. One feature can have multiple scenarios like that - together they are called acceptance criteria. When all such scenarios of the given feature work correctly, the feature is done. There is another vital part of the user story - general description, that should contain the rationale behind the story and the value for the user or any other important actor in the system, such as the stakeholder. Before we write scenarios, we often come up with the rationale like that and it drives us to write a scenario. For example, for the feature above we would have used something like that:

Because formal form user stories are more precise, easier to write and simpler to translate to the automated test, we are going to use them to learn End-to-End testing in the context of Test-Driven Development.

Exercises

1. Write a scenario for authentication story, when John enters the wrong password.
2. Write a user story with rationale and scenarios for the sign-up feature.
3. Imagine we are developing an instant messaging application. What do you think would be the next feature after login/sign-up? Write the user story with rationale and scenarios for this feature.

Do you have questions? Or do you want to get quick feedback on how you did the exercises? - mail me: oleksii@tddfellow.com

Setting Up the Project

Now we will be writing a simple web application, using Vanilla Javascript (ECMAScript 5), so that our setup is rather simple. For the testing, we will be using a standalone version of the Jasmine testing framework. Also, we will be writing a single page application (SPA), so that we don’t have to worry about rendering different pages in our tests for now. We are aiming for the following directory structure of our project:

1
2
3
4
5
6
7
8
9

.
├── lib
├───── .. external libraries, such as Jasmine ..
├── spec
├───── .. sources with Jasmine automated tests ..
└── src
├───── .. sources with our main code ..
├── index.html       - entry point to the application
├── SpecRunner.html  - entry point to our test suite

First, create required directories: lib, spec and src. Then download the latest standalone Jasmine release here: https://github.com/jasmine/jasmine/releases (jasmine-standalone-{version}.zip file). At the time of writing, the version is 2.5.2. Unzip that file into your project directory. You should get the following files from it:

• ./lib/jasmine-2.5.2/ directory - contains all the resources required by Jasmine.
• ./SpecRunner.html - example entry point to our test suite.
• ./src/Player.js and ./src/Song.js - example source files.
• ./spec/PlayerSpec.js and ./spec/SpecHelper.js - example automated Jasmine tests.

Now, try to open SpecRunner.html in your browser. It should run these example tests, and they should all pass. Here is how it should look like:

Also, create an empty index.html:

1
2
3
4
5
6
7
8
9
10

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>

</body>
</html>

And now we should have the desired project structure. So how does that Jasmine testing framework works, anyways?

Crash Course into Jasmine

Let’s take a look at the example test file to get the gist of how Jasmine works:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

// spec/PlayerSpec.js

describe("Player", function() {
  var player;
  var song;

  beforeEach(function() {
    player = new Player();
    song = new Song();
  });

  it("should be able to play a Song", function() {
    player.play(song);
    expect(player.currentlyPlayingSong).toEqual(song);

    //demonstrates use of custom matcher
    expect(player).toBePlaying(song);
  });

  describe("when song has been paused", function() {
    beforeEach(function() {
      player.play(song);
      player.pause();
    });

    it("should indicate that the song is currently paused", function() {
      expect(player.isPlaying).toBeFalsy();

      // demonstrates use of 'not' with a custom matcher
      expect(player).not.toBePlaying(song);
    });

    it("should be possible to resume", function() {
      player.resume();
      expect(player.isPlaying).toBeTruthy();
      expect(player.currentlyPlayingSong).toEqual(song);
    });
  });

  // demonstrates use of spies to intercept and test method calls
  it("tells the current song if the user has made it a favorite", function() {
    spyOn(song, 'persistFavoriteStatus');

    player.play(song);
    player.makeFavorite();

    expect(song.persistFavoriteStatus).toHaveBeenCalledWith(true);
  });

  //demonstrates use of expected exceptions
  describe("#resume", function() {
    it("should throw an exception if song is already playing", function() {
      player.play(song);

      expect(function() {
        player.resume();
      }).toThrowError("song is already playing");
    });
  });
});

First important concept here is the describe("...", function () { ... }). describe function is used to describe a certain concept or a certain context. For example, describe("Player", ...) means that we are going to define tests for Player class or some other Player concept. Also, describes can be nested to indicate that we are describing some specific context (describe("when a song has been paused", ...)) or sub-concept of current concept, such as the method of currently described class (describe("#resume", ...)). That is a good example, of what the unit test suite might be describing. In the case of End-to-End tests we would like to describe a full feature, so describe("Login Feature", ...) is a good bet. The second argument for the describe is the function that will contain all tests and sub-describes for the described concept. This function is the capturing closure, so defining variables and functions on the outer-level describe will make them available on the inner-level describes and the tests themselves.

Second important concept here is the it("...", function () { ... }). it function is used to create a test for the currently described concept, context or sub-concept. The first argument is the description of what it does, where it is the described concept. For example, given we describe a music player and our context is when the volume is at max, then we might write the test it("is deafening", ...). In the case of End-to-End tests we are describing a feature, so it will refer to our application, or application’s user interface, for example: it("shows user's nickname", ...). The second argument to the it is the function with the test itself. Here we will setup the stage for the test, call our main code and verify that everything happened as we expect.

Finally, the third important concept is the expect(...).to.... That is Jasmine’s form of assertion. That is where we verify that our code worked as we expect it to. As an argument to expect we provide an actual value. The actual value is something that our code has returned as a result of the function or method execution or something that we have read from the UI using UI manipulation code, or something that we have read from some 3rd party service, such as our back-end server, 3rd-party API or database. Essentially, this is the value that we are verifying to be correct. The second part is the Jasmine matcher - the method defined on the object, that is returned from expect(value) call, that allows us to define what we want to assert about that value. The most used one is toEqual(...), which asserts that the value was equal to some expected value.

These three concepts should be enough to start writing tests. Don’t worry about everything else that you see in this example file from standalone Jasmine distribution. We will discover some of these concepts as we go. Now, let’s remove src/Player.js, src/Song.js, spec/PlayerSpec.js and spec/SpecHelper.js, and run our test suite - it is enough to reload the page to re-run our test suite. Test run should report that No specs found:

To get the gist of how describe("...", function () { ... }), it("...", function () { ... }) and expect(...).toEqual(...) works, let’s write our first failing test. Also, that will let us see if the testing framework is configured correctly and is capable of showing us the test failure. Let’s create a new file called spec/JasmineWorksSpec.js:

1
2
3
4
5
6
7

// spec/JasmineWorksSpec.js

describe("testing framework", function () {
  it("works", function () {
    expect(2 + 2).toEqual(5);
  });
});

And we need to add this test file to the SpecRunner.html:

1
2
3
4

<!-- include source files here... -->

<!-- include spec files here... -->
<script src="spec/JasmineWorksSpec.js"></script>

And if we run our test suite, we should see a failure:

1
2

testing framework works
  Expected 4 to equal 5.

And we ought to make it pass by fixing our incorrect assertion: expect(2 + 2).toEqual(4);. And if we run the test suite again, by reloading the page in the browser, all the test should pass.

Writing our First Simple Tests

Now we can write some real tests to practice usage of describe, it and expect(...).toEqual: let’s create ArithmeticsSpec.js and write some tests for behavior of add function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// spec/ArithmeticsSpec.js

describe("Arithmetics", function () {

  describe("#add(a, b)", function () {
    it("calculates the sum of two numbers", function () {
      // ARRANGE
      var a = 3;
      var b = 4;
      var expected = 7;

      // ACT
      var actual = Arithmetics.add(a, b);

      // ASSERT
      expect(actual).toEqual(expected);
    });
  });

});

Don’t forget to add the <script src="spec/ArithmeticsSpec.js"></script> to the SpecRunner.html. This test will fail first because Arithmetics module is not defined. We will define it as an empty object. Next failure is because Arithmetics.add is not a function - it is undefined. We will define that function with two arguments inside of the Arithmetics object. Finally, the test will fail, because we expect the result to be seven, but it was undefined. We will make the simplest thing we can do to pass the failing test - return seven. That will make the test pass. The code will be in src/Arithmetics.js, which we include in our SpecRunner.html, and will look like that:

1
2
3
4
5
6
7

// src/Arithmetics.js

var Arithmetics = {
  add: function (a, b) {
    return 7;
  }
};

That, of course, is not correct implementation, so we need another test to drive out the proper implementation - test with different inputs and a different result. To make it pass we will have to use a + b:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// spec/ArithmeticsSpec.js
describe("Arithmetics", function () {

  describe("#add(a, b)", function () {
    it("calculates the sum of two numbers", function () { ... });

    it("calculates the sum of two other numbers", function () {
      // ARRANGE
      var a = 73;
      var b = 89;
      var expected = 162;

      // ACT
      var actual = Arithmetics.add(a, b);

      // ASSERT
      expect(actual).toEqual(expected);
    });
  });

});

// src/Arithmetics.js
var Arithmetics = {
  add: function (a, b) {
    return a + b;
  }
};

Three “A”s: Arrange, Act, and Assert

Have you noticed three comments that I have left in the example tests’ code: ARRANGE, ACT and ASSERT? These are three “A”s of writing a good test. Arrange is the part of the test, where we set up the stage: prepare input data, create objects, load resources, change the state of the system - it is the part where we create the context for our test. Act is the part of the test, where we call our system under the test. In the Arithmetics example it was a function Arithmetics.add(a, b). The system under the test can return some useful value or change its state. To verify that either is correct we, finally, use Assert section of our test - part of the test where we verify the outcome of the call to the system under the test.

The sections ARRANGE, ACT and ASSERT are spelled out in the comments only for the reader’s convenience - usually, real projects don’t have such comments. It is worth noting that for learning and practicing purposes it is a good idea to name these sections explicitly in our tests - this develops a habit of recognizing which part of the test should belong to which section. Also, the formula Act -> Arrange -> Assert makes it easier to come up with the test when we lack deep experience in testing, or with the particular testing framework, or an environment.

Going a bit back to our user story scenarios: have you noticed the connection between “Arrange, Act and Assert” and “Given-When-Then”? Arrange part of the test corresponds to the Given part of the scenario, Act part of the test corresponds to the When part of the scenario, and Assert part of the test corresponds to the Then part of the scenario. Let’s see it on of our previous example scenarios:

Exercises

1. Write tests and implement functions on Arithmetics module: subtract, multiply and divide.
2. Inline Arrange, Act and Assert in a one-liner. Can you still recognize implicit Arrange, Act and Assert sections in that one line? Is it more or less readable? Is there a middle ground between two versions? Why would you choose one or the other?
3. Classify parts of the free-form story for the user log in from before as Arrange, Act, and Assert. Was it easier, than classifying formal Given-When-Then form? Was it harder? Or maybe the same? How would it be if you never saw Given-When-Then version of that free-form story?

Writing our First End-to-End Test

Now that we know approximately, how to arrange the steps of our scenario into the test, let’s give it a shot. We will start by creating a new test file for our login feature called LoginFeatureSpec.js. Don’t forget to put an appropriate script tag in the SpecRunner.html. We will start by writing the skeleton of our test suite: describe and it inside of it. Next, we will put scenario steps as comments to our test, and we will split them into three sections: Arrange, Act, and Assert. It will look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// spec/LoginFeatureSpec.js

describe("Login Feature", function () {

  it("allows to login with correct credentials", function () {
    // ARRANGE
    // Given User with email ‘john@example.org’ and password ‘welcome’ exists
    // And I am at the login page

    // ACT
    // When I enter ‘john@example.org’ in the email field
    // And I enter ‘welcome’ in the password field
    // And I click on the submit button

    // ASSERT
    // Then I see the profile page
    // And I see my name as the title of the profile page
  });

});

Next step would be to change the first Given comment to the function call. We should give a good readable name to that function. One straightforward option would be givenUserExists(email, password). Another good option is addUser({email: email, password: password}). While they are not that different, I prefer addUser for its higher conceptual flexibility - we will likely need that function in some different scenario step in the future. While I prefer that, we should not do that yet, because we might never need the function like that, and givenUserExists will do us more good right now since it resembles the scenario step so much. When we need this flexibility, we’ll perform a refactoring. So for now, let’s create an empty function with that name in a new file spec/FeatureSteps.js and load this file from our SpecRunner.html.

This empty function, on its own, doesn’t do us much good because all our tests will pass. If we continue replacing our steps in comments with such functions, we will end up with one big failure at the Assert section, and we will have to write a lot of code at once to fix that. To drive ourselves to implement the function givenUserExists properly right now, we should write an assertion right after the call. This assertion is not part of Assert section - it is a part of test-driving the functionality of our feature steps. A good assertion here will be to ask our user storage mechanism if such user exists right after we created that user. Also, it would be a good idea to check that user does not exist, before we created it. Also, we will extract variables email and password because we have to repeat them all over the place already. Let’s see how it will look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// spec/LoginFeatureSpec.js

describe("Login Feature", function () {

  it("allows to login with correct credentials", function () {
    // ARRANGE

    // Given User with email ‘john@example.org’ and password ‘welcome’ exists
    var email = "john@example.org";
    var password = "welcome";
    expect(Users.exists(email, password)).toEqual(false);
    givenUserExists(email, password);
    expect(Users.exists(email, password)).toEqual(true);

    // ...
  });

});

When we run our tests, the breadcrumbs of test failures will drive us to create this basic functionality. First, we will create Users.js with empty Users module and import it from SpecRunner.html. Then, next failure will drive us to add method exists(email, password) on Users module, that will always return false. Next, make function givenUserExists(email, password) call Users.add(email, password), which in turn will make us create a function Users.add(email, password), that will store email-password pair to the list of users in the memory. And, finally, make Users.exists to search for the email-password pair in that in-memory list. And finally, our test will pass. Let’s take a look at how these steps will look in our code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

// => Error: Users is undefined
// in src/Users.js:
var Users = {};

// => Error: Users.exists is not a function
// in src/Users.js:
var Users = {
  exists: function (email, password) {}
};

// => Error: expected undefined to equal false
// in src/Users.js:
var Users = {
  exists: function (email, password) {
    return false;
  }
};

// => Error: expected false to equal true
// in the (second assertion)
// in spec/FeatureSteps.js:
function givenUserExists(email, password) {
  Users.add(email, password);
}

// => Error: Users.add is not a function
// in src/Users.js:
var Users = {
  users: [],

  exists: function (email, password) { ... },

  add: function (email, password) {
    this.users.push({email: email, password: password});
  }
}

// this still fails with:
// => Error: expected false to equal true
// because we need to implement Users.exists "properly"
// in src/Users.js:
var Users = {
  users: [],

  exists: function (email, password) {
    return this.users.length > 0;
  },

  add: function (email, password) { ... }
}

// => All tests PASS

It is funny, how simple Users.exists(email, password) function is. It verifies that we have at least one user. While this is not a correct code, this is good enough for our current test. As we know that this code is not entirely correct, we need to remember to write the test(s) to prove it incorrect, so that we can make it proper with confidence. Since we want first to finish the current test, we should add a to-do list item to write such test. We have two edge cases here that will not work with our implementation: when we have only one user in the system and the credentials we provided do not match and when we have multiple users in the system, and we provide correct credentials for the second one:

1
2
3
4
5
6
7
8
9
10
11

xdescribe("when user has different credentials", function () {
  it("does not allow to login with wrong credentials", function () {

  });
});

xdescribe("when there are more than one user", function () {
  it("allows to login with correct credentials", function () {

  });
});

Have you noticed xdescribe? It is a different form of the describe, that allows us to mark the whole context as pending. It won’t run the tests inside, and it will mark them as pending in the test run report. That is the ultimate way to maintain a Test-Driven TODO List. As we test-drive our code, we will find more of these. In the report they look like this:

Let’s finish continue implementing our steps. The comment And I am at the login page transparently becomes a function givenIAmAtTheLoginPage(). As we already have seen, it doesn’t do us any good just to replace the comment with a function call that does nothing - so we should surround it with proper assertions. We know that login page should have some text input for email and another password field for password, and we will need a button to confirm user’s intent to log in. Also, because we are developing a single page application, we would need some container for the currently active page. Let’s say we need these things:

• Initially, we will have only one container with id="page" and no content. We probably ought to define it in our HTML file.
• When we render our login page, we should have:
  • email text input field with id="email",
  • password input field with id="password",
  • and button with id="do_login".

Now that we have spelt this out, it is fairly straightforward to write assertions surrounding the givenIAmAtTheLoginPage() call:

1
2
3
4
5

// Initially, we will have only one container with `id="page"`
var container = document.querySelector("#page");
expect(container).not.toEqual(null);
// and no content
expect(container.innerHTML).toEqual("");

That fails because we don’t have such element in our HTML. We need to create it both in our SpecRunner.html. Also, now it will be important to move all our <script> tags from the <head> to the <body> below the container that we have just created. SpecRunner.html should look this way after that:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Jasmine Spec Runner v2.5.2</title>

    <link rel="shortcut icon" type="image/png" href="lib/jasmine-2.5.2/jasmine_favicon.png">
    <link rel="stylesheet" href="lib/jasmine-2.5.2/jasmine.css">
</head>

<body>

    <div id="page"></div>

    <script src="lib/jasmine-2.5.2/jasmine.js"></script>
    <script src="lib/jasmine-2.5.2/jasmine-html.js"></script>
    <script src="lib/jasmine-2.5.2/boot.js"></script>

    <!-- include source files here... -->
    <script src="src/Arithmetics.js"></script>
    <script src="src/Users.js"></script>

    <!-- include spec files here... -->
    <script src="spec/JasmineWorksSpec.js"></script>
    <script src="spec/ArithmeticsSpec.js"></script>
    <script src="spec/FeatureSteps.js"></script>
    <script src="spec/LoginFeatureSpec.js"></script>

</body>
</html>

Now, our next failure is that givenIAmAtTheLoginPage() function is not defined. We can define it as empty function in our spec/FeatureSteps.js file for now. This will turn our tests green again. We still haven’t made our assertions about the state of the UI after the call to givenIAmAtTheLoginPage - let’s do this now:

1
2
3

var emailInput = container.querySelector("#email");
expect(emailInput.tagName).toEqual("input");
expect(emailInput.type).toEqual("email");

That fails with the error Cannot read property tagName of null, which means that we don’t have #email element inside of the #page container. Simplest thing to do would be to add that element to the #page container in our SpecRunner.html. And it won’t work! Because we have an assertion that verifies, that before calling to the givenIAmAtTheLoginPage we do not have anything in the #page container. Now we have to do something useful in the function givenIAmAtTheLoginPage. For example, we can call LoginPage.render(). Which does not exist yet and we will need to create it in the file src/LoginPage.js and load it from our SpecRunner.html. To fix current failure we will need to create a #email element there and append it to our #page container:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// spec/FeatureSteps.js
function givenIAmAtTheLoginPage() {
  LoginPage.render();
}

// src/LoginPage.js
var LoginPage = {
  render: function () {
    var emailInput = document.createElement("div");
    emailInput.id = "email";

    var container = document.querySelector("#page");
    container.appendChild(emailInput);
  }
};

That makes the current test failure go away, but we have two more: Expected 'DIV' to equal 'input'. and Expected undefined to equal 'email'.. To make these pass, we would need to change document.createElement(...) call to use input tag name and also we will need to set the input type to email. And as we see, the tag name stored in emailInput.tagName is all-caps, so we will have to fix our assertion also to expect that:

1
2
3
4
5
6
7
8
9

// first we'll fix the assertion:
// in spec/LoginFeatureSpec.js
expect(emailInput.tagName).toEqual("INPUT");

// and then we will fix the emailInput creation:
// in src/LoginPage.js
var emailInput = document.createElement("input");
emailInput.id = "email";
emailInput.type = "email";

And if we run our tests, they all pass. Great! We should now do the same for our password input field and the login button:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// in spec/LoginFeatureSpec.js
var passwordInput = container.querySelector("#password");
expect(passwordInput.tagName).toEqual("INPUT");
expect(passwordInput.type).toEqual("password");
var loginButton = container.querySelector("#do_login");
expect(loginButton.tagName).toEqual("BUTTON");
expect(loginButton.textContent).toEqual("Login");

// in src/LoginPage.js
var passwordInput = document.createElement("input");
passwordInput.id = "password";
passwordInput.type = "password";
container.appendChild(passwordInput);

var loginButton = document.createElement("button");
loginButton.id = "do_login";
loginButton.textContent = "Login";
container.appendChild(loginButton);

And all tests pass again. Let’s take another look at how our test looks like. It is quite complicated, and it has so much stuff, that is hugely detailed and precise, that it is not possible to see a user story scenario there anymore. One possible solution to that problem is to push the assertions that are related to the feature scenario step to the respective step functions. Now it looks much better. We should use the same concept for all our further steps. After refactoring test code looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

// in spec/LoginFeatureSpec.js
it("allows to login with correct credentials", function () {
  // ARRANGE
  var email = "john@example.org";
  var password = "welcome";
  givenUserExists(email, password);
  givenIAmAtTheLoginPage();

  // ACT
  // When I enter ‘john@example.org’ in the email field
  // And I enter ‘welcome’ in the password field
  // And I click on the submit button

  // ASSERT
  // Then I see the profile page
  // And I see my name as the title of the profile page
});

// in spec/FeatureSteps.js
function givenUserExists(email, password) {
    expect(Users.exists(email, password)).toEqual(false);

    Users.add(email, password);

    expect(Users.exists(email, password)).toEqual(true);
}

function givenIAmAtTheLoginPage() {
    var container = document.querySelector("#page");
    expect(container).not.toEqual(null);
    expect(container.innerHTML).toEqual("");

    LoginPage.render();

    var emailInput = container.querySelector("#email");
    expect(emailInput.tagName).toEqual("INPUT");
    expect(emailInput.type).toEqual("email");

    var passwordInput = container.querySelector("#password");
    expect(passwordInput.tagName).toEqual("INPUT");
    expect(passwordInput.type).toEqual("password");

    var loginButton = container.querySelector("#do_login");
    expect(loginButton.tagName).toEqual("BUTTON");
    expect(loginButton.textContent).toEqual("Login");
}

Now, let’s follow the same pattern for our Act section. First, we will deal with When I enter ‘john@example.org’ in the email field. This seems to be a call to a function whenIEnterInTheField("#email", email) - we will implement it using Javascript’s APIs. We will do the same for the And I enter ‘welcome’ in the password field, which will use the same function whenIEnterInTheField("#password", password). Finally, we will implement whenIClickOn("#do_login") as a replacement for the comment And I click on the submit button. We will also sprinkle assertions inside of the steps to make sure that we are using the Javascript APIs correctly. The code will look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// in spec/LoginFeatureSpec.js
it("allows to login with correct credentials", function () {
    // ARRANGE
    var email = "john@example.org";
    var password = "welcome";
    givenUserExists(email, password);
    givenIAmAtTheLoginPage();

    // ACT
    whenIEnterInTheField("#email", email);
    whenIEnterInTheField("#password", password);
    whenIClickOn("#do_login");

    // ASSERT
    // Then I see the profile page
    // And I see my name as the title of the profile page
});

// in spec/FeatureSteps.js
function whenIEnterInTheField(selector, value) {
    var element = document.querySelector(selector);
    expect(element).not.toEqual(null);
    expect(element.value).toEqual("");

    element.value = value;

    var elementAfterChange = document.querySelector(selector);
    expect(element.value).toEqual(value);
}

function whenIClickOn(selector) {
    var element = document.querySelector(selector);
    expect(element).not.toEqual(null);

    element.click();
}