The code for the chapter can be found online at https://github.com/PacktPublishing/Svelte-with-Test-Driven-Development/tree/main/Chapter01/Start.

You will need to have a recent version of Node.js installed. See https://nodejs.org for instructions on how to install and update Node.js for your platform.

In this section, you’ll use the default method for creating a new SvelteKit project, which uses the npm create command. (For reference, you can also check the official documentation at https://kit.svelte.dev/docs/creating-a-project.)

The project we are building is called Birthdays and the npm package name is birthdays. It will be introduced properly in Chapter 2, Introducing the Red-Green-Refactor Workflow.

SvelteKit 1.0

These instructions were valid at the time of writing, for SvelteKit 1.0. It’s likely things will improve in time, so you may find some of the later instructions will become unnecessary or may no longer work. Check the book’s GitHub repository for the most up-to-date instructions.

For now, we’ll concentrate on the mechanics of building a new project:

1. Start by opening a Terminal window in your usual work location (for me, this is ~/work on my Mac). Then type the following commands:

   mkdir birthdays
   cd birthdays
   npm create svelte@latest

If this is the first Svelte project you’ve created, you’ll be presented with the following message from npm:

Need to install the following packages:
  create-svelte@2.1.0
Ok to proceed? (y)

2. Answer y to that. You’ll see a bunch more questions, which we’ll go through individually:

   create-svelte version 2.1.0
   Welcome to SvelteKit!
   ? Where should we create your project?
     (leave blank to use current directory) ›

3. Since you’re already in the birthdays directory, just leave this blank, and hit Enter. Next, you’ll be asked about which app template you’d like to use:

   ? Which Svelte app template? › - Use arrow-keys. Return to submit.
       SvelteKit demo app
   ❯   Skeleton project - Barebones scaffolding for your new SvelteKit app
       Library skeleton project

4. Choose Skeleton project. Next, you’ll be asked about TypeScript:

   ? Add type checking with TypeScript? › - Use arrow-keys. Return to submit.
       Yes, using JavaScript with JSDoc comments
       Yes, using TypeScript syntax
   ❯   No

5. For this question, I’ve chosen No. That’s because this book is about testing techniques, not typing techniques. That’s not to say that this book doesn’t apply to TypeScript projects – it most certainly does – just that typing is not the topic at hand.

If you want to use TypeScript

If you’re a seasoned TypeScript developer, please feel free to choose that option instead. The code samples in the book won’t need too much modification except for the additional type definitions, which you’ll need to provide.

6. Finally, you’ll be asked about extra package dependencies:

   ? Add ESLint for code linting? › No / Yes
   ? Add Prettier for code formatting? › No / Yes
   ? Add Playwright for browser testing? › No / Yes
       ✔ Add Vitest for unit testing? … No / Yes

7. Choose Yes as the answer to all these questions. Although we won’t mention ESLint in this book, it’s always good to have. And we’ll need Playwright and Vitest.

You’ll then see a summary of all your choices, followed by a Next steps list:

Your project is ready!
✔ ESLint
  https://github.com/sveltejs/eslint-plugin-svelte3
✔ Prettier
  https://prettier.io/docs/en/options.html
  https://github.com/sveltejs/prettier-plugin-svelte#options
✔ Playwright
  https://playwright.dev
✔ Vitest
  https://vitest.dev
Install community-maintained integrations:
  https://github.com/svelte-add/svelte-adders
Next steps:
  1: npm install (or pnpm install, etc)
  2: git init && git add -A && git commit -m "Initial commit" (optional)
  3: npm run dev -- --open

We’ll perform these next steps but before we do that, we’ll run some extra verification steps. It’s always good to check your work.

Type npm install into the Terminal and confirm that everything is installed correctly. Then, go ahead and commit your changes. (If you’ve forked the GitHub repository, you won’t need to use the git init command.)

Committing early and often

It’s a good idea to be checking in your work very often. While you’re learning the TDD approach to testing, it can be helpful to check in after every single test. This might seem like a lot but it will help you backtrack in case you get stuck.

Then, run npm run dev – –open. It should open your web browser and show you a "Welcome to SvelteKit" message.

You can then close the browser and hit Ctrl + C in the Terminal to stop the web server.

Next, let’s verify the Playwright and Vitest dependencies.

Installing and running Playwright

Although we won’t use Playwright in this chapter, it’s a good idea to get it installed and verify that it’s working.

Start by running npm test at the command line:

work/birthdays % npm test
> birthdays@0.0.1 test
> playwright test
Running 1 test using 1 worker
[WebServer]
[WebServer]
[WebServer] Generated an empty chunk: "hooks".
[WebServer]
  ✘  1 test.js:3:1 › index page has expected h1 (7ms)
  1) test.js:3:1 › index page has expected h1 =============================================
    browserType.launch: Executable doesn't exist at /Users/daniel/Library/Caches/ms-playwright/chromium-1041/chrome-mac/Chromium.app/Contents/MacOS/Chromium
    ...
  1 failed
    test.js:3:1 › index page has expected h1 ============================================

If you’ve never installed Playwright before, you’ll see a message like the preceding one.

Playwright has its own environment setup to do, such as installing Chromium onto your machine. You can install it with the following command:

npx playwright install

Then, trying npm test again should give you the following output, showing that the one example test that’s included is passing:

> birthdays@0.0.1 test
> playwright test
Running 1 test using 1 worker
[WebServer]
[WebServer]
[WebServer] Generated an empty chunk: "hooks".
[WebServer]
  ✓  1 test.js:3:1 › index page has expected h1 (307ms)
  1 passed (4s)

This test, index page has expected h1, is a test for the "Welcome to SvelteKit" message you saw earlier when you launched the application in the browser.

Running Vitest

Running npm run test:unit is the default way to run Vitest tests. Try it now:

work/birthdays % npm run test:unit
> birthdays@0.0.1 test:unit
> vitest
 DEV  v0.25.8 /Users/daniel/work/birthdays
 ✓ src/index.test.js (1)
 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  15:56:18
   Duration  737ms (transform 321ms, setup 0ms, collect 16ms, tests 2ms)
 PASS  Waiting for file changes...
       press h to show help, press q to quit

This automatically puts you in watch mode, which means any changes to the filesystem will cause tests to re-run. Press q to quit this mode. I personally don’t use watch mode and we won’t be using it in this book. See the Creating a shell alias section for a little discussion on why this is.

In the next section, we’ll make the ergonomics of the project a little easier for us.

In this section, we’ll take some configuration actions that will make our test-driven lives much simpler.

Choosing your editor

Let’s start with your choice of code editor. More than likely, this means a choice between an IDE, such as Visual Studio Code, or a plain text editor, such as Vim or Emacs.

IDEs tend to have lots of bells and whistles and one of those is the built-in test runner, which runs tests for you and integrates test output into the editor itself. On the other hand, plain text editors will require you to have a separate Terminal window for you to enter test commands directly, as you did in the previous section.

Figure 1.1 shows how my own setup looks, using Vim and tmux to split windows. The top half of the screen is where I edit my source files, and when I’m ready to run tests, I can switch to the bottom half and enter the test command.

Figure 1.1 – Using tmux and Vim

Figure 1.2 shows the same project in Visual Studio Code with the Vitest extension installed. Notice the test runner has a bunch of neat features, such as the ability to filter the test output, and green ticks next to the line numbers of passing tests.

Figure 1.2 – Using Visual Studio Code to run tests

I think there is a lot to learn from using a plain editor and Terminal setup, but if you don’t feel comfortable with that, then it’s best to stick to your favorite IDE for now.

The one thing you want to make sure of is that it’s easy and quick to run tests. So, if you’re writing a new test, you want to immediately run it and see it fail. And if you’re making a test pass or refactoring tests, make sure you can quickly re-run tests to check your progress.

Creating a shell alias

If you’re choosing to use the Terminal to run tests, then you will almost certainly want to set up an alias to make it simpler to run Vitest unit tests. You’ll recall that there are two commands that you use for running tests: npm test for Playwright tests and the npm run test:unit command for Vitest unit tests.

The style of testing shown in this book follows the classic test pyramid approach to testing, which states that we should have lots of little unit tests (in Vitest) and far fewer system tests (in Playwright).

So, given that we’ll be working much more frequently with Vitest, doesn’t it make sense to have the shorter test command be the one that runs unit tests?

The solution that I use is a shell alias, v, that invokes Vitest. If you wanted to use the standard watch mode, you’d set up the shell alias to run this command:

npx vitest

However, because I don’t want to use watch mode, I set it up to use this command:

npx vitest run

I‘d suggest you use this version, at least while you read through this book. I find that watch mode tends to break silently, especially when you’re in the first stages of setting up a project. To avoid confusion, better to just invoke the test command when you’re ready.

On my Mac, my default shell is zsh, which configures its shell aliases in the ~/.zshrc file. You can add that alias to the file using the following commands:

echo 'alias v="npx vitest run"' >> ~/.zshrc
source ~/.zshrc

Now, you can simply type the v command to run your Vitest unit tests. You can also use this to run a single test file, like this:

v src/index.tests.js

This is a handy way to run just a small part of your test suite.

Changing the test runner to report each test name

Recall that when we ran our Vitest unit tests, the test report told us the filename of the test suite that was run, together with some summary information:

 DEV  v0.25.8 /Users/daniel/work/birthdays
 ✓ src/index.test.js (1)
 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  15:56:18
   Duration  737ms (transform 321ms, setup 0ms, collect 16ms, tests 2ms)

It turns out this isn’t enough – we want to see test names too, just like how the Playwright test told us the description of the test that was passing.

Open the vite.config.js file and add a new reporter property that is set to verbose, as shown in the following code block:

 const config = {
   plugins: [sveltekit()],
   test: {
     ...,
     reporter: 'verbose'
   }
 };

Be careful

If you had left your test runner running in watch mode, you’ll need to restart it at this point, and at any other point in which you modify the configuration.

Now, running tests at the command line using the v command will give this:

 RUN  v0.25.8 /Users/daniel/work/birthdays
 ✓ src/index.test.js (1)
   ✓ sum test (1)
     ✓ adds 1 + 2 to equal 3
 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  11:02:05
   Duration  905ms (transform 320ms, setup 1ms, collect 16ms, tests 2ms)

Much better!

Watching the test fail

We’re almost done with configuring Vitest, but before continuing, let’s check that the test actually tests what we want it to test. This is an important concept with TDD: if you’ve never seen a test fail, how do you know it tests the right thing?

Open src/index.test.js and take a look:

import { describe, it, expect } from 'vitest';
describe('sum test', () => {
  it('adds 1 + 2 to equal 3', () => {
    expect(1 + 2).toBe(3);
  });
});

Make a change to the expect statement, like the one shown here:

expect(2 + 2).toBe(3);

Now if you run the test, you should see a failure:

❯ src/index.test.js:5:17
      3| describe('sum test', () => {
      4|  it('adds 1 + 2 to equal 3', () => {
      5|   expect(2 + 2).toBe(3);
       |                 ^
      6|  });
      7| });
  - Expected   "3"
  + Received   "4"

Brilliant – our test runner seems to be in working order. You can go ahead and undo the change to the test, and watch it go green again. That’s it for the basic editor configuration.

Test file location – src or test?

In many other programming environments, test files are kept apart from application source files. A separate directory named something like tests or specs is used to house all executable test scripts.

There can be a couple of advantages to that. First, it can avoid packaging tests with application code when it comes to building deployable units. However, Svelte (and JavaScript in general) doesn’t suffer from this problem because only modules referenced by the application entry point will be bundled.

Second, having a separate directory avoids the mindset of one test file per module. Not all modules need unit tests: if a unit exists as a part of a larger unit, we’ll often just write tests for the top-level unit and those tests will also provide coverage for the lower-level unit. Conversely, sometimes it’s helpful to have two (or more!) test files for a single module.

That’s especially true when using component mocks that wipe out a component mock for an entire module. You might want a test file that mocks a component, and another test file where the component isn’t mocked. We’ll look at component mocks in Chapter 12, Using Component Mocks to Clarify Tests.

The current SvelteKit approach is to keep Vitest test files housed within the src directory. Partly, this is to avoid confusion with Playwright tests, which do live in a separate directory, named tests. (We’ll see Playwright tests starting from Chapter 3, Loading Data into a Route).

This book continues with that style, but I would encourage you to explore and adopt whichever style you feel most comfortable with.

In the next section, we’ll add support for the kinds of tests we’ll be writing throughout the book.

A Svelte component test is one that, perhaps unsurprisingly, tests a Svelte component. For this, we need access to a Document Object Model (DOM), which isn’t part of the standard Node.js environment. We’ll also need some additional packages for writing unit test expectations against the DOM.

Installing jsdom and testing library helpers

At the Terminal, run the following command to install the jsdom package and @testing-library packages that we’ll use in our unit tests:

npm install --save-dev \
  jsdom \
  @testing-library/svelte \
  @testing-library/jest-dom \
  @testing-library/user-event

If you’re using TypeScript, at this point, you may wish to add packages containing type definitions.

Next, create a new file named src/vitest/registerMatchers.js with the following content. It ensures that the matchers we’ll be using are available for use via the expect function:

import matchers from '@testing-library/jest-dom/matchers';
import { expect } from 'vitest';
expect.extend(matchers);

Then, update vite.config.js to add a new environment property, which installs jsdom correctly, and also a setupFiles property, which ensures the file defined previously is loaded (and invoked) just before the test suites are loaded:

 const config = {
   plugins: [sveltekit()],
   test: {
     ...,
     reporter: 'verbose',
     environment: 'jsdom',
     setupFiles: ['./src/vitest/registerMatchers.js']
   }
 };

That’s it for the basic setup. Now let’s test it out.

Writing a test for the DOM

Open the src/index.test.js file and add the following test definition, inside the describe block. This test makes use of the document object that is created for us by the jsdom package, and the toHaveTextContent matcher that is provided by the @testing-library/jest-dom package:

it('renders hello into the document', () => {
  document.body.innerHTML =
    '<h1>Hello, world!</h1>';
  expect(document.body).toHaveTextContent(
    'Hello, world!'
  );
});

Now, if you run the test, you should see it pass. But, just as you did with the first test, it’s important to confirm the test actually tests what it says it does. Change the test by commenting out or deleting the first line of the test, and then re-running the test runner.

You should see an output as follows:

 FAIL  src/index.test.js > sum test > renders hello into the document
Error: expect(element).toHaveTextContent()
Expected element to have text content:
  Hello, world!
Received:
 ❯ src/index.test.js:9:25
      7|
      8|  it('renders hello into the document', () => {
      9|   expect(document.body).toHaveTextContent(
       |                         ^
     10|    'Hello, world!'
     11|   );

That proves the test is working. You can go ahead and undo the breaking change you made.

Writing a first Svelte component test

Next, let’s write an actual Svelte component and test that out. Create a new file named src/Hello.svelte with the following content:

<script>
  export let name;
</script>
<p>Hello, {name}!</p>

Then, go back to the src/index.test.js file and refactor your test to use this new component. To do that, replace the call to document.outerHTML with a call to the render function, like this:

it('renders hello into the document', () => {
  render(Hello, { name: 'world' });
  expect(document.body).toHaveTextContent(
    'Hello, world!'
  );
});

This render function comes from the @testing-library/svelte package. Import that now, along with an import for the Hello component, placed at the top of the file:

import { render } from '@testing-library/svelte';
import Hello from './Hello.svelte';

Check that the test still passes with the refactor.

Then, add this third test, which verifies that the name prop in the component is being used to verify the output:

it('renders hello, svelte', () => {
  render(Hello, { name: 'Svelte' });
  expect(document.body).toHaveTextContent(
    'Hello, Svelte!'
  );
});

Run the test and make sure it passes.

Now, go ahead and comment out the render call in the last test. You might think that the test fails with an error saying nothing was rendered on-screen. But let’s see what happens:

Error: expect(element).toHaveTextContent()
Expected element to have text content:
  Hello, Svelte!
Received:
  Hello, world!

Hold on a second; is this what we expected? This test didn’t ever print out a Hello, world! message so why is the test expectation picking it up?

It turns out that our tests share the same document object, which is clearly not good for test independence. Imagine if the second test also expected to see Hello, world! rather than Hello, Svelte!. It would have passed by virtue of the first test running. We need to do something about this.

Ensuring the DOM is cleared after each test run

We want to make sure that every test gets its own clean version of the DOM. We can do this by using the cleanup function.

Create a new file named src/vitest/cleanupDom.js:

import { afterEach } from 'vitest';
import { cleanup } from '@testing-library/svelte';
afterEach(cleanup);

Then, insert that into the setupFiles property in vite.config.js:

const config = {
  ...,
  test: {
    ...,
    setupFiles: [
      './src/vitest/cleanupDom.js',
      './src/vitest/registerMatchers.js'
    ]
  }
};

Now, if you run your failing test again, you should see that the Hello, world! message no longer appears.

Before continuing, uncomment the render call and check your tests are back in an all-green state.

Restoring mocks automatically

There’s one final piece of configuration we need in vite.config.js. Add the restoreMocks property, as shown here:

const config = {
  ...,
  test: {
    ...,
    restoreMocks: true
  }
};

This is also important for test independence and will be important in Chapter 11, Replacing Behavior with a Side-By-Side Implementation, when we begin using the vi.fn function for building test doubles.

That covers all the configuration you need for the rest of the book. The next section touches briefly on some optional configurations you might want to consider.

In this section, we’ll look at configuring Prettier and setting up more appropriate tab widths on the Terminal. These settings mirror the print settings that are used in this book.

Configuring Prettier’s print width

Due to the constraint of the physical pages in this book, I have set the printWidth setting of Prettier to 54 characters, and all code samples are formatted with that setting.

I also think the default value, 100, is too high. I like short columns of text as I find them easier to share and read in all sorts of environments – such as on mobile devices, where it’s much easier to scroll vertically than it is horizontally.

Also, having extra vertical space comes in handy when you are pairing with other developers and you want to refer to particular line numbers (assuming you have line numbers turned on).

In .prettierrc, you can set the print width with the following addition:

{
  "printWidth": 54,
  ...
}

You might be more comfortable with something in the 60 to 80 range.

Reducing the tab width in the Terminal

The Svelte community has a preference for tabs over spaces because tabs are better for screen readers. Unfortunately, a lot of Terminals and shell programs are set up for a default tab width of eight characters, which is way too many for my liking.

Although every Terminal is different, the one solid piece of advice I have is to set git config to use less as its pager, with tab stops at positions 1, 3, 5, and 7:

git config --global core.pager 'less -x1,3,5,7'

This makes git diff and git show much more bearable, and these are two commands I use extremely frequently.

This chapter has taken a detailed look at the various parts of a base SvelteKit project, showing how Playwright and Vitest are added, together with the additional dependencies you’ll need to write Svelte component tests.

We’ve also looked at some of the ways you can set up your development environment to help you be productive.

You’re now ready to start exploring TDD practices, starting with the Red-Green-Refactor Cycle -> Workflow in the next chapter.