Forem: Mikhail Istomin

The most valuable developer in the team is …

Mikhail Istomin — Thu, 05 Sep 2024 00:51:22 +0000

… the one who increases the productivity of their team members.

You don’t have to be a team/tech lead or an architect to do things that boost the team`s performance. Even a middle-level developer can cause the impact.

Motivation

Why should you care about colleagues’ performance? Because making things that improve the team performance saves money for the business. The team can do more for less time. The ability to make such improvements makes you valuable for the business. For the current and future employers. It’s a win-win situation, good for the business, and good for you.

it can facilitate your promotion
it looks great in your CV
it highlights your professionalism in the job interviews

Here are some ideas, on what to do to boost your team.

Metrics

I added some hints concerning metrics of how the impact can be measured. The metrics are super important. I believe that everything should be estimated in numbers. Numbers mean more than words. With figures at our disposal, we can effectively compare the impact of the different approaches. Moreover, we can track progress over time, enabling us to contrast our current situation with that of a year ago.

Metrics play a crucial role when communicating with non-technical managers. People from the business side don't care about code and tech stuff. They care about money. And all the number metrics can be calculated into money one way or another. It’s a good way to highlight your impact on the project's success.

I think the suggested metrics are the weakest part of the article, though. Please, post a comment if you have better ideas to estimate a developer's impact on a team’s performance.

Documentation

In my job, I follow the Rule of Two (invented by me 😄). It says

“If a colleague asks me a technical question about our project, and later another person asks me the same question, it makes sense to add an article/post in the project documentation with the answer, because most likely I will be asked about it again.”

The idea is that the next time someone has the same question, they will quickly find the answer in the project documentation. It saves their time and my time as well. Saved time = more money for business.

What things are worth documenting?

various guides. How to set up the local environment. Checklist for a good code review. How to perform typical product-related tasks. For instance, how to update the prices in your e-commerce product to test various corner cases. How to create a new user in the CRM.
code conventions and coding practices established on the project
details of your development process. DOD and DOR. The current approach for task estimation. Branching and releasing strategy
diagrams and graphs explaining dependencies between parts of the app
contact information of the important persons on the project and counterparts

What if my project has no documentation at all?

Well, you might be that guy who introduces it. As a pioneer, you will be even more valuable to the business.

Promote the documentation

It’s very important not only to write useful articles but also to let your colleagues know what you have done. After each documentation update write messages in the team chats and highlight them in daily meetings

it will make you visible to the project management and a team lead as a valuable contributor
your colleagues will remember that this piece of info exists in the documentation
searching in the chat history will give your colleagues a hint. Useful in situations like “I know that we have the answer, but I don’t recall where exactly”
it will encourage your colleagues to contribute to the documentation as well

Metrics

It’s difficult to come up with a general metric for the quality and usefulness of the project documentation. The number of articles and the views count don’t say anything. But in some cases, there are some figures to calculate

concerning a guide for the start-up of the local environment, we can measure how much time it takes for a newcomer to prepare the local machine and pick up the first task. We can compare the time taken for the old/new guide
documentation quality affects the time taken for the grooming and estimation of new features since the new things are connected to the old ones one way or another. We could measure the dynamics
regularly ask colleagues to estimate documentation quality from 1 to 10 (for instance every month or every quarter). The average can be considered as a satisfaction level

Choosing the right architecture, framework, and libraries

One of the most important topics. Let’s consider some cases from the team’s performance standpoint.

you are responsible for choosing the framework/library among several alternatives. You weigh the benefits and drawbacks of the things that are available and choose the one that will allow the team to write the code smoothly. The features and ecosystem of the chosen item allow the team to write less code relying on the out-of-the-box functionality
you choose the framework/library/design which is aligned with the team's skills and maturity level. It makes sense to prefer a simpler solution if the team's average level is low. But for the more skillful team, we can choose the more advanced approaches
apply the right design pattern in the right place to simplify code maintenance in the long run
you can introduce a library to simplify boilerplate tasks or reduce duplicate code. For instance, introducing tanstack query in a React app allows the team to use handy API to make network calls rather than write cumbersome and repetitive code for that
when working on the design, a skillful developer makes good assumptions about how the system might be extended in the future. Reasonable extension points can be added to the design. As a result, adding new features in the future will require small changes in the existing codebase
the system should be split into independent and isolated parts which know as little as possible about other parts of the app. Low coupling makes code changes more predictable and reduces the number of bugs

This topic can take the whole article, so I stop here. I think you got the point. The solid design and the right tools make the team very efficient.

Metrics

Scrum Velocity, or an average amount of work delivered in a month/quarter

Improve development experience

Introduce and propagate tools that make code writing and debugging easier and faster

IDE plugins for code highlighting, autocomplete, formatters, etc. In VScode the set of chosen plugins can be defined as a .json file located in the project repo to share with colleagues
scripts to automate routine tasks. For instance, in the JS world, we can introduce git hooks to automatically run linter checks before push rather than executing checks manually. Scripts to start multiple services at once are another good example
AI tools. Even a basic understanding of how to utilize the capabilities of AI tools like Ghat GPT or Claude positively impacts a developer’s performance. Figure out how to use it and teach your colleagues
Postman collections and Swagger can simplify API-related tasks. What arguments do that endpoints accept? No need to search through the codebase, it’s much easier to check Swagger instead

Metrics

we can calculate the average time a task stays in “In Progress”. Using the right tools will decrease the number
an average amount of work (story points, T-Shirt sizes, whatever) delivered in a month or quarter. Scrum Velocity.

Unit-testing culture

Plenty of bugs can be discovered in the early stage by unit tests. Organizing proper testing processes saves a lot of time and money in the long run.

I agree, it’s not applicable to some kinds of projects. Startups, prototypes, or projects with constantly changing requirements will not benefit from tests. But for all other projects, I would recommend introducing unit tests.

if the project has no unit tests at all, the adopter (you) will have to choose the technology/framework and write first 100 tests as an example and a starting point for the colleagues
in some cases, it’s more efficient to write tests only for the most important and fragile logic leaving the rest of the app untested. I have an idea of how to prioritize code for testing. Will share in another post
providing the mocks might require a lot of cumbersome code in some cases. It makes sense to use extra tools to simplify it. For instance, ng-mocks for Angular
you may write documentation and conduct some team-level master classes to share the knowledge and facilitate the testing adoption in the project

Metrics

an average number of bugs discovered in a sprint, month, or quarter
an average amount of work (story points, T-Shirt sizes, whatever) delivered in a month or quarter. Scrum Velocity.

Knowledge sharing

You can organize a call, master class, or regular meetings to share valuable project-related information with the team. It can be a screen sharing with the presentation or online coding. Whatever is suitable to efficiently share important ideas with colleagues.

Avoid speaking about general topics. Focus on things that your colleagues can apply to the project right now.

nonobvious but important things about domain logic or business processes. Sometimes developers focus on writing code but have limited knowledge of how the business works. The lack of knowledge of this kind might lead to bugs. It makes sense to shed some light on the business that stands behind the app to make the development mode aware and conscious.
tricky things about the tech stack you are using on the project. Especially if you implement some things in a nonstandard way or if the implementation differs from what the framework/libraries documentation suggest
any unclear topics highlighted on the retro or daily meetings are a good thing to clarify and share
encourage colleagues to participate in discussions and share information as well
make the knowledge-sharing sessions on schedule, say, once a week

Metrics

The regular knowledge-sharing sessions are supposed to boost the professional level of the team so we can estimate the dynamics in the development speed. Scrum Velocity, or an average amount of work delivered in a month/quarter

Other

It’s already too much for a post. So I briefly share other ideas on how to impact the team’s performance

mentoring. Take care of the less experienced developers in the team. Communicate with them directly to make them more efficient. Pair programming and code review have proved to be very efficient
right task distribution among the team members. A team lead should consider many factors when choosing a developer for a task
improving the code review culture. Sometimes people consider code review as a useless formality. That’s wrong since the code review is one of the essential quality gates

Streamlining Styles: CSS Variables for Maintainable Code

Mikhail Istomin — Wed, 21 Aug 2024 23:32:45 +0000

Here are some insights on how CSS variables can simplify support of reusable and customizable components. Regardless of the framework you're using, this approach remains framework-agnostic.

Sample component

Suppose I need to add the Progress Bar component to my UI kit. Using React as an example, here's a straightforward implementation.

import "./ProgressBar.css";

export function ProgressBar({percentage} : {percentage: number} ){
  return ( 
    <div className="progress-bar">
      <div className="fill"
        style={{ width: percentage + "%"}}
      />
    </div>
  )
}

And CSS to add colors and basic rules

.progress-bar{
  width: 200px;
  height: 20px;
  border: 1px solid black;
}

.progress-bar .fill{
  height: 100%;
  background: black;
}

It's black by default and looks like this

The component is supposed to be reused in various parts of my app. I expect that each consumer should have the flexibility to customize the color of the bar and its border to align with their specific needs and color scheme.

I expect consumers to provide their own CSS rules to override the default colors. For example, a consumer can write the following CSS to make the progress bar green within the upload section.

#upload .progress-bar{
  border-color: green
}
#upload .progress-bar .fill {
  background-color: green;
}

This customization works as expected.

Each consumer can adopt the same approach, and at first glance, it seems like a solid solution.

Problem

However, that way of customization comes with several drawbacks

❌ Future bugs: In the long run, the progress bar component will be updated or refactored. The customization will break if classes are renamed or the hierarchy of the tags is changed.
🤯 Consumer's cognitive load: Developers using my component need to examine its HTML structure to determine the necessary CSS rules for overriding the default values.
⚒️ Cumbersome customization code: Modifying both the color of the bar and its border requires writing two separate rules.

Of course, it's not a big deal for simple cases like our ProgressBar. However more complex components in a large UI kit, especially when used by many developers, can present significant challenges.

CSS variable as a solution

To simplify customization and mitigate these issues, we can leverage CSS variables.

In my sample component, changes are made only in the CSS file

.progress-bar{
  --progress-bar-color: black;
  width: 200px;
  height: 20px;
  border: 1px solid var(--progress-bar-color);
}

.progress-bar .fill{
  height: 100%;
  background: var(--progress-bar-color);
}

Note that I declare the variable --progress-bar-color to set the color. Consumers can now customize the component as easily as

#upload .progress-bar{
  --progress-bar-color: green;
}

With this new approach, let's revisit the list of customization problems

❌ Future bugs: As the developer of the progress bar, I can modify class names and the hierarchy as needed. However, as long as I apply the CSS variable correctly to the updated elements, color customizations made by consumers remain intact.
🤯 Consumer's cognitive load: Consumers no longer need to examine my component's code to customize colors. The CSS variable acts as an 'interface' or 'abstraction,' allowing them to simply set the desired color without delving into the implementation details.
⚒️ Cumbersome customization code: Now, a single CSS rule can customize both the fill and the border elements.

Extra benefit

In terms of color customization, relying on the CSS variable streamlines the application of a general color scheme. You can manage all color settings with a simple CSS file that defines variables across the entire page.

Now, all the colors on the page can be controlled from a single location. To update the colors for the entire page, simply replace the CSS variable definitions with a new set.

This approach also facilitates the implementation of features such as light/dark themes or user-defined color preferences.

Outcome

💸 Better maintainability: By adopting the customization through CSS variables, the codebase becomes more maintainable, making future updates simpler and less time-consuming.

👍 Reduced Bug-Prone Code: The clear separation between the component's internals and its customization interface minimizes the risk of bugs, as changes to internal implementation don't affect how the component is customized.

😀 The code gets easier to understand: The use of CSS variables makes the solution more intuitive and easier to understand. Developers can quickly grasp how to modify styles without delving into complex or opaque code.

♾️ Framework-agnostic: You can apply this approach everywhere since it relies on the browser features only.

Let's use Chrome Profiler to research obfuscated code

Mikhail Istomin — Tue, 21 May 2024 15:48:36 +0000

Imagine you want to figure out how some interesting feature on a website works. The challenge is that on modern websites, the client-side JavaScript code is usually minified and obfuscated, making the research quite difficult.

Check out how the Chrome Performance tool can help you study twisted JS code.

Problem

I’m currently working on the React Donut chart with a big focus on accessibility (A11y). As an example, I took this chart. The problem is that I could not figure out how they managed to make the donut navigable with the keyboard arrows. Is it some combination of ARIA attributes or JS code involved? A deep dive into the code was needed.

Of course, the JS bundles were obfuscated, so I decided to give the Profiler a try.

Profiling

The plan is the following

Start profiling
Do some actions on the website to trigger the code I want to research (press the keyboard keys in my case )
Stop profiling
Analyze the generated diagram.

The diagram has the Interactions section that tracks keyboard events. Let’s zoom and scroll to the Arrow Key event I need.

The bars on the diagram are clickable.

The summary of a selected bar is displayed below the diagram. If the selected bar represents a JS function, the profiler shows the link to the code. It’s amazingly helpful.

Here is the keyboard event handler that I was looking for.

Now, the Source tab shows me the exact function in the JS bundle that handles the event. The Profiles saved me a lot of time. No need to look through the huge codebase and obfuscated bundles. The function is located and I can proceed with my research.

Bonus

Also, the profiler shows the setTimeout statement which caused the function execution. Very helpful in some cases.

Angular DI: the genetic tokens pitfall

Mikhail Istomin — Fri, 15 Sep 2023 10:04:55 +0000

Intro

Recently I have discovered that using generic tokens for DI in Angular has an unexpected problem. It's not a critical issue, but rather something to be aware of.

In a nutshell, Angular and Typescript are not able to verify that a provided class really implements an interface, specified for a token.

App example

I declare the DI token PaymentServiceToken and provide the implementation on the module level.

export interface IPaymentService{
  getPaymentTypes(): void;
  authorizePayment(): void;
}

export const PaymentServiceToken = 
  new InjectionToken<IPaymentService>('Payment Service token')

@NgModule({
  ...
  providers: [
    {
      provide: PaymentServiceToken,
      useClass: PaymentService
    }
  ],
})
export class AppModule { }

Note that the token is initialised as a generic class to let the consumers know that the implementations for this token will implement the interface IPaymentService.

Then the service can be consumed by a component via DI like this

@Component({...})
export class PaymentComponent implements OnInit{

  constructor(
    @Inject(PaymentServiceToken) private paymentService:IPaymentService,
  ) {}

  // OR
  // private paymentService = inject(PaymentServiceToken);

  ngOnInit(): void {
    this.paymentService.getPaymentTypes();
  }
}

As a result I expect interaction with the injected service to be type-safe. In case of service misuse the errors should be thrown in compilation time.

At the same time I can provide other implementations for the same token on the module level without making changes in the components level. Something like

@NgModule({
  ...
  providers: [
    {
      provide: PaymentServiceToken,
      // useClass: PaymentService
      useClass: environment.production 
        ? PaymentService 
        : MockPaymentService
    }
  ],
})
export class AppModule { }

This approach is useful for some cases:

replace a real service with a mock version to avoid API calls
replace an old service with a new version having some extra features or refactoring
switching between implementations depending on configs or feature flags

Problem

To enable type checking I set up the token using the IPaymentService interface. But what if, by mistake, I provide the implementation that doesn't implement the interface?

export const PaymentServiceToken = 
  new InjectionToken<IPaymentService>('Payment Service token');

// DeliveryService  doesn't implement IPaymentService
class DeliveryService(){}

@NgModule({
  providers: [
    {
      provide: PaymentServiceToken,
      // useClass: PaymentService
      useClass: DeliveryService  // <--- wrong service !!!
    }
  ],
})
export class AppModule { }

The result is a disaster. I have no errors in compile time. But in runtime the TypeError is thrown and the app is ruined

Providing the wrong service is for sure the developer's fault, but Typescript and Angular failed to detect it during compilation.

Solution

Unfortunately, I haven't found a way to arrange proper type checking to verify that the token's implementation meets the token's interface.

providers: [
  {
    provide: PaymentServiceToken,
    useClass: PaymentService // <--- be extremely cautious here
  }
],

Moreover, there is an open issue in the Angular repo connected to the generic token's problem. Looks like there is no quick and simple solution.

The only thing I can suggest is to define a function with typing which verifies that the returned class implements the certain interface.

function getPaymentService(): (new () => IPaymentService) {
  return environment.production 
    ? PaymentService
    : MockPaymentService
}

@NgModule({
  providers: [
    {
      provide: PaymentServiceToken,
      useClass: getPaymentService()
    }
  ],
})
export class AppModule { }

We can improve the function getPaymentService to make it suitable for handling services with DI in constructors

function getPaymentService(): (new (...args: any) => IPaymentService) {
  return environment.production 
    ? PaymentService
    : MockPaymentService
}

Or rely on Angular's Type interface

function getPaymentService(): Type<IPaymentService> {
  return environment.production
    ? PaymentService
    : MockPaymentService
}

This solution will throw a compilation error if I mistakenly provide a wrong service

Honestly, I don't like this solution since you have to write such functions manually for each generic token. I just can't come up with something better than that.

I hope the more useful solution will be introduced in the next versions of Angular.

FAQ on Google Tag Manager (GTM) for non-GTM devs

Mikhail Istomin — Fri, 18 Aug 2023 18:09:16 +0000

Intro

GTM is a valuable tool in the modern WEB ecosystem. But several times I faced the following issue. The FE team works on a website and the dedicated GTM-focused team works on GTM for the same website. The problem is that GTM-related knowledge gets concentrated in the GTM team and the FE team is completely unaware of GTM features and approaches.

But at the same time, occasionally the FE team has to deal with bugs and unexpected behavior caused by GTM. In those cases lack of knowledge of GTM reduces the efficiency of the FE team.

I have composed a short FAQ for non-GTM FE devs who just want to grasp the basic aspects of working with GTM.

How GTM works

There are plenty of resources over the Internet explaining what is GTM and how it works. It will put it as simple as this.

The GTM specialist (the guy in the fancy hat to the right) logs in to the GTM admin panel.
He sets up the container and puts some custom scripts in it. Note that the container has a unique id (the red label).
The user (the guy in the sunglasses) opens the website. The HTML has the <script> tag responsible for initializing GTM. I call it "loader", the green brick in the picture above. The loader is added in HTML by the FE team. Also, the loader has a hardcoded container id. The loader makes a request to the Google servers to fetch the container by id.
Once the container is received, custom scripts added by the GTM guy are executed in the browser.

Actually, things are a bit more complicated. Variables, triggers, and tags have to be configured in the GTM container as well to make it work. I omit all those complex details in order to provide a straightforward explanation and keep the focus on the GTM basics.

Here I want to highlight two things:

Benefit: new custom scripts might be added to GTM without redeploying the main website.

Drawback: the FE team working on the website might be completely unaware of the release schedule of the GTM team. Even the purpose of GTM scripts may be not shared with the FE team.

How to disable GTM in the browser

Sometimes you might want to disable GTM on the website to compare UX and behavior with GTM and without it. It's possible to do this via an admin panel of your site, site configs, or via modifying the code. But there is a simpler way. GTM can be easily disabled in the browser.

In the devtools open the Network tab and filter JS requests by the 'gtm' keyword.
Then block the request https://www.googletagmanager.com/gtm.js?id=<CONTAINER_ID>. Here <CONTAINER_ID> is an arbitrary set of letters and digits. It's unique for your website.
That's it. After the page reload the block will be applied and the container will never be loaded by your browser.

Don't forget that the blocking works in your browser only.

You can unblock scripts anytime on the Network Request Blocking tab.

Visualizing dataLayer

One of GTM's key features is dataLayer. In a nutshell, it is a bus enabling interaction between scripts on the page and GTM scripts. The app's code push events in the dataLayer to notify custom scripts in GTM about user actions and other important things.

In some cases, it's essential for development and bug fixing to study published events and their payload. The easiest way is to type dataLayer in the browser's console. You will see the events as a simple array.

Not very handy, is it?

So I recommend using the Chrome extension Datalayer Checker instead. It has the elegant user interface and many useful features.

There is one trick. By default, Chrome extensions are disabled in incognito mode. So the Datalayer Checker will not be available in incognito which is not very useful. However, there is a special setting for that case. Go to the extension settings and enable it for incognito

Flaky unit tests in Angular

Mikhail Istomin — Tue, 08 Aug 2023 10:25:39 +0000

Introduction

A flaky test is an unstable test that randomly passes or fails despite no changes in the code or the test itself.

When unit tests are a part of the CI pipeline, flaky tests become the real problem. Tests unpredictably fail and every time devs have to spend precious time investigating and fixing. Also, flaky tests reduce confidence in tests in general.

In this article I want to research the nature of flaky unit tests in Angular and consider possible fixes.

Flaky test example

The simple component

Let's say we are developing a blog engine. The blog has the Backoffice, kind of an admin page, where authenticated users with admin permissions can set some settings, manage blog pages, etc.

Each page of the blog has a header. One of the header responsibilities is

render the Backoffice link if the current user is has admin permissions
hide the Backoffice link if the current user is not an admin

I'm going to implement it as simple as possible. You can find the code in Github Repo

Here is our typing



export interface User {
  name: string,
  isAdmin: boolean,
}

The service does nothing but storing the user data.



@Injectable({
  providedIn: 'root'
})
export class UserService {
  currentUser: User;
  constructor() { }
}

And finally the header component that consumes user data from the server and renders a link



@Component({
  selector: 'app-header',
  template: `
  <div *ngIf="user">
    <a class="backoffice-link" *ngIf="user.isAdmin" href="/backoffice"></a>
  </div>
`,
})
export class HeaderComponent implements OnInit {
  user: User;
  constructor(private userService: UserService) { }

  ngOnInit(): void {
    this.user = this.userService.currentUser;
  }
}

The tests for the simple component

Now I'm going to write some unit tests. Most of all, I want to cover <a>. It should be hidden for regular users, but visible for admins.

The mock for a regular non-admin user



import { User } from "./user.interface";

export const mockReguarUser: User = {
  name: 'John Doe',
  isAdmin: false,
}

And here are the tests. I guess, it's the most straightforward way to write unit tests for our case



describe('HeaderComponent', () => {
  let component: HeaderComponent;
  let fixture: ComponentFixture<HeaderComponent>;
  const userServiceStub = { currentUser: mockReguarUser }; // (1)

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [ HeaderComponent ],
      providers:[
        { provide: UserService, useValue: userServiceStub } // (2)
      ]
    })
    .compileComponents();
  });

  beforeEach(() => {
    fixture = TestBed.createComponent(HeaderComponent);
    component = fixture.componentInstance;
  });

  it('should not render Backoffice link for regular users ', () => {
    fixture.detectChanges(); // to trigger ngOnInit
    const link = fixture.debugElement.query(By.css('.backoffice-link'));
    expect(link).toBeFalsy(); //(3)
  });

  it('should render Backoffice link for admins users ', () => {
    userServiceStub.currentUser.isAdmin = true; //(4)
    fixture.detectChanges(); // to trigger ngOnInit
    const link = fixture.debugElement.query(By.css('.backoffice-link'));
    expect(link).toBeTruthy();
  });
});

Basically, I create a stub for the UserService, the mockReguarUser constant is used as user data (1). Then, I provide the stub to the component (2). The component consumes the service stub via DI engine, reads user data and render HTML according to user properties.

In (3) I check if the link is not displayed for a regular user. In (4) I change the isAdmin flag in mocked data to check how the header component handles admin users.

The tests look fine, but when I run Karma the strange things happen.

Initially, tests are green, but then I start hitting the reload button to rerun test suit. Surprisingly the particular test passes or fails in a random way. So, without any changes in the code I get different results many times. That's exactly what a flaky test is.

Researching a flaky test

First, let's figure out which test is unstable. The error message says

Looks like the the header component sometimes renders the Backoffice link for regular users, which it definitely should not do. I need to debug the test to find the root cause.

Unfortunately, the test result is unstable. It makes debugging too difficult. I need a reliable way to reproduce the test failure to be able to dive deeper. Here we need to learn about the random seed.

The seed

By default Jasmine runs unit tests in a random order. Random tests execution helps developers write independent and reliable unit tests. Basically it's what the I letter in F.I.R.S.T stands for. Read more about the FIRST stuff here

However this random order is controllable. Before running tests Jasmine generates a random number which is called the seed. Then the order of tests execution is calculated according to the seed. Also, Jasmine let us know which seed were used for the test run. Moreover, the seed can be provided via config to make Jasmine run tests in the same order over and over again.

That's what we can do to reproduce the failing test execution

1) Obtain the seed used for a failed test run. It can be taken from the browser's report

If a flaky test detected in CI and the browsers report is not available, the Jasmine order reporter can be used. The only thing is that you have to apply it beforehand. Then the seed can be found in logs of the CI pipeline



Chrome 115.0.0.0 (Windows 10) JASMINE ORDER REPORTER: Started with seed 05217

2) Once we know the seed that results in failing test order, it can be applied in Karma configs.



// karma.config.js
module.exports = function (config) {
  config.set({
    // ... other settings
    client: {
      jasmine: {
        random: true,
        seed: '05217' // <----------
      },
    },
  });
};

Now tests will be executed in the same order every time. In our case it means that the issue with the nasty unit test can be reproduced and investigated.

Studying the flaky test

We already discovered that the header components sometimes renders the Backoffice link for regular users. Let's figure out why. I simply put debugger in the ngOnInit method and run tests to check what's going on when the flaky test gets executed.

It turned out that the this.userService.currentUser.isAdmin is true when we run a test for a regular user. But the property is false in mockReguarUser we use in tests. How it becomes true?

The reason is the order of tests execution.



describe('HeaderComponent', () => {
  const userServiceStub = { currentUser: mockReguarUser };

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      providers:[
        { provide: UserService, useValue: userServiceStub }
      ]
    })
    .compileComponents();
  });

  // (1) 
  it('should not render Backoffice link for regular users ', () => {
    fixture.detectChanges(); // to trigger ngOnInit
    const link = fixture.debugElement.query(By.css('.backoffice-link'));
    expect(link).toBeFalsy();
  });

  // (2) 
  it('should render Backoffice link for admins users ', () => {
    userServiceStub.currentUser.isAdmin = true;
    fixture.detectChanges(); // to trigger ngOnInit
    const link = fixture.debugElement.query(By.css('.backoffice-link'));
    expect(link).toBeTruthy();
  });
});

When the test (1) executed before (2) everything is fine. But when (2) executed first we face the problem.

Test (2) sets userServiceStub.currentUser.isAdmin to true.
But userServiceStub.currentUser is a reference "shared" between both tests. So, when the test (1) is executed next, it works with the modified mock! Having isAdmin = true results is unexpected behavior and the test fails.

In the specific order of execution the test (2) becomes a criminal and the test (1) is a victim.

I think now it's clear why tests unpredictably failed/passed when executed multiple times in a row.

Fixing the flaky test

Cloning mocks

We need to make tests more isolated from each other to fix the problem. Let's create a new copy of the mock for each test. Note how I clone mockReguarUser in beforeEach section to ensure that each test gets a separate mock. At the same time the original mock is kept intact.



describe('HeaderComponent', () => {
  let component: HeaderComponent;
  let fixture: ComponentFixture<HeaderComponent>;

  // use the mock regular user
  const userServiceStub: UserService = { currentUser: {} as User };

  beforeEach(async () => {
    userServiceStub.currentUser = {...mockReguarUser} // clone mock
    await TestBed.configureTestingModule({
      declarations: [ HeaderComponent ],
      providers:[
        { provide: UserService, useValue: userServiceStub }
      ]
    })
    .compileComponents();
  });

Now a test can modify its mocks whatever it wants. The changes will not affect other tests.

Deep cloning

The trick with cloning via the spread operator works fine because the mockReguarUser has no nested objects. But the operator creates a shallow copy. It is not enough for more complex mocks, since the nested objects will be copy by reference and the data still be shared among tests causing the same problem.

Lodash cloneDeep is quite useful to handle complex mock cloning. It would be as simple as



userServiceStub.currentUser = cloneDeep(mockReguarUser)

Flaky tests in multiple components

Above we considered the relatively simple problem. The test that modifies mocks and the flaky test that unexpectedly fails due to the modifications both belong to the same component. And both tests sit in the same .spec.ts file.

In more complex apps this problem might be more complicated. Changing mocks made in suits for one component might cause test flakiness for other component. The components might even belong to different Angular modules.

In that case the investigation might be more difficult and solution probably will be more sophisticated. But the main idea is still the same. Most likely the problem can be fixed by applying cloning to prevent tests interaction via references in mocks.

Links

my Github repo with the example of a flaky test
Jasmine order reporter
Lodash cloneDeep

TypeScript: type compatibility vs duck typing

Mikhail Istomin — Mon, 17 Apr 2023 10:54:01 +0000

Intro

TypeScript is based on the structural type system. In a nutshell, the types of variables involved in some operations in your code should not be explicitly "identical". TypeScript considers the operation valid if types have a similar structure and follow the same shape.

I'm not going to provide a comprehensive article on type compatibility. The goal is to share with you a small research on a side-effect caused by this feature. Namely an issue with duck typing.

Compatible types example

First, let's look at the following piece of code

interface Pizza {
  name: string,
}

interface Beer {
  name: string;
  isDark: boolean;
}

let pizza: Pizza = { name: 'Gangsta Paradise'};
let beer: Beer = { name: 'Pirate Rage', isDark: true};

pizza = beer; // valid operation because Pizza and Beer are compatible

In the last line, we assign the Beer data to a variable having the Pizza type. Beer and Pizza are separate, completely independent interfaces. But TypeScript considers them as compatible and allows us to put new data in the pizza variable.

In a real app such an assignment might be an issue causing mistake or vice versa a smart trick based on good understanding of TypeScript features. For our research, the idea of this assignment is not important. We only care that it is valid for Typescript.

Duck Typing

Let's proceed with writing code for our app. Both Pizza and Beer get a new numerical property price. Also, in specific cases, we want to make some discount on products. Let's say 10% discount on pizzas and 20% on beers.

Following SOLID principles, we want to put the discount calculation logic in a separate function. The function is supposed to deal with all types of products. Something like this

interface Pizza {
  name: string,
  price: number,
}

interface Beer {
  name: string,
  isDark: boolean,
  price: number,
}

function getDiscountPrice(product: Pizza | Beer): number{
  const isBeer: boolean = //??? 
  if(isBeer){
    // beer gets 20% off
    return product.price * 0.8
  } else{
    // pizza gets 10% off
    return product.price * 0.9
  }
}

Pay attention to the isBeer flag. We want to run different logic for pizzas and beers. But how to find out, which type of product the function is dealing with?

If Pizza and Beer would be classes we could apply the instanceof operator. But unfortunately, they are interfaces and instanceof would not work.

Duck typing to the rescue! According to the interfaces we defined, Beer has the isDark property, but Pizza don't. So we can calculate isBeer like

function getDiscountPrice(product: Pizza | Beer): number{
  const isBeer = 'isDark' in product;
  if(isBeer){
    // beer gets 20% off
    return product.price * 0.8
  } else{
    // pizza gets 10% off
    return product.price * 0.9
  }
}

Note
It would be better to wrap isBeer into a type guard. But let's keep it as it is for simplicity

Issue with duck typing for compatible types

Let's put together the getDiscountPrice function and the type compatibility case we studied in the beginning.

interface Pizza {
  name: string,
  price: number,
}

interface Beer {
  name: string,
  isDark: boolean,
  price: number,
}

let pizza: Pizza = { name: 'Gangsta Paradise', price: 100 };
let beer: Beer = { name: 'Pirate Rage', isDark: true, price: 100 };

pizza = beer;                          // (1)

const price = getDiscountPrice(pizza); // (2)
console.log(price);                    // price is 90

function getDiscountPrice(product: Pizza | Beer): number{
  const isBeer = 'isDark' in product;
  if(isBeer){
    // beer gets 10% off
    return product.price * 0.9
  } else{
    // pizza gets 20% off
    return product.price * 0.8
  }
}

After the assignment in line (1) the variable pizza is still typed as Pizza. Given the code of getDiscountPrice we might expect that the calculated discount price will be 80 (since any Pizza is supposed to get 20% off).

But actually, the calculated price will be 90. We have 90 because the pizza data happened to have the isDark property which is unexpected for our duck typing approach. You can run this example and check the result in TypeScript Sandbox

You can rightly say "Wait a minute, the code works as expected. You, as a developer, put some strange data in the pizza variable in the line (1). Don't blame TypeScript"

Well, I know, I agree with you. That's the developer's fault. But the TypeScript let me do it, no compilation error was thrown. Type compatibility system considers code like (1) as valid.

It might be a problem in a real-world big app. Imagine that pieces of code (1), (2), and the function declaration for getDiscountPrice sit in different modules. The data flow and modules interaction is complicated. But the TS compilation reveals no errors. Valid type compatibility might result in a tricky issue if the assignment on (1) is made by mistake.

Conclusion

TypeScript is a great tool. Its type checking is able to detect mistakes in code making the codebase safer. But TypeScript is not able to reveal all the flaws. For me, one of the most severe drawbacks of Typescript is the fact that the border between "detectable" and "non-detectable" mistakes is sometimes blurred.

I mean the code above is absolutely valid from the TS perspective. And still, it has some unexpected, error-prone behavior.

Know the tools you use. I obtained deeper understanding of TypeScript when studying this case. I hope it will be helpful for you as well.