DEV Community: Souchet Céline

Hacktoberfest 2022: Now, it's an official Process Analytics tradition!

Souchet Céline — Wed, 16 Nov 2022 16:34:00 +0000

Again this year, Process Analytics participated in Hacktoberfest 2022 and we’d like to share what we consider to be a great success. This post highlights some contributions the project received, and we compare this year’s results with the results of Hacktoberfest 2021 👀.

We offered the community the opportunity to work on our cornerstone bpmn-visualization TypeScript library, its related examples repository, the project website and the bpmnVisualizationR package.

As part of the event, we updated our famous Hacktoberfest BPMN Diagram with the Hacktoberfest 2022 theme:

Hacktoberfest 2022 with Process Analytics

Nour Assy for Process Analytics ・ Sep 26 '22 ・ 3 min read

#hacktoberfest #typescript #rlang #visualization

We are on Discord

But before we talk about the contributions received, if you missed the September news, we have set up a Discord server to more easily discuss topics of interest with the community of the Process Analytics project.

It was very useful during the Hacktoberfest period, so we plan to keep it active indefinitely. Help us keep up the chat with your thoughts and ideas.

ℹ️ Feel free to check the September news, or access the server directly to see the different channels currently available.

Hacktoberfest 2022 results

As always happens, some contributions could not be completed due to lack of contributor’s time, or due to the complexity of a task. That is often the case with Hacktoberfest projects - it’s the way it works!

Nevertheless, we would like to thank all the people who made an effort to contribute 🙏🏻. We warmly invite you to try again, at any time, and we’re more than happy to provide assistance 🙂.

Now, let's talk about the contributions that were accepted.

bpmnVisualizationR package

We had our first external contribution on the bpmnVisualizationR package 🥳

Many thanks to ColinFay, an R specialist, working at ThinkR (Certifications et Formations au langage R).

Colin worked on adding automated tests to this package, and also gave us some tips on good practices 🤩.

Examples of the bpmn-visualization TypeScript library

2 people contributed to the repository of the bpmn-visualization examples.

Thanks to:

Emmanuel Duchastenier who worked on:
- improving the contributing guide,
- the replacement of the favicon.
Adrien Kantcheff for adding an example of a project using Angular 14

Website

Emmanuel Duchastenier’s improvement of the contributing guide will make future contributions easier.

Advocacy

As maintainers, we also had the privilege of contributing by advocating for our project, for Hacktoberfest and for the idea of open source contribution in general 😎.

We organized multiple sessions with Data Science students who have no experience with open source contribution. Multiple students expressed interest and started learning our project domain: process analytics and BPMN.

This was a rewarding experience for us 🥇. In addition to encouraging people to contribute to open source 💪, working with students forced us to speak a non/low-code language and to prepare a getting started tutorial to using our libraries that is easy to follow for any beginner.

That’s all folks

We were very happy to participate in Hacktoberfest 2022 🥰, to receive contributions and to get feedback from the contributors.

We hope our contributors got their Hacktoberfest 👕 or planted a 🌳.

We plan to participate again in 2023 🥳. In the meantime, feel free to contribute to the Process Analytics on GitHub or to contact us if you have any questions 👋.

And don’t forget, to stay on top of the latest news and releases, follow us through:

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics
Discord: Join our server!

Dive Into Process Analytics at Bonita Day Paris

Souchet Céline — Wed, 17 Aug 2022 12:58:25 +0000

Today, process analysis is becoming an increasingly important part of the industry. Analysis techniques are becoming more diverse.

However, there are no dedicated and well-defined visualization APIs for the visualization component of these process analysis results, which makes visualization customization (to meet specific needs) difficult.

🔙In early 2020, Bonitasoft launched an initiative to make process analytics visualization more accessible and intuitive: Process Analytics.

This project consists of open source libraries and components, based on the BPMN process model, that help developers to create tools that can provide a visual overview of your business process and their execution data.

During Bonita Day, organized in Paris in early April 2022, we presented the Process Analytics project of Bonitasoft (in French 🇫🇷). ℹ️ It was also made at Bonita Day in Madrid in Spanish 🇪🇸

The presentation is designed to use Process Analytics libraries to help you understand how your business processes are executed and how to optimize them.

📽 During this session, we showed the different components of the project available to you, as well as demonstrating a concrete integration case through a ticketing application:

Presentation of the different components of the Process Analytics project
Focus on the use of the bpmn-visualization TypeScript library (provided by the Process Analytics project) to monitor processes
Focus on the exploitation of the execution context of a process instance
Focus on the exploration and navigation between the process and the administration pages of the Bonita Platform

We also talked about a bridge between the world of Process Mining and the world of BPM. The Process Analytics project has developed a tool to generate a process model (in both the classic Process Mining format and in the BPMN format) from event logs (XES format). With this tool, you can compare these 2 visualizations, and it’s useful to be able to use the generated process in a BPM platform.

Go to the Model Generation Application page to try it 🧪

As mentioned above, the Process Analytics project is Open Source. So we will be more than happy to exchange ideas and more with you on the subject.

Because who knows, if you feel like contributing (feature, bug, doc, etc), you are very welcome to do so! 🙂

In the meantime, if you want to stay on top of the latest news and releases from the Process Analytics project, follow us through:

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics

Model Generation Application

Souchet Céline — Tue, 09 Aug 2022 08:31:08 +0000

In our May news, we announced 📣 our upcoming demonstration tool: “Model Generation Application”.

Built with Process Analytics components, it is a shiny R application that generates a process from event logs (in XES format), using 2 representations that can be used for comparison, with execution data (frequency):

a basic Process Discovery view
a BPMN diagram

For both representations, it lets the user filter out noise that can be generated by the event log, depending on its quality.

With the BPMN view, you can enrich the process semantics by doing gateway and task detection.
And once the BPMN diagram is generated, you can use it in a BPM platform.

⏩ Go to the Model Generation Application page to learn more and try it out 🧪. We’re interested in your feedback!

While waiting for the online version, if you want to stay up to date with the latest news and releases from the Process Analytics project, follow us :

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics

🇫🇷 Webinar: Dive into Process Analytics

Souchet Céline — Fri, 05 Aug 2022 12:54:28 +0000

The Process Analytics project consists of open source libraries and components that allow you to get a visual overview of your business process and the process execution data.

At the end of June 2022, Haris Subašić and Céline Souchet showcased an integration use case through a ticketing application, in French 🇫🇷.

ℹ️ The presentation is designed to help you understand how your processes are executed and how to optimize your business processes.

🎥 Topics covered include:

What different process components are available to you
How the bpmn-visualization TypeScript library can be used to monitor processes
How to leverage execution context of processes
How to drill down and navigate between the process and the Bonita administration pages

In the meantime, if you want to stay on top of the latest news and releases from the Process Analytics project, follow us through:

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics

🇬🇧 Webinar: Dive into Process Analytics

Souchet Céline — Wed, 03 Aug 2022 15:27:00 +0000

The Process Analytics project consists of open source libraries and components that allow you to get a visual overview of your business process and the process execution data.

On July, 5th 2022, Alejandro Rondón and Thomas Bouffard showcased an integration use case through a ticketing application.

ℹ️ The presentation is designed to help you understand how your processes are executed and how to optimize your business processes.

🎥 Topics covered include:

What different process components are available to you
How the bpmn-visualization TypeScript library can be used to monitor processes
How to leverage execution context of processes
How to drill down and navigate between the process and the Bonita administration pages

In the meantime, if you want to stay on top of the latest news and releases from the Process Analytics project, follow us through:

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics

Process Analytics - June 2022 News

Souchet Céline — Wed, 13 Jul 2022 09:49:23 +0000

Welcome to the Process Analytics monthly news 👋.

As you know, the goal of the Process Analytics project is to rapidly display meaningful Process Analytics components in your web pages using BPMN 2.0 notation and Open Source libraries.

Summer is here 🌞. People in the northern hemisphere are happy not to see clouds ☁️ and rain 🌧️.

On our side, the project team worked very hard in June to improve the bpmn-visualization TypeScript library 🤗. We also presented the project at several conferences and events. Let’s see what’s new here 👀!

Events

Bonita Day Paris

At the beginning of April 2022, our team presented the Process Analytics project at the Bonita Day event in Paris, organized by Bonitasoft.

The replay of this presentation in French is available 👇

ℹ️ For more information, see this article.

FR Webinar: À la découverte de Process Analytics

We also presented the Process Analytics project during a Webinar organized by Bonitasoft, at the end of June.

In this presentation, we showed the different components of the project available to you, as well as a concrete integration case using a ticketing application as an example.

The replay of this presentation in French is available on the Bonitasoft website.

ℹ️ A webinar in English is planned for early July and another webinar en español (in Spanish) will be scheduled in the future.

Bonita Day Madrid

At the end of June 2022, Alejandro Rondon presented the Process Analytics project at the Bonita Day event in Madrid, organized by Bonitasoft. 🙏🏻 Big thanks to Alejandro.

The event teaser is available 👇

bpmn-visualization TypeScript library

In June, we released 2 versions: 0.24.1 & 0.25.0.

New API: Filter pools at load time

When calling the load method, it is now possible to filter the pools in the diagram you want to display.

You can filter for one or several pools and specify the filtering options by pool id and/or name.

In the following example 👇, we load the same diagram with different filter configurations. First we load without filtering, so we see the whole diagram. Then we filter different pools, one pool at a time. And finally, we filter 3 pools at the same time.

Demo page improvements

Add a select button to switch the BPMN Theme

It’s now possible to change the BPMN theme at runtime in the demo page.

Add a zoom reset button

We also added a new button to reset the zoom level, very similar to the previous zoom in/out.

Examples

Change the fill color of edge markers

⏩ A new example is available to demonstrate how to change the fill color of the edge markers.

Message Flows: Start (circle) and End (arrow) markers

Sequence Flows: Conditional marker

Add a new project to demonstrate integration with Parcel

This new project demonstrates the straightforward integration of bpmn-visualization in a TypeScript project built with Parcel v2. It also helps to improve project quality by detecting any integration errors prior to shipping new releases.

For more information, see process-analytics/bpmn-visualization-examples#338.

That’s all folks!

We hope you enjoyed this June project news and are looking forward to what the rest of the summer will bring 👋.

In the meantime, stay on top of the latest news and releases by following us:

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics

Cover photo by Mick Haupt on Unsplash

Process Analytics - March 2022 News

Souchet Céline — Tue, 03 May 2022 13:36:42 +0000

Welcome to the Process Analytics monthly news 👋.

As we remind you each month, the goal of the Process Analytics project is to rapidly display meaningful Process Analytics components in your web pages using BPMN 2.0 notation and Open Source libraries.

In March, we worked on improving the bpmn-visualization TypeScript library and the bpmnVisualizationR package 🤗. Let’s see what’s new here 👀!

bpmn-visualization TypeScript library

In March, we released 2 versions: 0.22.0 & 0.23.0.

Improvements for TypeScript projects 📃

We simplified the TypeScript integration by removing the need to install typed-mxgraph in your project.

It is now easier than ever to use bpmn-visualization in TypeScript projects 🎉.

New API 📚

It is possible to use the new API to retrieve the bpmn-visualization and mxGraph versions used at runtime: getVersion().

An example of an integration is shown below 👇.

This is done with the following JavaScript code that displays the version information in the footer of the page:

// Use the new “Version” API
const version = bpmnVisualization.getVersion();

// bpmn-visualization version
const versionAsString = `bpmn-visualization@${version.lib}`;

// List all dependencies in the form of “dependency-1@version / dependency-2@version / ….”
const dependenciesAsString = [...version.dependencies].map(([name, version]) => `${name}@${version}`).join('/');

// “footer” is the html element that displays the version information
footer.innerText = `${versionAsString} with ${dependenciesAsString}`;

NOTE: This is helpful to debug projects that use a newer version of the mxGraph library which currently causes issues, like version 4.2.2.

BPMN rendering fixes ✅

☢️ The library didn't accept the coordinates of the waypoints of the edges defined in the BPMN 2.0 source. Instead, it forced the usage of orthogonal edges which had a lot of side effects.

The video below 👇 shows the behavior changes on message flows. The first part presents the rendering as it was done prior to the 0.23.0 version. The position of the message flow (and its label) sometimes changed depending on the zoom factor 😵‍💫. The same issue applied to overlays that were configured to be displayed at the middle of the edges. They were moved to the start or the end of the edge.

The second part of the video is done using the 0.23.0 version. The edge segments are no longer always orthogonal and the position of the element remains unchanged, regardless of the zoom factor. 🥳

Have a look at the release notes of the 0.23.0 version to get the complete list of issues that are fixed by removing the 'always use orthogonal edges' configuration.

Documentation improvement 🎁

The icons used in the library are now available in SVG format in the docs/users/images/icons folder. Feel free to reuse the icons in your application.

The user documentation has also been updated to display the icons.

Demo improvement ✨

The layout of the demo has been improved for mobile devices.

The demo also displays the current versions of bpmn-visualization and of the mxGraph library in the footer.

bpmnVisualizationR package

In March, we released 1 version: 0.1.2.

The major change is the upgrade of the bpmn-visualization TypeScript library to version 0.23.0.

That’s All Folks!

We hope you enjoyed this March project news and are looking forward to what April will bring 👋.

In the meantime, to stay on top of the latest news and releases, follow us through:

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics

Cover photo by Dustin Humes on Unsplash

Using BPMN Visualization in R

Souchet Céline — Thu, 14 Oct 2021 13:53:05 +0000

With the bpmn-visualization TypeScript library, you can visualize process execution data on BPMN diagrams in a web browser, by adding custom overlays and customizing the style of the diagram.

The new BPMN Visualization - R Package is being developed to offer another way to visualize process execution data in R.

Let's see how it works.

Prerequisites

R Studio or R Console

Installation

First, you need to install the package from Github:

Load a BPMN file

The bpmnVisualization package accepts a BPMN file in XML format.
There are several ways to load this file. However, in this article, we will focus on how to load an example file from the package.

You will find the other ways to load a BPMN file in the README of the package.

Display the BPMN diagram

At the moment, there are 2 ways to display the BPMN diagram: Just the diagram without overlay or The diagram with overlay(s).

Just the diagram

The diagram with overlays

Overlays customization and positioning will be possible in a future version of the package.

Integrate in a Shiny App

You can also use the bpmnVisualization package in a Shiny app.

If you are not familiar with Shiny, it is an R package that makes it easy to build interactive web apps straight from R. You can host standalone apps on a webpage or embed them in R Markdown documents or build dashboards.

The following example displays a BPMN diagram provided as an example by the package, with an overlay on top of a BPMN element.

Participation in Hacktoberfest 2021

If you want to participate in Hacktoberfest to promote Open Source development and you don't know where to make a contribution, you can try with the labeled issues from the BPMN Visualization - R Package repository.

We are also waiting for contributions in other repositories. For more information, see this article.

If you have any questions - let us know directly on GitHub issues or via Twitter.

Conclusion

Now, you have everything you need to start your first project with BPMN Visualization in R.

Thank you for reading and I hope I helped or inspired you 😊

We also plan to publish the BPMN Visualization package in CRAN soon.

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics

Process Analytics - September 2021 Newsletter

Souchet Céline — Wed, 13 Oct 2021 14:34:59 +0000

Welcome to the Process Analytics monthly newsletter 👋.

The goal of the Process Analytics project is to rapidly display meaningful Process Analytics components in your web pages using BPMN 2.0 notation and Open Source libraries.

Summer is over 🏖️, September was back to school 📚. October is Hacktoberfest 🍁. On our side, the project team worked hard to propose many new elements in our project:

Website changes
Hacktoberfest 2021 participation
GitHub organization profile
New examples of the bpmn-visualization TypeScript library

Website: add the News section

Have you missed our past news? 😱 Don't worry, you can now access everything directly from the website home page. 😊

Remember that we cross post all our news on both Medium and Dev.to.

The 'News' section in the website home page

Hacktoberfest participation as maintainers

The Process Analytics team is participating in Hacktoberfest
2021, as we did for Hacktoberfest 2020.

🤔 What is Hacktoberfest?

Hacktoberfest encourages participation in the open source community, which grows bigger every year.
Hacktoberfest, in its 8th year, is a month-long celebration of open source software run by DigitalOcean. During the month of October, we invite you to join open-source software enthusiasts, beginners, and the developer community by contributing to open-source projects.

We prepared our project to be ready to welcome Hacktoberfest participants. This included updating examples and documentation, and polishing 🧹 the GitHub repositories.

You can find more details about our participation in the following article:

Hacktoberfest 2021 with Process Analytics

Thomas Bouffard for Process Analytics ・ Sep 30 '21 ・ 2 min read

#hacktoberfest #news #bpmn #analytics

GitHub organization profile

The GitHub profile highlights our main repositories ✨ and explains how you can easily contribute to Process Analytics. ⏩ See the live profile.

Cheat Sheet for contributing to Process Analytics

bpmn-visualization TypeScript library

In September, we released 2 versions: 0.19.1 & 0.19.2.

In addition to internal improvements, they include new examples.

Two new live examples

These new examples let you experiment with the bpmn-visualization integration and use the API directly in your browser. They can also be used as templates to demonstrate missing features or bugs.

They are available on various platforms:

If you are not familiar with these live IDEs, visit the CodeSandbox documentation and the CodePen documentation.

With the proposed template 👇, you can test, for instance, the Overlays and style API. You will see the results in the browser in seconds.

Playing with the Codepen template

Monitoring demo improvements

The demo now uses a new design that also allows users to select the data types to add to the BPMN diagram: Paths, Overlays or Both.

The legend part has also been improved. It displays:

The legend titles
Only the legends related to the selected data types

Improvements of the monitoring processes demo

Hacktoberfest 2021 theme demo revamped

The Hacktoberfest demo has been updated to use the Hacktoberfest 2021 theme, which has a refreshed design. Using the selection buttons, it is now possible to:

Easily change the theme (dark or light)
Choose the 2020 or 2021 flavor

Want to use the same kind of image to call for contributions for Hacktoberfest in your own project or access to the light and dark themes? ⏩ Go to the live demo!

Choose your favorite Hacktoberfest Theme

Plans for the future

Here are the topics we will be managing in the coming months:

Create new examples to demonstrate other Process analytics / Process Mining use cases.
Add more tests to be able to upgrade mxGraph (the technical library in charge of the final rendering) to the latest version.

That's All Folks!

We hope you enjoyed the September/October project news and are looking forward to what the rest of the fall will bring 👋.

In the meantime, to stay on top of the latest news and releases, follow us through:

Website: https://process-analytics.dev
Twitter: @ProcessAnalyti1
GitHub: https://github.com/process-analytics

Cover photo by Anne Nygård on Unsplash

Automated visual regression testing with TypeScript, Playwright, Jest and Jest Image Snapshot

Souchet Céline — Mon, 20 Sep 2021 12:22:18 +0000

Introduction

As you know, to have automated visual regression tests (in addition to unit and integration tests) is important to ensure the users a good experience.

This assures that nothing is accidentally broken and confirms that user flows and the appearance of your application are functional when the existing code is modified or a dependency is updated.

Recently, I wrote an article on visual regression testing with TypeScript, Jest, Jest Image Snapshot and Puppeteer.

If you use Puppeteer, you know that you can test only under Chromium.
The implementation with Firefox is experimental, and Webkit is not supported at all.

Today, I will offer you an alternative to Puppeteer: Playwright
Playwright is pretty similar to Puppeteer. All the features present on Puppeteer are not yet present on Playwright. But the advantage with this tool is that you can run your tests on Chromium, Firefox, Webkit, Google Chrome & Microsoft Edge, and in addition with a single command.

In this article, I will explain how to set up and to run tests with Playwright, in a TypeScript project, using Jest - as the test runner - and Jest-Image-Snapshot (Jest matcher) - to take screenshots of current web pages and to compare generated screenshots with a screenshot baseline to find regressions in the user interface.

If you read my previous article, it will be pretty similar.

Project example

I will use the bpmn-visualization TypeScript library (version 0.13.0) as an example. (This example has been simplified so it shows more clearly the configuration and features explained in this article.) The goal of this project is to load BPMN content, and render it.
Automated visual tests will simplify our life with each refactoring, addition of a new component, update of the positioning algorithm of the different BPMN elements, or update of the MxGraph rendering library.
Also, I will configure the tests to run on Chromium, Firefox and Webkit.

Prerequisites

As first step, we need to install the required packages as
devDependencies:

Jest + its type definition: A JavaScript Testing Framework

Jest is a fully featured testing framework, developed by Facebook. It needs very little configuration and works basically out of the box.

npm install -D jest @types/jest

Playwright: A Node.js library to automate Chromium, Firefox,Webkit, Google Chrome & Microsoft Edge with a single API. It is possible to perform most of the actions that are done manually on a browser and take screenshots.

npm install -D playwright jest-playwright-preset

Jest-Image-Snapshot + its type definition: A Jest matcher to perform image comparisons

npm i -D jest-image-snapshot @types/jest-image-snapshot

Configuration

Let’s configure the previous libraries.

Configure Jest

I won't go into detail here on all the different ways to configure Jest.
If you already use Jest for your unit/e2e tests, this is not new for you. If you would like more explanations about Jest, there are many great articles available.

In this example, we have 4 Jest configurations: unit tests, integration tests, e2e tests and performance tests. We added the visual tests in the e2e test suite. Here, I will just explain how we configure Jest for the e2e tests.

First, create the Jest configuration file (jest.config.js) at ./test/e2e directory:

This configuration sets the root directory to the root project directory, runs .ts files with ts-jest module and looks for .spec.ts and test.ts files under any subdirectory of ./test/e2e directory.

Configure Playwright

Specify the preset in the Jest configuration (./test/e2e/jest.config.js), as specified in the official documentation of Playwright:
Create a new file (./test/e2e/jest-playwright.config.js) for the Playwright configuration to run the server & launch the browser once for all tests:

With this configuration, we start a server on the port 10002 with a timeout of 30s, and start 3 browsers.

Extend the Jest expect assertion mechanism to use Jest Image Snapshot

This is the part that might be new, but with a little configuration, we will be ready soon.

By default, Jest doesn’t know anything about Jest-Image-Snapshot and its assertion toMatchImageSnapshot. So we’ll need to extend Jest. For that, create a new file (./test/e2e/jest.image.ts), like the following:

To avoid extending Jest in each test file or import the previous file globally in all test files, we need to configure Jest to run it immediately after the test framework has been installed in the environment with setupFilesAfterEnv (Jest property) in ./test/e2e/jest.config.js.

Add a new command

To simply the test execution, add the following script in the package.json file:

Now, you can run your e2e tests with the following command:
npm run test:e2e

Note: cross-env is useful if you run the tests on different OS.

Test

You can find the different properties to customize Jest-Image-Snapshot in its README on Github.

Create a basic test with Jest-Image-Snapshot

If everything is configured correctly, we are now ready to create our first visual regression test (./test/e2e/bpmn.rendering.test.ts) by combining Playwright and Jest and Jest-Image-Snapshot!

After the test runs, a new directory will be created -
__image_snapshots__ - with an image for each toMatchImageSnapshot call. The name of the snapshot is computed by default with testPath, currentTestName, counter and defaultIdentifier.

Example of generated snapshot:

bpmn-rendering-test-ts-no-bpmn-gateway-visual-regression-1-snap.png

Note: Make sure that the snapshot files are committed in your source control so that they are shared with other developers and CI environments.

Test on different machines

One issue with one-to-one pixel matching is that there is a good chance that the test will be in error on a machine other than on which it was developed, because every environment has slightly different ways of rendering the same application.

For example, suppose that we want to run the tests on the CI environment every time we create a pull request to the master branch in GitHub.
Without any modifications to the code, the test is passed locally; but on the CI environment, it fails with a message like this:

Error: Expected image to match or be a close match to snapshot but was 0.0005804554357724534% different from snapshot (2.7861860917077763 differing pixels).

And a new image file for the diff is stored in the
__image_snapshots__/__diff_output__ directory with the name <snapshot_name>-diff.png.

If we use the previous test, we’ll have something like this:

bpmn-rendering-test-ts-no-bpmn-gateway-visual-regression-1-diff.png

You can modify the previous jest-image-snapshot configuration (./test/e2e/bpmn.rendering.test.ts), and update the value of failureThreshold (default value: 0) & failureThresholdType (default value: pixel). These properties are used to calculate the threshold of tolerated differences (before the test fails).

Warning: If you increase the failure threshold too much, when there is too much difference between local and CI environments, it may be impossible to detect visual regressions.

Order the snapshots

If you have 10 or more tests, it can become complicated to find which screenshot corresponds to which test / feature in the directory __image_snapshots__.

Modify the customSnapshotsDir property to have a different value according to the tests.

./test/e2e/helpers/image-snapshot-config.ts
./test/e2e/bpmn.rendering.test.ts
./test/e2e/bpmn.navigation.test.ts

Reuse the snapshots

Sometimes the expected result/snapshot is the same even after different actions. To avoid having a lot of identical snapshots in the Github repository, it’s better to reuse a snapshot.

For that, it’s necessary to override the default customSnapshotIdentifier & customDiffDir properties.

customSnapshotIdentifier: the custom name to give this snapshot. This prevents the name of the snapshots from being computed with testPath, currentTestName, counter and defaultIdentifier.
customDiffDir: the custom absolute path of a directory to keep this diff in. As we use the same snapshot in different tests, to know which diff file corresponds to which test, we need to set a different value according to the tests.

Example

./test/e2e/helpers/image-snapshot-config.ts
./test/e2e/diagram.rendering.test.ts

Conclusion

With so many operating systems, web browsers, and screen resolutions, Visual Testing can be a powerful tool to assure that an application works well in all possible environments. It is definitely worth trying it as a complement to other sets of tests.

Now, you have everything you need to start your first visual regression test in TypeScript with Jest & Playwright.

Thank you for reading and I hope I helped or inspired you :)

References

Github repository of bpmn-visualization: https://github.com/process-analytics/bpmn-visualization-js
Github repository of Jest-image-snapshot: https://github.com/americanexpress/jest-image-snapshot
Playwright documentation: https://playwrightdev/
Main image made with: https://www.canva.com

Automated visual regression testing with TypeScript, Puppeteer, Jest and Jest Image Snapshot

Souchet Céline — Fri, 16 Apr 2021 16:14:16 +0000

Introduction

As developers, it is our job to ensure that our users get an experience with no regression.

Like any good developer, when I add a feature or fix a bug, I also create unit, integration, and end-to-end tests. This assures that, when the existing code is modified, nothing is accidentally broken, and confirms that user flows are functional.

Like many people, I've gotten used to using a manual process to visually check that the design looks as intended.

Refactoring, adding a new component, or updating a package can sometimes change the appearance of the application. It can get laborious to click through every possible user journey, and we are not immune to forgetting a test or to miss a small visual change.

So how can we make sure that the visuals are always correct and less painful to test? I had heard of automatic testing for no visual regression before. I looked into using Selenium some time ago, but changed projects and no longer needed it.

Now that I have a need for visual checks in my current project, I’ve found there are different libraries - easy to learn - that can take screenshots of current web pages and compare generated screenshots with a screenshot baseline to find regressions in the user interface (UI).

In this article, I will explain how to use one of these libraries - Jest-Image-Snapshot (Jest matcher) - in a Typescript project.

Project example

I will use the bpmn-visualization TypeScript library (version 0.10.0) as an example. (This example has been simplified so it shows more clearly the configuration and features explained in this article.) The goal of this project is to load BPMN content, and render it.
Automated visual tests will simplify our life with each refactoring, addition of a new component, update of the positioning algorithm of the different BPMN elements, or update of the MxGraph rendering library.

Prerequisites

As first step, we need to install the required packages as devDependencies:

Jest + its type definition: A JavaScript Testing Framework

Jest is a fully featured testing framework, developed by Facebook. It needs very little configuration and works basically out of the box.

npm install -D jest @types/jest

Puppeteer + its type definition: A Node library to control Chrome or Chromium, both in headless mode and with a user interface. It is possible to perform most of the actions that are done manually on a browser and take screenshots.

npm install -D puppeteer @types/puppeteer jest-puppeteer

Jest-Image-Snapshot + its type definition: A Jest matcher to perform image comparisons

npm i -D jest-image-snapshot @types/jest-image-snapshot

Configuration

Let’s configure the previous libraries.

Configure Jest

In this example, we have 3 Jest configurations: unit tests, e2e tests, and performance tests. We added the visual tests in the e2e test suite.
Here I will just explain how we configure Jest for the e2e tests.

First, create the Jest configuration file (jest.config.js) at ./test/e2e directory:

Configure Puppeteer

Specify the preset in the Jest configuration (./test/e2e/jest.config.js), as specified in the official documentation of Jest:
Create a new file (./test/e2e/jest-puppeteer.config.js) for the Puppeteer configuration to run the server & launch the browser once for all tests:

With this configuration, we start a server on the port 10002 with a timeout of 30s, start a browser with a timeout of 2 minutes, and pipe the browser process stdout and stderr into process.stdout and process.stderr.

Extend the Jest expect assertion mechanism to use Jest Image Snapshot

This is the part that might be new, but with a little configuration, we will be ready soon.

Add a new command

To simply the test execution, add the following script in the package.json file:

Now, you can run your e2e tests with the following command:
npm run test:e2e

Note: cross-env is useful if you run the tests on different OS.

Test

You can find the different properties to customize Jest-Image-Snapshot in its README on Github.

Create a basic test with Jest-Image-Snapshot

If everything is configured correctly, we are now ready to create our first visual regression test (./test/e2e/bpmn.rendering.test.ts) by combining Puppeteer and Jest and Jest-Image-Snapshot!

After the test runs, a new directory will be created -
__image_snapshots__ - with an image for each toMatchImageSnapshot call. The names of the snapshots are computed by default with testPath, currentTestName, counter and defaultIdentifier.

Example of generated snapshot:

bpmn-rendering-test-ts-no-bpmn-gateway-visual-regression-1-snap.png

Note: Make sure that the snapshot files are committed in your source control so they are shared with other developers and CI environments.

Test on different machines

Error: Expected image to match or be a close match to snapshot but was 0.0005804554357724534% different from snapshot (2.7861860917077763 differing pixels).

And a new image file for the diff is stored in the __image_snapshots__/__diff_output__ directory with the name <snapshot_name>-diff.png.

If we use the previous test, we’ll have something like this:

bpmn-rendering-test-ts-no-bpmn-gateway-visual-regression-1-diff.png

Warning: If you increase the failure threshold too much, when there is too much difference between local and CI environments, it may be impossible to detect visual regressions.

Order the snapshots

If you have 10 or more tests, it can become complicated to find which screenshot corresponds to which test/feature in the directory __image_snapshots__.

Modify the customSnapshotsDir property to have a different value according to the tests.

./test/e2e/helpers/visu-utils.ts
./test/e2e/bpmn.rendering.test.ts
./test/e2e/bpmn.navigation.test.ts

Reuse the snapshots

Sometimes the expected result/snapshot is the same even after different actions. To avoid having a lot of identical snapshots in the Github repository, it’s better to reuse a snapshot.

For that, it’s necessary to override the default customSnapshotIdentifier & customDiffDir properties.

customSnapshotIdentifier: the custom name to give this snapshot. This prevents the name of the snapshots from being computed with testPath, currentTestName, counter and defaultIdentifier.
customDiffDir: the custom absolute path of a directory to keep this diff in. As we use the same snapshot in different tests, to know which diff file corresponds to which test, we need to set a different value according to the tests.

Example

./test/e2e/helpers/visu-utils.ts
./test/e2e/diagram.rendering.test.ts

Conclusion

Now you have everything you need to start your first visual regression test in Typescript with Jest & Puppeteer.

Thank you for reading and I hope I helped or inspired you :)

References

Github repository of bpmn-visualization: https://github.com/process-analytics/bpmn-visualization-js
Github repository of Jest-image-snapshot: https://github.com/americanexpress/jest-image-snapshot
Puppeteer documentation: https://pptr.dev/
How to use Puppeteer with Jest: https://jestjs.io/docs/en/puppeteer
Main image made with: https://www.canva.com