DEV Community: MaxKless

Nx Console gets Lit

MaxKless — Fri, 30 Jun 2023 07:46:51 +0000

Over the last few weeks, we rebuilt one of Nx Console’s most liked features from the ground up: The Generate UI. It looks better, loads faster, and preliminary research shows using it makes you happier, too ;)

You can use it today by installing the latest version of Nx Console for VSCode and JetBrains IDEs! 🎉🎉🎉

If you’re curious to learn more about the rewrite and the motivations behind it, this is the blog post for you! We’ll touch on these topics and more:

Why did we choose to rewrite?
What’s Lit and why did we use it over Angular?
How did the rewrite go and what Lit features were important for us?
What does the performance look like before and after?

If you prefer a video format, check out our Youtube video 👇

Background: Why Migrate from Angular to Lit?

A Short History of Nx Console

Let’s go back in time: Nx Console has been around for a while. It first launched in 2018 - then called Angular Console - as a standalone Electron app which let you run Angular schematics and builders from a graphical interface. Of course, it was built with Angular and looked something like this:

In 2019, it was ported to a VSCode extension with the now familiar UI and support for the standalone app was dropped.

In 2020, support for the entire Nx ecosystem was added, it was renamed to Nx Console and an amazing transformation began: Today, Nx Console is much more than just a single form - it tightly integrates Nx into your IDE, gives you the overview of your projects that you need and puts your task-running just a click away.

Rewriting in Lit

This evolution brought significant improvements to the usability of Nx Console and the value we could provide to developers, but not without presenting its own set of challenges. Inevitably, the codebase grew complex and convoluted over time - the context in which it ran changed, the scope of the product changed, yet the technology remained the same. Adding small features or fixing bugs became increasingly time consuming, and every PR compounded the problem.

The UI looked somewhat outdated and had been built with only VSCode in mind - which became painfully obvious when support for JetBrains IDEs was added. While the web-based nature of the Generate UI allowed us to reuse the code in the new environment, the design looked out of place.

In addition, we started questioning our usage of Angular. Angular is a great framework for building web apps, and in the original context of Angular Console, it made a lot of sense: A tool built by and for Angular engineers - of course it’s written in Angular. But things changed, and Angular started to feel overkill for what we needed. Angular has a huge number of features right out of the box. But for our simple form, we didn’t need routing, http requests or modules to organize our code. The amount of boilerplate and overhead Angular introduces is significant.

So, ultimately, we decided to pull the plug and rewrite the entire thing in Lit.

Lit is a lightweight framework built on top of web components and “adds just what you need to be happy and productive: reactivity, declarative templates and a handful of thoughtful features to reduce boilerplate and make your job easier” (taken from their docs). We had used it before to build the Nx Cloud view and were happy with the simple setup and great DX. So the decision to reuse it here was an easy one, since it allowed us to reuse code, build tooling and expertise. The rewrite also gave us the opportunity to improve the design for both supported IDEs and give the entire UI a clean, new coat of paint.

Before I dive deeper into specifics, let’s have a look at the general architecture of Nx Console first.

Nx Console Architectural Overview

Nx Console is composed of 3 core parts:

The nxls is a language server based on the Language Server Protocol (LSP) and acts as the “brain” of Nx Console. It analyzes your Nx workspace and provides information on it, including code completion and more.
The Generate UI is the form-based view for running Nx generators.
The platform-specific wrappers. These are written in Typescript and Kotlin and connect the rest of Nx Console to IDE-specific APIs. Having the other parts separate greatly reduces the amount of duplicated code we have to write in order to support multiple IDEs

This architecture’s modularity meant we could quickly switch out the Generate UI for a new version without significantly impacting the rest of the codebase - only the parts that actually render the UI and communicate with it had to be adjusted slightly. It also allowed us to ensure backward compatibility: the old generate UI is still available via a feature toggle in the settings.

If you want to dive deeper, there are many more resources on the architecture of Nx Console and how it’s built:

Migrating to Lit: Step by Step

To rebuild our UI, we first needed a new Lit app to work on. While there’s no native Nx plugin for Lit, generating the code we need was still very straightforward:

nx generate @nx/web:app --name generate-ui-v2

This generates an entire project for us, with a tsconfig.json , index.html , main.ts and a project.json , where our Nx-specific config lives.

I also installed a couple of dependencies:

The @nx/esbuild plugin because I like fast build times 🏎️
TailwindCSS because I don’t like writing CSS 🤫
@vscode/webview-ui-toolkit because it does all of the VSCode work for me 🤖

This is really where Nx shines, because it allows you to take these tools and quickly patch them together and build a pipeline that does exactly what you need. And it also allows you to think about your workspace visually. This is what this is what my task graph for building the Lit app ultimately looks like:

You can see three build steps:

generate-ui-v2:_build uses esbuild to bundle my Lit components written in Typescript and spits out a main.js file
generate-ui-v2:extract-dependencies copies the third party assets we need into the dist folder. Right now it’s just codicons .css and .ttf files.
generate-ui-v2:build finally runs tailwind over the bundled code. This could also be done with postCss or a custom esbuild plugin but running tailwind directly is the easier, so why complicate things?

💡 There’s different ways to generate this visualisation for your own workspaces:

In VSCode, use the Nx Project View or the Nx: Focus task in Graph action

In JetBrains IDEs, use the Nx Toolwindow or context menus

In the command line, run nx build {{your project}} --graph

In the bigger context of Nx Console, here’s what happens when you build the VSCode extension

You can see that we’re still building both the new & old generate UI as well as the Nxls and the Nx Cloud webview before combining them all into one VSCode extension artifact.

Building the Form

Lit is a very small library that provides useful abstractions over browser-native features like web components and messages. Here’s what a simple Lit component, written with Typescript, looks like:

// main.ts
@customElement('root-element')
export class Root extends LitElement {
  render() {
    return html`<p> Hello World </p>`;
  } 
}

//index.html
<!DOCTYPE html>
<html lang="en">
    <body>
        <script type="module" src="main.js"></script>
        <root-element></root-element>
    </body>
</html>

If you need to pass information up the DOM, you use normal events and you can set properties to send information to descendants. Check out the Lit Docs to learn more about how the render() method works, how to leverage reactivity, the shadow DOM and so much more.

💡 All code samples in this section have been adapted for brevity and clarity. So you won’t find this exact code anywhere, but it demonstrates the concepts well

Communicating with the IDE - using Reactive Controllers

To communicate with the host IDE, we were able to reuse almost all the logic from the previous UI (for more details, see Communicating with IntelliJ from the last blog post). Instead of a service that exposes observables that our component can consume, we used a Reactive Controller. Controllers are a neat feature of Lit - they hook into a component and can request DOM updates on their behalf. This eliminates the need for observable streams and subscriptions while keeping the communication code self-contained. Look at this example:

// main.ts
@customElement('root-element')
export class Root extends LitElement {
    icc: IdeCommunicationController;

  constructor() {
    super();
    this.icc = new IdeCommunicationController(this);
  }

  render() {
    return html`${JSON.stringify(this.icc.generatorSchema)}`;
  } 
}

// ide-communication-controller.ts
export class IdeCommunicationController implements ReactiveController {
  generatorSchema: GeneratorSchema | undefined;

    constructor(private host: ReactiveControllerHost) {}

    // ...

    private handleMessageFromIde(message: InputMessage) {
        // ...
        this.generatorSchema = message.payload;
        this.host.requestUpdate()
    }
}

You can see that root-element can really just deal with rendering the form contents, delegating communicating with the IDE and when to update the DOM to the controller.

Rendering the form fields - using Mixins

The core part of the UI is the form. We built all kinds of inputs: text fields, checkboxes, (multi-) select boxes and array fields. While those each have unique implementations, displaying them is also going to take a lot of repeated code. Every fields needs a label and description. Every field needs to know about its validation state, how dispatch change events and what aria attributes to set. In order to keep this code clean and DRY, we used Class Mixins. Mixins aren’t really a Lit-specific feature, but I don’t see them used much in other frameworks. A mixin is essentially a factory that takes a class and returns another, modified class. Check out this example:

// field-mixin.ts
const Field = (superClass) => class extends superClass {
    // we can define (reactive) properties that every field is going to need
    @property()
    option: Option;

    protected get fieldId(): string {
      return `${this.option.name}-field`;
  }

    // we can define methods that should be available to all fields
    dispatchValue(value: string) {
        // ...
    }
};

// field-wrapper-mixin.ts
const FieldWrapper = (superClass) => class extends superClass {
    // we can define a render() method so that fields are all rendered the same
    protected render() {
        return html`
            <label for="${this.fieldId}">${this.option.name}</label>
            <p> ${this.option.description} </p>
            ${this.renderField()}
        `
    }
}

// input-field.ts
@customElement('input-field')
export class InputField extends FieldWrapper(Field(LitElement)) {
    renderField() {
        return html`
            <input 
                id="${this.fieldId}"
                @input="${(e) => this.dispatchValue(e.target.value)}"
            />
        `
    }
}

You can see that each component and mixin deals with a specific subset of the overall logic, keeping our code cleanly separated and reusable. A checkbox, for example, is a special case because it’s layout on the page is slightly different - no problem, we simply wrote a CheckboxWrapper with some modifications without having to worry about changing the checkbox logic itself.

💡 Properly typing mixins is complicated so I left that part out. Refer to Mixins in Typescript to learn more or check out our source code on GitHub.

Injecting Services & Data - Lit Context

If you’re coming from the Angular world, you probably appreciate the great dependency injection (DI) mechanism they have. You can centrally define some services and reuse them across your app, without thinking about passing on props from component to component - the DI system takes care of it. Lit provides something similar via the [@lit-labs/context](https://lit.dev/docs/data/context/) package. It’s based on the Context Community Protocol and similar to React’s context API.

Under the hood, it still works with normal browser events, but it abstracts it away from you so you can easily share data and services across your app.

The Generate UI is rendered in both VSCode and JetBrains IDEs. In order to look appropriate, components need to know which environment they’re in and adjust styling accordingly. Instead of passing this information from component to component, we can make it available contextually! And with a proper mixin, reading the editor context only has to be implemented once, too.

Have a look at the following example:

// editor-context.ts
export const editorContext = createContext<'vscode' | 'intellij'>(
  Symbol('editor')
);

const EditorContext = (superClass) => class extends superClass {
    @consume({ context: editorContext })
    @state()
    editor: 'vscode' | 'intellij';
};

// ide-communication-controller.ts
export class IdeCommunicationController implements ReactiveController {
    // ...
    constructor(private host: ReactiveElement) {
        const editor = isVscode() ? 'vscode' : 'intellij';

        // provide the context to all DOM children of the host element
        new ContextProvider(host, {
          context: editorContext,
          initialValue: editor,
        });
    }
}

// some-component.ts
@customElement('some-component')
export class SomeComponent extends EditorContext(LitElement) {
  render() {
    return html`<p> I am rendered in ${this.editor}</p>`;
  } 
}

VSCode Webview UI Toolkit

As we mentioned above, a big part of why we rewrote the UI is that it looked quite out of place in JetBrains IDEs. It was still useful, of course, but it’s important to make sure the form feels right.

In VSCode, this is very easy to achieve, thanks to the VSCode Webview UI Toolkit. It’s a set of web components, provided by Microsoft, that are designed to look good and be used in VSCode webviews.

Using it, you get the native look, a11y, and theme-aware styling for free! Thanks to everyone who built it, it’s a huge help!

E2E Testing with Cypress

One big upside of using a webview is the huge Javascript ecosystem is available to you! To make sure that no regressions are introduced later on, we use Cypress. We can mock the editor communication and provide different schemas, make sure the form is rendered correctly and the right messages are sent back to the IDE.

While there’s no particular Lit integration for Cypress, the tool itself is framework agnostic so it still works perfectly fine. Using the @nx/cypress executors did most of the work for us so setup was pretty quick too.

Results: Comparing Performance

There’s a number of different aspects to performance we can compare between the two implementations. The biggest one by far is not really quantifiable: The maintainability and looks of the new UI. In my opinion, it looks a lot fresher and more native in both environments. We got rid of a lot of legacy code and the new version is easier to reason about and work with.

But there are thing we can measure, so let’s talk numbers!

Startup Time

It takes time to bootstrap a large framework like Angular, so skipping that, the UI should load quicker than before.

We measured the median time it took to render all options of the @nx/angular:application generator in both VSCode and IntelliJ. You can see that the results are pretty clear-cut, even though they are not hugely impactful.

	Old UI (Angular)	New UI (Lit)	Speedup
VSCode	65 ms	39 ms	~ 1.7x
IntelliJ	189 ms	122 ms	~ 1.5x

Bundle Size

As mentioned earlier, Angular comes with a lot more features out-of-the-box than Lit, so it would make sense that the built bundle will be bigger.

We were able to reduce the bundle size (w/o compression) from about 733 kB to 282 kB, which comes out to about a 2,6x decrease. Unlike a website, where the bundle needs to be shipped to users when they load a page, Nx Console users only need to download it once when installing the plugin. This means we’re not affected by network speeds after installation, which makes the bundle size less critical.

💡 Because of a misconfiguration from a few Angular versions ago, the bundle size that we reported in this tweet was overly bloated. We corrected it, but Lit still came out ahead in terms of size and rendering times.

Build Time

While it might not be important to users of Nx Console, the time it takes to build the project makes a difference to us developers.

Since Lit is just javascript files that don’t require a custom compiler or build tooling, we decided to use esbuild (via @nx/esbuild), which is written in Go and extremely fast. On the other hand, the old UI used the @angular-builders/custom-webpack:browser builder, which uses webpack under the hood.

We went from about 3.5 seconds to less than 2 seconds of build time, which is less of an improvement than we expected. Since we also have to run tailwind over our files, some of that additional esbuild speed seems to be relativized.

Looking Ahead

Rebuilding the UI has paved the road to reduce a lot of the maintenance burden of Nx Console. It will allow us to move even quicker on building new features to provide the best developer experience possible for you.

Specifically, the updated architecture enabled us to build a (still secret and WIP) plugin feature for Nx Console. Just like Nx, there are always going to be things that are unique to your workspace. We want to make it easy for you to extend and modify Nx Console in ways that help you make the most of using it.

So keep your eyes peeled for announcements and let us know via GitHub or Twitter if you have any ideas! We’d love to chat.

One more thing!

Nx Console is a tool by developers for developers and there’s one thing we love - keyboard shortcuts. So of course we had to build some in. In addition to being keyboard-friendly and tabbable, you can do the following:

Cmd/Ctrl + Enter to run the generator
Cmd/Ctrl + Shift + Enter to start a dry run
Cmd/Ctrl + S to focus the search bar and look for a specific option. Just tab to get back to the form

If the prettier UI and better performance haven’t convinced you, this surely will! 😉

Learn more

Also, if you liked this, click the 👏 and make sure to follow Max and Nx on Twitter for more!

Battle-Testing Nx Console with E2E Tests

MaxKless — Wed, 16 Nov 2022 13:03:47 +0000

Nx Console is the UI for Nx & Lerna. It’s available as a VSCode extension (and more IDEs coming soon!) and with it, you get powerful features like:

autocomplete for Nx config files,
exploration of generators (and schematics) in a form-based view,
context-aware visualisation of the Nx dependency graph right in your IDE
and many more DX improvements throughout the extension!

The Nx Console project started many years ago and went through various iterations. From a small, standalone client for angular schematics to what it is today: A fully-integrated tool to help you be more productive while developing with Nx.

And folks like it: We passed a million installs this year! 🎉

// Detect dark theme var iframe = document.getElementById('tweet-1518620884570820608-948'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1518620884570820608&theme=dark" }

Of course we as maintainers need to make sure that all of our features work when we make a PR or release a new version.

This used to mean manually clicking through features in different sample workspaces - as you can imagine, this quickly became tedious as well as unreliable. Keep in mind that Nx Console works not just for Nx but also for Lerna and Angular workspaces across multiple versions!

We needed a solution to automate this.

The Problem with testing VSCode extensions

There’s many different kinds of tests and different ways to structure and write them. Let’s go over four common types of tests and see how to use them in the context of a VSCode extension.

Static Tests, like type checking and linting, are a given. VSCode extensions are written in Typescript and Nx sets up ESLint for us automatically so we get these static checks for free.
Unit Tests break your code down into ‘units’ and test those in isolation (what exactly constitutes a ‘unit’ is up to interpretation in most cases). They are a bit more complicated to get right here. Because a lot of functionality is tied to the VSCode APIs, unit tests often end up mocking everything which results in little functionality actually being tested. Because of this, unit tests are mostly useful for niches as well as helper and utility functions, not for broad coverage. They can still be useful and we have unit tests written with jest throughout our repo (but you could use any JS test runner to write and run unit tests).
Integration Tests combine multiple parts of your software and test them together. They are a good option for testing some behaviour of extensions. If you read the docs, they suggest using the @vscode/test-electron package and mocha. This will allow you to run tests inside an actual VSCode instance, so you avoid mocking. However, you are still constrained. The API gives limited information on many areas. For example even this very simple test is not easily realizable with the VSCode API:
```
suite("Sample Extension", () => {
  vscode.commands.executeCommand("testing-ext.helloWorld");

  test("should display 'Hello World' notification", () => {
    // ??? - VSCode API does not expose this information
  });
});
```
End-to-End (E2E) tests are robots that click through your application to make sure it works. They can test every kind of behaviour an actual user could do. Of course, this comes with a price: The overhead to run them can be quite high as you need to spin up fresh VSCode instances for each test. But this is a tradeoff worth taking: You will not be restricted in what you test and the tests mimic actual user flows. The best part: Since VSCode is built on Electron, there is a DOM that you can read, manipulate and assert on just like you would with any web application and keep using the well-established JS tooling we have for this. This is where WebdriverIO comes into play.

WebdriverIO and the wdio-vscode-service

WebdriverIO (abbreviated as WDIO) is an E2E testing framework for Node.js. It allows you to automate all kinds of web and mobile applications using the Webdriver or Chrome DevTools protocols.

In theory - since VSCode is built on Electron and is just Javascript, HTML and CSS under the hood - you could use any other framework like Cypress or Nightwatch to test it.

So why WebdriverIO?

WDIO has one big advantage: The wdio-vscode-service . It’s a plugin that integrates with WDIO and handles all setup-related work for you. You won’t have to think about downloading, installing and running a VSCode instance or the matching Chromedriver. On top of that, it bootstraps page objects for many functionalities and lets you access the VSCode API via remote function execution.

All these (and more) features enable you to set WDIO up quickly and move on to writing test!

Configuring WDIO and writing the first test

Setting up WDIO is a straightforward process. By following the installation guide you get a preconfigured wdio.conf.ts file and all required dependencies installed. After adding some types to tsconfig.json and tweaking some paths in wdio.conf.ts to match our folder structure, we were already at the point where we could execute wdio run ./wdio.conf.ts . You can see that VSCode is downloaded and unpacked for us. But of course, without any tests nothing really happens. Let’s change that!

➜  vscode-e2e ✗ npx wdio run ./wdio.conf.ts

Execution of 0 workers started at 2022-10-27T21:39:54.555Z

Downloading VS Code 1.72.2 from https://update.code.visualstudio.com/1.72.2/darwin/stable
Downloading VS Code [==============================] 100%
Downloaded VS Code into /Users/maxkless/nx-console/apps/vscode-e2e/.wdio-vscode-service/vscode-darwin-1.72.2

2022-10-27T21:40:42.539Z ERROR @wdio/cli:launcher: No specs found to run, exiting with failure

Spec Files:      0 passed, 0 total (0% completed) in 00:00:47

Writing a test isn’t very complicated. Create a file in a location matching your configuration’s specs property and WDIO will pick it up automatically. You can use mocha, cucumber or jasmine as test frameworks and start writing describe , it and before blocks like you’re used to.

import { Workbench } from 'wdio-vscode-service';

describe('NxConsole Example', () => {
  it('should be able to load VSCode', async () => {
    const workbench: Workbench = await browser.getWorkbench();

    expect(await workbench.getTitleBar().getTitle()).toBe(
      '[Extension Development Host] Visual Studio Code'
    );
  });
});

Refer to the WebdriverIO docs to learn more about its API and how to write tests.

If we run wdio run ./wdio.conf.ts again, we will see that WDIO is using the cached VSCode binary and successfully executing our test!

vscode-e2e ✗ npx wdio run ./wdio.conf.ts

Execution of 1 workers started at 2022-11-10T12:10:40.029Z

Found existing install in /Users/maxkless/nx-console/apps/vscode-e2e/.wdio-vscode-service/vscode-darwin-1.72.2. Skipping download
[0-0] RUNNING in chrome - /specs/example.e2e.ts
[0-0] PASSED in chrome - /specs/example.e2e.ts

 "spec" Reporter:
------------------------------------------------------------------
[chrome 102.0.5005.167 mac os x #0-0] Running: chrome (v102.0.5005.167) on mac os x
[chrome 102.0.5005.167 mac os x #0-0] Session ID: da14f0f07ba2fe47728eaf8a249b5bca
[chrome 102.0.5005.167 mac os x #0-0]
[chrome 102.0.5005.167 mac os x #0-0] » /specs/example.e2e.ts
[chrome 102.0.5005.167 mac os x #0-0] NxConsole Example
[chrome 102.0.5005.167 mac os x #0-0]    ✓ should be able to load VSCode
[chrome 102.0.5005.167 mac os x #0-0]
[chrome 102.0.5005.167 mac os x #0-0] 1 passing (1.3s)

Spec Files:      1 passed, 1 total (100% completed) in 00:00:28

Integrating with Nx - defining a target

Of course, we wanted to take advantage of Nx’s powerful features like the task graph, computation caching and distributed task execution. If you’re working on an integrated style Nx repo, you get access to many official and community plugins that allow for instant integration with popular dev tools. Jest, ESLint, Cypress and many more have executors (more on that here) that allow you to run them through Nx. This isn’t the case for WebdriverIO, so we had two options: Create a custom plugin and WDIO executor or simply use nx:run-commands to wrap arbitrary commands with Nx. If WDIO became widely used in our repo, writing a custom plugin isn’t too much effort and could definitely be worth it! But for this one-time usage, we went with the quicker option. Let’s set up an e2e target like this:

{
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "apps/vscode-e2e/src",
  "projectType": "application",
  "targets": {
    "e2e": {
      "executor": "nx:run-commands",
      "options": {
        "command": "wdio run ./wdio.conf.ts",
        "cwd": "apps/vscode-e2e"
      },
      "dependsOn": ["^build"]
    }
  },
  "implicitDependencies": ["vscode", "nxls"],
}

Now, if we run nx run vscode-e2e:e2e , we will see WDIO run inside Nx!

➜  nx-console ✗ npx nx run vscode-e2e:e2e

✔    2/2 dependent project tasks succeeded [2 read from cache]

Hint: you can run the command with --verbose to see the full dependent project outputs

——————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

> nx run vscode-e2e:e2e

## Execution of 1 workers started at 2022-10-27T19:44:02.756Z
Found existing install in /Users/maxkless/nx-console/apps/vscode-e2e/.wdio-vscode-service/vscode-darwin-1.71.2. Skipping download
[0-0] RUNNING in chrome - /specs/example.e2e.ts
[0-0] PASSED in chrome - /specs/example.e2e.ts
"spec" Reporter:

[chrome 102.0.5005.167 mac os x #0-0] Running: chrome (v102.0.5005.167) on mac os x
[chrome 102.0.5005.167 mac os x #0-0] Session ID: 74edae2b6a5f68effc8bdec1e2114e5f
[chrome 102.0.5005.167 mac os x #0-0]
[chrome 102.0.5005.167 mac os x #0-0] » /specs/example.e2e.ts
[chrome 102.0.5005.167 mac os x #0-0] NxConsole Example
[chrome 102.0.5005.167 mac os x #0-0]    ✓ should be able to load VSCode
[chrome 102.0.5005.167 mac os x #0-0]
[chrome 102.0.5005.167 mac os x #0-0] 1 passing (6.8s)
Spec Files:      1 passed, 1 total (100% completed) in 00:00:29

——————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

> NX   Successfully ran target e2e for project vscode-e2e and 2 task(s) it depends on (40s)
> 

Nx read the output from the cache instead of running the command for 2 out of 3 tasks.

See Nx Cloud run details at [https://cloud.nx.app/runs/rprfQeMdy6](https://cloud.nx.app/runs/rprfQeMdy6)

While the output doesn’t look too different, this enables some amazing features! If we run the tests again, they will complete in a few milliseconds because the result could be retrieved from cache. Also, because we defined dependsOn and implicitDependencies , Nx will always make sure that up-to-date versions of Nx Console and the nxls are built before E2E tests run. All this with just a few lines of config!

Setting up CI

Another important step in getting the maximum value out of automated E2E testing is running it in CI. Adding new checks to an existing Github Actions pipeline isn’t complicated, so a single line of yaml configuration should do the trick:

run: yarn exec nx affected --target=e2e --parallel=3

nx affected analyzes your code changes in order to compute the minimal set of projects that need to be retested. Learn more about it here: How Affected Works

This will fail, however, because WebdriverIO tries to open VSCode and expects a screen - which action runners obviously don’t have. If we were testing on a simple Chrome or Firefox instance, this could be solved by adding --headless to the browser’s launch options. VSCode doesn’t support a headless mode, though, so we had to find another solution: xvfb.

xvfb, short for X virtual frame buffer, is a display server that allows you to run any program headlessly by creating a virtual display - the frame buffer. To run our E2E test through xvfb on CI, two steps were necessary:

First, we created a new configuration in our e2e target that runs the same script, but through xvfb.

{
  ...
  "e2e": {
    ...
    "configurations": {
      "ci": {
        "command": "xvfb-run -a wdio run ./wdio.conf.ts"
      }
    },
  }
},
}

Second, we have to make sure xvfb is installed on our action runners. Theoretically, we could just run sudo apt-get install -y xvfb on all our runners and call it a day. But for clarity’s sake and to demonstrate some of the advanced things you can do with Nx Cloud, we decided on a different solution. We want to create two kinds of runners: One with xvfb installed and one without it. This can be done by using the NX_RUN_GROUP variable in our agent and task definitions. With it, E2E tests are run on the first kind and other tasks are run on any runner.

First, we specify a unique value of NX_RUN_GROUP per run attempt and set it as an environment variable in our agent definition. Then, we make sure xvfb is installed on these agents.

agent:
    runs-on: ubuntu-latest
    name: Nx Cloud - Agent E2E
    timeout-minutes: 15
    steps:
      - name: Set nx run variable
        run: echo "NX_RUN_GROUP=run-group-e2e-${{ github.run_id}}-${{ github.run_attempt }}" >> $GITHUB_ENV
      - uses: actions/checkout@v2
      - uses: ./.github/workflows/setup
        with:
          node_version: ${{ env.node_version }}
      - name: Install xvfb
        run: sudo apt-get install -y xvfb
      - name: Start Nx Agent E2E
        run: npx nx-cloud start-agent
      - uses: actions/upload-artifact@v3
        with:
          name: e2e-screenshots
          path: apps/vscode-e2e/.screenshots
          if-no-files-found: ignore

In action.yml , where we specify the checks to be run, we provide the same NX_RUN_GROUP environment variable for our E2E task.

name: E2E
env:
    NX_RUN_GROUP: run-group-e2e-${{ github.run_id}}-${{ github.run_attempt }}
run: yarn exec nx affected --target=e2e --parallel=3 --configuration=ci

Nx Cloud then matches these run groups and makes sure that all E2E tasks are only executed on agents with xvfb installed. With it, we can now do everything we can do locally, with a real screen. For example, we take screenshots on failure and make them available to download from GitHub via actions/upload-artifact .

Conclusion

In the end, we have fully functioning E2E test running on every PR, fully cached and distributable through Nx.

I want to take a moment and give special thanks to Christian Bromann who is a lead maintainer on WebdriverIO and the wdio-vscode-service. Without his foundational work, this would’ve been 100x harder.

If you have questions, comments or just want to chat about Nx Console, you can find me on twitter: @MaxKless

Some of the code snippets I showed here have been shortened for clarity, but if you want to see our setup with all details, head over to GitHub:

nrwl / nx-console

Nx Console is the user interface for Nx & Lerna.

The UI for Nx & Lerna

Spend less time looking up command line arguments and more time shipping incredible products.

Why Nx Console?

Developers use both command-line tools and user interfaces. They commit in the terminal, but resolve conflicts in Visual Studio Code or WebStorm. They use the right tool for the job.

Nx is a command-line tool, which works great when you want to serve an application or generate a simple component. But it falls short once you start doing advanced things.

For instance:

Exploring custom generator collections is hard in the terminal, but it's easy using Nx Console.
Using rarely-used flags is challenging. Do you pass absolute or relative paths? You don't have to remember any flags names or paths - Nx Console will help you by providing autocompletion and validating your inputs.
Context-switching between your IDE and the browser is annoying. With Nx Console, you can view…

View on GitHub

Learn more

Also, if you liked this, click the ❤️ and make sure to follow Max and Nx on Twitter for more!

DEV Community: MaxKless

Nx Console gets Lit

Background: Why Migrate from Angular to Lit?

A Short History of Nx Console

Rewriting in Lit

Nx Console Architectural Overview

Migrating to Lit: Step by Step

Building the Form

Communicating with the IDE - using Reactive Controllers

Rendering the form fields - using Mixins

Injecting Services & Data - Lit Context

VSCode Webview UI Toolkit

E2E Testing with Cypress

Results: Comparing Performance

Startup Time

Bundle Size

Build Time

Looking Ahead

One more thing!

Learn more

Battle-Testing Nx Console with E2E Tests

The Problem with testing VSCode extensions

WebdriverIO and the wdio-vscode-service

Configuring WDIO and writing the first test

Integrating with Nx - defining a target

Setting up CI

Conclusion

nrwl / nx-console

Nx Console is the user interface for Nx & Lerna.

The UI for Nx & Lerna

Why Nx Console?

Learn more

#nx Follow