Debug end-to-end(e2e) tests in VSCode

While using TypeScript and Angular I also made the switch a while back to VSCode. I was previously using Eclipse. Eclipse is a great IDE, but I wanted to try something new and VSCode was gaining a lot of momentum at that time. A dedicated IDE sounds like a good idea and an IDE built on a browser engine sounds exciting, right?

Nowadays, development speed increased tremendously but this came with a lot of challenges. Maintain a high development speed and high quality is important, but not easy to achieve. Automated tests is definitely of great help. Unit tests are integrated in most major current web frameworks, like Angular. Unit tests are great for testing micro-functionality of classes and components, but not sufficient. End to end tests are the next steps and helps you test your applications as a whole, but also are more complicated to write.

We chose CucumberJS as an e2e testing framework for a few reasons. One is the fact that you can write tests in a more human friendly language. Please keep in mind that this does not mean that are easier to develop, but somehow easier to understand. For each Cucumber step you still need to write TypeScript code, but you can have a clear separation between the description of the whole test and how exactly this test translates into browser actions. So non-technical people can review tests and, to some extent, write new ones. These new tests will still have to be review by developers and, at least partially, backed by actual code, but they’re a good starting point. This way, Cucumber and similar BDD frameworks can offer a common ground between developers, testers, designers and business analysts.

On the other hand, as Cucumber is more human friendly and less organized and structured, these tests can become cluttered and harder to maintain. It will be so nice to have something like the GitHub Copilot to help you eliminate duplicates in the Cucumber steps. First to suggest existing steps to avoid duplication and later on to detect duplicates and suggest ways to eliminate them.

As I pointed out, every Cucumber test step must be backed by actual code which translate it into browser actions. As the underlying framework we chose Protractor. At that time it was the integrated Angular e2e framework and, even though Cypress is gaining a lot of momentum, I still see a lot of good value in Protractor too. Anyway those two frameworks are pretty similar and I guess you can easily migrate between the two.

What linked Cucumber and Protractor together was protractor-cucumber-framework which was fairly easy to setup, but this might make the subject of another post.
So we have Protractor, configured out-of-the-box in Angular, we have protractor-cucumber-framework which adds Cucumber as another layer on top of Protractor, where we can develop e2e behavior driven tests in a human friendly way.

Not about this I want to talk about :). What I want to tell you is how you can debug these tests in VSCode. Which as I realized was not easy thing to setup. But as soon as you made the setup, everything works like a breeze and you can easy debug e2e tests in VSCode. Debugging is an important part of the development process and not having access to a debugger makes your developer life much harder.

The exact configuration that you need in your .vscode/launch.json file is

{
	"name": "Debug e2e",
	"cwd": "${workspaceRoot}",
	"internalConsoleOptions": "openOnSessionStart",
	"preLaunchTask": "npm: e2e-compile",
	"type": "node",
	"request": "launch",
	"program": "${workspaceRoot}/node_modules/protractor/bin/protractor",
	"args": [
		"${workspaceRoot}/e2e/protractor.conf.js"
	],
	"env": {
		"DEBUG": "true"
	},
	"sourceMaps": true,
	"outFiles": [
		"${workspaceRoot}/dist/out-tsc/e2e/**/*.js"
	],
	// "skipFiles": [
	// 	"<node_internals>/**"
	// ],
}

There are a few interesting things. "type": "node" seems to be the only option working here. I also tried with pwa-node, but without any luck.
Another thing is that if you write your Protractor tests in TypeScript you usually register ts-node for transpiling. But because ts-node does this in memory you cannot use here, as there should be a link between the debugged source and the compiled output, So the workaround here is that if you want to debug protractor tests you must first compile them (this is what the preLaunchTask does) and then use the resulting .js files and associated source maps (this is what sourceMaps and outFiles configuration options are for). Furthermore, e2e-compile is a script in your project’s package.json

"e2e-compile": "tsc --project e2e/tsconfig.e2e.json"

There’s no big difference between your tsconfig and the one that you use in your project, main difference being the use of CommonJS module format.

{
	"extends": "../tsconfig.json",
	"compilerOptions": {
		"module": "CommonJS",
		"types": [
			"chai",
			"node"
		],
		"incremental": true
	}
}

With the above changes you’ll be able to debug Protractor tests in VSCode. Please keep in mind that, even with this setup, you cannot set breakpoints in Cucumber tests, but you can set breakpoints in the equivalent .ts files describing these test steps. Almost as good.