DEV Community: Andy

Strange Magic of Typescript Intersections

Andy — Sun, 28 May 2023 08:09:52 +0000

During a recent code review, I stumbled upon an intersection type that appeared not to be fully unbderstandable to me. Intrigued by its usage, I embarked on a journey to delve deeper into the inner workings of TypeScript intersections. In this article, I will share my findings and shed light on how intersections can be used and which gotchas you may face.

What is intersections?

In a nutshell, TypeScript intersections offer a means of combining multiple types into a single cohesive type. By merging various types, intersections enable we can create composite types that inherit the properties and methods of their constituent types.

An intersection in TypeScript is defined by using the & symbol between the types to be merged. Let's explore a simple example to illustrate this concept:

type Student = {
  id: string;
  name: string;
};

type Settings = {
  theme: 'dark' | 'light';
  isLocalTimezone: boolean;
};

type StudentsSettings = Student & Settings;

const settings: StudentsSettings = {
    id: '1',
    name: 'Andy',
    theme: 'dark',
    isLocalTimezone: true
}

In the above example, we define three distinct types: Student, Settings, and StudentsSettings. The Student type represents basic student information such as name and id, while the Settings type encapsulates application settings for this student like theme and local timezone if preferable. Utilizing the intersection operator (&), we combine these types to create the StudentsSettings type.

As demonstrated, the StudentsSettings type inherits properties from both Student and Settings, enabling the creation of an object of this type that incorporates properties from both constituent types. This facilitates the representation of an employee object enriched with extended address information. Simple, right?

How we can use it?

Theoretically, we can use intersections for extending existing types. Suppose you have a foundational type that encompasses a common set of properties, and you need to create specialized types that inherit those properties while introducing additional ones. Everything will be clear and effortless, right?

The answer is not that easy!

Pitfalls of the intersections!

First of all, let's define what will really happen when we're trying to intersect some types. Let's start with primitive types:

type A = string & number;

const a: A = 1; // Type 'number' is not assignable to type 'never'.

We get never, which indicates the values that will never occur. I understood it in the beginning that string and number have no intersections. Initially I had this picture in my head:

Continuing our exploration into the realm of TypeScript intersections, let's delve deeper by examining two additional examples:

type B = { name: string } & { name: number };
type C = { name: string } & { name: string | number  };

const b: B = { name: '1' } // Type 'string' is not assignable to type 'never'.
const c: C = { name: '1' };

In the first example, we define the type B as the intersection of { name: string } and { name: number }. However, when we attempt to assign a value to b, we encounter an error: "Type 'string' is not assignable to type 'never'." This occurs because the intersection between a string and number results in an empty set of possible values, represented by the never type.

In the second example, for type C the resulting intersection is simply { name: string }. Since both constituents already contain string as a possible value for the name property, the assignment of { name: '1' } to c is valid.

We have only one problem with this understanding - it's misleading because intersections don't work this way all the time.

Rethinking sets theory

The official documentation says us:

Intersection types are closely related to union types, but they are used very differently. An intersection type combines multiple types into one.

This is exactly what we had in the first example, but it works till the moment you have the collision of the types and they are overriding each other. When the collision happens TS will decide who will survive.

type D = { name: string } & { name: string | number; id: number  };

const d: D = { name: '1', id: 1 };

This case will pass the check and we predicted what we get as a result, but we used the wrong logic there. The official documentation doesn't help a lot with this understanding, because I see no answer to the question: "How TS combines types in such cases?"

We can make even more unclear examples:

type E = { name: string } & Record<string, number>;
type F = { name: string } & Record<string, 'foo' | 'bar'>;

const e: E = { name: '1', id: 1 } // Type '{ name: string; id: number; }' is not assignable to type 'E'.
const f: F = { name: 'foo', id: 'bar' } 
/*
Type '{ name: string; id: "bar"; }' is not assignable to type 'F'.
  Type '{ name: string; id: "bar"; }' is not assignable to type 'Record<string, "foo" | "bar">'.
    Property 'name' is incompatible with index signature.
      Type 'string' is not assignable to type '"foo" | "bar"'.
*/

In the first example, we define the type E and e variable. However, when we attempt to assign the object { name: '1', id: 1 } to the variable e, a type error occurs "Type '{ name: string; id: number; }' is not assignable to type 'E'." Unlike the previous examples, we do not encounter the never type. This behavior may seem a bit peculiar, considering the previous illustrations.

Moving on to the second example, we define the type F as the intersection of { name: string } and Record<string, 'foo' | 'bar'>. At first glance, it appears to work as expected. However, there is an error that arises, leading to confusion. The expectation is that having either 'foo' or 'bar' should be acceptable from the perspective of the { name: string } type. However, the presented type creates a misleading impression of possible data assignments, which is incorrect. I found no way to create proper data for this type. So this type is equal to the first one when creating proper data is not possible.

Conclusion

These examples demonstrate that the behavior of intersections can become increasingly intricate. It one more time underscores the importance of thoroughly understanding TypeScript intersections and using them in proper cases, not as a universal tool for making types in the app.
During writing this post I found several questions on StackOverflow, where people expressed confusion regarding the behavior of the intersections' behavior and had the same wrong assumptions that I had. This observation indicates that I'm not the only one who was confused by TS intersections
Consequently, this realization has led me to utilize intersections in exceptional scenarios where alternative options are limited and I clearly know what I'm doing.

Thank you for reading. Any feedback is welcomed :)

Mocking data for Integration tests in React

Andy — Sat, 11 Mar 2023 15:37:33 +0000

Recently I had to write a lot of unit and integration tests with jest and react-testing-library for my front-end project. We increased the code coverage from 50% to 90%. I can only say that it was challenging, but one of the problems I faced was mocking some hooks, external functions, and components.
Below you can find the list of solutions I used and the conclusions I came to. If you know a better way to do the same — go ahead, I would be glad to hear your suggestions

Should I test my code?

Let's clarify this point first because I know that some developers have doubts about it.

I think testing your code not only makes sense but is also super-useful if you would like to build a reliable and maintainable application.
Testing your functions and components will help you to catch bugs early in the development process and ensure that they work as expected under different scenarios. It can also help identify issues with component dependencies and ensure that they are properly isolated and reusable.
So if you have any hesitation about it — throw it away, it will not harm you, on the contrary, It will significantly boost the understanding of your code!

The first test

Let me define the technologies that will be used in the examples below. For development are used React(18.2), Typescript(4.9.3) and Jest(^27) with React Testing Library(13.4.0) for testing. Now we can start coding.
Imagine you have component like this:

const Users = () => (
  <Page testId={Id.UsersPage} className={classes.usersPage}>
    <PageTitle title="Users" testId={Id.PageTitle} />
    <UsersList testId={Id.UsersList} />
  </Page>
);

We don't have any logic here, so we will check if the components are visible after we render them:

it('Users is rendered correctly', () => {
  render(<Users />);

  expect(screen.getByTestId(E2eId.UsersPage)).toBeVisible();
  expect(screen.getByTestId(E2eId.PageTitle)).toBeVisible();       
  expect(screen.getByTestId(E2eId.UsersList)).toBeVisible();  
});

Ok, so now we know that all the parts of the Users component are rendered. Theoretically, we can test the markup instead, but it doesn't bright a lot of fruit because such a test will be fragile and will not check the business logic we might have in the components.
In real life, the test won't be that easy because within the UsersList we probably have a request for the list of users the following way:

import { getUsers } from 'api';

const UsersList = observer(() => {
  const [users, setUsers] = useState([]);
  ...
  useEffect(() => {
     getUsers().then((response: User[]) => {
       setUsers(response)
     });   
  }, []);
  ...
});

Looking at the component above, for testing Users we need to mock API call here and jest.mock will allow us to do that easily.

jest.mock('api', () => ({
  getUsers: () => Promise.resolve([])
});

I'm not going to check if this function was called, but if it's necessary I have to use jest.fn instead my current implementation.

Testing custom hooks

In terms of mocking the most frequent case for me, it is a custom hook that I used for getting data from the store. I selected MobX for the state management and use useStore hook to request and manipulate data. Here is the updated version of the UsersList component.

const UsersList = observer(() => {
  const {
    usersStore: { getUsers }
  } = useStore();

  useEffect(() => {
    getUsers();
  }, []);
  ...
});

Let's try to mock this hook and return data:

import { MOCKED_USERS } from 'mocks';

jest.mock('stores/store.context', () => ({
  useStore: () => ({
    usersStore: {
      getUsers: jest.fn(() => Promise.resolve(MOCKED_USERS))
    }
  })
}))

If you try this, you will see that it doesn't work.

First of all, you can't use variables that are defined outside of the jest.mock function. To solve it, you can try to hack jest.mock by using nested functions, and in some cases, it works.
However, I would not rely on the such a solution and it won't help when you need to return the different datasets for different tests(Except if you want to use switch...case). So, after some experiments I came up with another idea and just imported getUsers function in the test file and re-define mockImplementation the following way:

(getUsers as jest.Mock).mockImplementation(() => { 
  return Promise.resolve(MOCKED_USERS)
});

The only problem is ... it doesn't work as well!

But the reason is different — every time component is re-rendered we execute the hook function and return a new jest mock function. So when I re-defined it within the test, it was a different function.

So, we need to find a way of returning the same function all the time. Fortunately, it's not that difficult, we only need to define the mock function outside the hook function.

jest.mock('stores/store.context', () => {
  const getUsersMock = jest.fn();

  return {
    useStore: () => {
        usersStore: {
          getUsers: getUsersMock
        }
    }
  }
});

Let's take a look at what we will have in the test after all changes

it('triggers getUsers when component is mounted', async () => {
  const {
    usersStore: { getUsers }
  } = useStore();

  (getUsers as jest.Mock).mockImplementation(() => { 
    return Promise.resolve(MOCKED_USERS)
  });

  render(<UsersList />);

  await waitFor(() => expect(screen.getByTestId(Id.UsersListContent)).toBeVisible());
  expect(getUsers).toBeCalled();
});

Testing external hooks and dependencies

After we cracked the problem with hooks the rest cases don't seem difficult. Below I will go through pretty common situations when you need to mock external dependencies of the components. Imagine we have component:

import { useAuth0 } from '@auth0/auth0-react';
import TreeView from 'components/TreeView';
import { notification } from 'antd';

const SecurePage = observer(({ children }: SecurePageProps) => {
  const { isAuthenticated, user } = useAuth0();
  const onError = () => notification.open(
    type: 'error',
    message: 'Something went wrong'
  });
  ...
  return (
    <div>{isAuthenticated ? children : <LoginPage onError={onError} />}
    <TreeView />
    </div>
  );
});

To cover both authorized and unauthorized user scenarios, I will first mock auth0. Then, I'll add a mock implementation of the useAuth0 hook in each of the tests. This approach will allow me to simulate different results and ensure that the app behaves correctly in each scenario.

jest.mock('@auth0/auth0-react');
...
(useAuth0 as jest.Mock).mockImplementation(() => ({
  isAuthenticated: true,
  user: {}
}))

So, we covered both cases when the user is authorized and not. But we probably would like to test showing notification on the error as well, so I will mock antd and verify notification.open is executed:

import { notification } from 'antd';
...
jest.mock('antd');
...
expect(notification.open).toBeCalled();

One more thing that might be helpful in some cases is mocking components. I have TreeView in the SecurePage component. Let's say I don't want to test it, I can mock it the following way:

jest.mock('components/TreeView', () => null)

Be careful we skipped the testing the TreeView component entirely. I can only recommend it when the TreeView component has already been tested separately or when you have a specific reason to omit it from certain tests.

Conclusion

Mocking data for your tests usually seems like something simple and developers don't pay a lot of attention to it. But in reality, it's a crucial technique for ensuring the trustworthiness and stability of your tests. Bad mocks can give you a deceptive sense of reliability, so you need to be careful.
On contrary, using mock data properly can help you isolate and debug problems more quickly and effectively. Having it in mind, you will create integration tests that are robust and accurate, and deliver high-quality user experiences for your customers.

Easy UI testing with Cypress

Andy — Fri, 30 Dec 2022 08:12:16 +0000

When I ask developers how they test their applications with UI usually the answers are related to unit-testing or to testing some specific components. I know that some of the managers even add a particular value of the code coverage as a requirement. They hope it will reduce amount potential problems and the code will be more reliable with coverage near to 100%. However, the truth is not that pleasant.

Unit tests don’t test application behavior that sees end users and doesn’t prevent all the bugs

If you want to be sure that the application is working as it was written on requirements you might consider verification of particular user scenarios. For me, a user scenario – is the described step-by-step user behavior in the application. Simply speaking, requirements one or another way describes how to achieve user goals by using the application. So when I’m checking a specific function in the unit test it’s not the same for sure, because the user works with the system on a much higher level.

What to do in this case? The answer is – writing the tests that will check requirements, not only classes and functions, I mean acceptance or e2e tests. In my case requirements are described in the form of the user scenarios with Gherkin and I will write acceptance tests

For you, it might be written a different way but the main idea is the same and I will show you how easy it can be for you.

Getting started

I’m going to use Cypress(version 12.2.0) for writing the tests for my UI and I don’t want to set up the whole backend and deal with creating specific users for testing purposes. I will use these tests in the pipeline of my front-end project. So the installation is pretty simple

npm i --save-dev cypress

We need to run cypress the first time to have all the config files created, so let’s do that

cypress open

It will open the interactive cypress application that will guide you and create the config and cypress folder in the repository. If you haven’t used cypress before I highly recommend accepting the suggestion from cypress about creating examples of the tests.suggestion from cypress about creating examples of the tests.

This way you will have a lot of examples that will help in the initial step.

Start writing tests

We have plenty of examples produced by cypress, but let’s do something on our own, to check how difficult it is. I’ve chosen npm.com UI and autocomplete on this page. But I’m not going to just check the autocomplete work on this page, but isolate UI and mock API. Let’s add one more file npm.autocomplete.cy.js in the e2e folder and write our test

describe('NPM tests', () => {
  beforeEach(() => {
    cy.visit('https://www.npmjs.com/');
  });

  it('Npm autocomplete test', () => {
    cy.intercept('GET', 'https://www.npmjs.com/search/suggestions?q=step', [
      {
        name: 'step',
        scope: 'unscoped',
        version: '1.0.0',
        description: 'Test',
        date: '2017-01-06T21:16:57.341Z',
        links: { npm: 'https://www.npmjs.com/package/step' },
        author: { name: 'John Smith', email: 'test@test.com', username: 'test' },
        publisher: { username: 'test', email: 'test@test.com' },
        maintainers: [{ username: 'test@test.com', email: 'test@test.com' }],
      },
    ]).as('getResults');
    cy.get('input[name="q"]').type('step');

    cy.wait('@getResults');
    cy.get('ul[role="listbox"] li').should('have.length', 1).should('have.text', 'stepTest1.0.0');
  });
});

First of all, I’ve added describe block and added cy.visit in beforeEach function, which will open npm.com before every test that we have below. The test itself is in it block and in the beginning, we’re intercepting the request that the page will do when we type something in the search field. Pay attention that we’ve defined the alias getResults

Next, cy.get is used to select the input field and type the word "step" there and cy.wait will help us to wait for our mocked response. Now it’s time to check what we have in the search results with should function and everything look correct.

We haven’t reviewed the features of the cypress here but has wonderful documentation with a huge amount of examples, so it won’t be a big challenge. Probably remember that I have requirements in the Gherkin form, so let’s make it possible to use Gherkin for writing tests.

Testing Gherkin

Cypress has a lot of officially supported plugins and I’m going to use one of them cypress-cucumber-preprocessor (version 15.0.0) for Gherkin support.

npm i --save-dev @badeball/cypress-cucumber-preprocessor

Additionally, I will install @bahmutov/cypress-esbuild-preprocessor (version 2.1.5) preprocessor, because it has no particular requirements and the config is the smallest.

Let’s update the cypress.config.ts with the new configuration. Pay attention I switched to TypeScript, it’s a pretty easy move with cypress because it’s described in the documentation. Don’t forget to add tsconfig.json if you go this way. Anyway it’s optional, so if you don’t need it – stay with the JavaScript.

This is the config, after the updates:

import { defineConfig } from "cypress";
import createBundler from "@bahmutov/cypress-esbuild-preprocessor";
import { addCucumberPreprocessorPlugin } from "@badeball/cypress-cucumber-preprocessor";
import createEsbuildPlugin from "@badeball/cypress-cucumber-preprocessor/esbuild";

export default defineConfig({
  e2e: {
    specPattern: "**/*.feature",
    async setupNodeEvents(
      on: Cypress.PluginEvents,
      config: Cypress.PluginConfigOptions
    ): Promise<Cypress.PluginConfigOptions> {
      // This is required for the preprocessor to be able to generate JSON reports after each run, and more,
      await addCucumberPreprocessorPlugin(on, config);

      on(
        "file:preprocessor",
        createBundler({
          plugins: [createEsbuildPlugin(config)],
        })
      );

      // Make sure to return the config object as it might have been modified by the plugin.
      return config;
    },
  },
});

Now we’re ready to re-write our test to Gherkin, so let’s create a .autocomplete.feature file and add the following scenario there.

Feature: NPM search

  Scenario: Searching the package
    Given I've opened the npm.com
    When I typed a phrase in the search field
    Then I should see the results in the dropdown menu

If you run tests after this step they will fail, because we haven’t defined the steps definitions, so it’s time to define it. By default, you can place steps definitions wherever you want in the e2e folder, but if you had many tests it would be a mess. I use subfolders within the e2e so for our case it will be e2e/autocomplete/autocomplete.ts

import { When, Then, Given } from '@badeball/cypress-cucumber-preprocessor';

Given(`I've opened the npm.com`, () => {
  cy.visit('https://www.npmjs.com/');

  cy.intercept('GET', 'https://www.npmjs.com/search/suggestions?q=step', [
    {
      name: 'step',
      scope: 'unscoped',
      version: '1.0.0',
      description: 'Test',
      date: '2017-01-06T21:16:57.341Z',
      links: { npm: 'https://www.npmjs.com/package/step' },
      author: { name: 'John Smith', email: 'test@test.com', username: 'test' },
      publisher: { username: 'test', email: 'test@test.com' },
      maintainers: [{ username: 'test@test.com', email: 'test@test.com' }],
    },
  ]).as('getResults');
});

When('I typed a phrase in the search field', () => {
  cy.get('input[name="q"]').type('step');
});

Then('I should see the results in the dropdown menu', () => {
  cy.wait('@getResults');
  cy.get('ul[role="listbox"] li').should('have.length', 1).should('have.text', 'stepTest1.0.0');
});

As you can see we’ve split our test into several steps, but it works the same way.

One of the benefits of such splitting is the possibility to re-use the steps. In this case, we’ve added one more scenario that starts with the same step we don’t need to define the Given once again in the scope of this feature. So, in the end, we write less code and some of the tests might be literally written in .feature files.

Scenario: No results is present for invalid value
    Given I've opened the npm.com
    When I typed incorrect search phrase
    Then I see no results

Additional configuration and reporting

The most important thing about the tests is to make it to help you in your day-by-day work. For this, it has to be easy to use and it should be integrated with the process of development. Let’s add a couple of scripts in our package.json

"scripts": {
    "cy:open": "cypress open",
    "cy:run": "cypress run"
  },

cy:open – is opening the interactive mode for writing and debugging the tests

cy:run – will run all the tests and generate the report

You will say here “Wait a moment, have we configured reporting?”. You’re goddamn right, we didn’t, but we will fix it in a moment by adding one more section to package.json Here is my config:

"cypress-cucumber-preprocessor": {
    "messages": {
      "enabled": true,
      "output": "report/cucumber-messages.ndjson"
    },
    "html": {
      "enabled": true,
      "output": "report/cucumber-messages.html"
    },
    "json": {
      "enabled": false
    }
  }

You can read a bit more about configuring the cypress-cucumber-preprocessor in the documentation, if you need to customize something.

Ok, let’s try to run the tests and see what we have

In the real project, I have a similar report for every merge request and it’s deployed separately for the main branch, so the management team can easily check what scenarios are covered by the test and what’s missing.

Conclusion

As you can see adding acceptance tests for testing your UI is not a difficult task and can be introduced relatively quickly. Of course, you need to cover at least the most important user scenarios to make such tests useful. The main goal of it is to catch issues as early as possible. Then in case, your changes broke something it will have been noticed immediately. It would be much better if you found the issue not on the production on Friday, right?!

I haven’t considered the cypress itself in detail in this article, because it wasn’t the goal. However, I can give you a couple of hints I’ve found after practicing it for some time:

use the cypress commands for the things that are used often in the code. I mean some standard selectors, creating mocks or interceptors. It’s strictly specific to the project, so I can’t tell you what exactly to put there, but you will find out yourself, after writing several tests
don’t use classes or ids for selecting UI elements, use special data attributes for it. It will prevent situations of breaking the tests accident by changes in the styles.
don’t create scenarios that are checking only the UI or some specific labels. Acceptance and e2e tests are expensive and if you test everything there it will take significant time not only for writing and supporting tests but for execution. You can use an integration test instead to cover this part.
Gherkin is a good option, but it’s not necessary. If your team doesn’t have requirements written in Gherkin – you can start without it. It’s much better to have less expressive tests than have no tests at all

Thank you for reading and good luck with testing!

Improve your stories with Gherkin!

Andy — Mon, 19 Sep 2022 06:59:37 +0000

I've been working as a developer for some time and it happened a way, I've never used Gherkin before the winter of 2022. In this post, I will try to tell you why using Gherkin can boost your understanding of the product, improve its quality, and why you should at least know what it is.

What's Gherkin?!

Let's start with the definition. Gherkin is a language for describing features with human-friendly syntax. In a more formal way we can define it the following way:

Gherkin is a line-oriented language that uses indentation to define the structure(similar to YAML or Python)

How does it look?

Each line starts with a keyword that defines the following block or text which can be the definition of a feature, scenario, or description of the step. Let's consider a small example:

Feature: Door functionality

  # The first scenario is describing success case
  Scenario: Open the door
    Given the user is staying in front of the door
    When the user turns a door handle
    And pulled the door
    Then the door is opened

Using it is pretty simple. "Feature" is describing feature block, that contains several Scenario blocks and every scenario has steps, that describe user behavior with "Given, When, Then" schema.

"Given" should contain the initial situation description or actions we need to perform to make possible to make "When" step. It can be launching the app, opening the page or modal. In the example above user should stay in front of the door to start opening it.
"When" contains action or actions that should be performed to get some result or change the application state. User make two actions in the example - turning the handle and pull the door to make it work.
"Then" describes the result or state that user sees after performing previous steps. It is opened door in the example above, but it might be some result, let’s say 42.
"And", "But" these two steps can be added to any of the step above or to all of them to enrich step with more details
There are some other keywords in Gherkin, that can simplify scenarios, but I don’t use it for now, because they are needed for simplification of the tests scenarios and not that necessary if you’re just writing story description

More about Gherkin you can read in cucumber documentation

One language for the whole team

The main benefit of using Gherkin is the possibility of communication between technical specialists and product people with the same language. It seems like a small thing, but in reality, it has a significant impact on the development process. It’s not a coincidence that the picture below causes nervous laughter from anyone who has even been involved in software development.

Standardizing of task's descriptions allows you to improve its quality and avoid bad descriptions, like this one “We've discussed it on Skype” or vice versa several pages with vague descriptions of the desired functionality. With standards, developers are not needed to delve into heterogeneous task descriptions to understand exactly what kind of behavior they need to add to the system. They will just know what to expect. At the same time, the product owner will easily describe the desired behavior in the form of a set of steps, he/she is doing it all the time anyway, just in a different manner.

Of course, Gherkin will not insure you from mistakes in the task’s descriptions, but with proper usage and involving the whole team in supporting it, improvement will be really significant. Scenarios might be easily verified by any member of the team during the grooming(refinement) or just before development by imaginary applying it to the application.

Testing

The next big advantage of the Gherkin descriptions is the possibility of direct usage in the acceptance tests. You can just create .feature file in the project and copy scenarios from the story. These files can be used by such tools like Cypress, Cucumber.js or jest with jest-cucumber plugin(the plugin doesn’t support the reports in the latest version, I hope it will be fixed soon, condition on 19-10-2022). So after copying scenarios you need to implement the steps, described in Gherkin and tests are ready.

In our team, we’re trying to follow TDD principles during the development, so we consider scenarios as acceptance tests for our app in all the cases. For our product owner, it’s a possibility to be sure that the feature is not only implemented but covered by tests.

That's not all!

Single language for the team and testing sounds serious enough, doesn’t it? However, it's not all benefits that you can take from Gherkin. I listed several items that seem valuable from my point of view:

you see the size of the tasks immediately. By opening the task you will see a number of scenarios in it and this is a kind of mark of complexity. Of course, the scenarios themselves will not describe the complexity of the implementation, but in the majority of cases, the task with 10 scenarios will require more time than a task with only one.
easiness of splitting the tasks. After several written stories, you will start seeing when you have too many scenarios in the story. Additionally, during the work over the description I'm grouping scenarios by some principle, so later if I decided to split it would be not that difficult. For developers, it’s also pretty clear, if they see 50 scenarios be sure they will request to split the story
everyone can write and update the story descriptions. Many times in my past I faced the situation when I found new details that are not written in the description. Usually, it required some communication sometimes a pretty long, but now I'm just updating the story and asking PO about reviewing my changes. The same way it works for technical stories, they look much more understandable with Gherkin because it won't allow you to go to deeply into technical details

Real-life example

Let’s consider a more realistic example than opening the door to feel more confident with Gherkin. Imagine we have an online shop that requires a promo code system. Let’s say that the back-end is implemented and the online shop contains features of adding purchases to the cart and payment. Let's write a story for this feature:

Story
  As a shop user
  I want to have the possibility to apply promo codes to my purchases
  So that I can buy products at lower prices

Now we have the goal of the task from the user's point of view and anybody who opens this task can easily find the answer to the question "Why are we doing it?”

Time to write scenarios. Scenarios might be written before the grooming or refinement meeting and in that case, we're discussing them, clarifying all the details, updating them if it's needed, and estimating. In case we don't have scenarios in the task, we're writing them during the meeting.

Feature: Promo code functionality 

Scenario: Promo code field is available on the cart page
  Given I opened the root page of the shop
  And I've added something to the cart
  When I opened the cart page
  Then I see on the right side the promo code field
  And "Apply" button is visible

Scenario: Apply promo code
  Given I opened the cart page with some purchases
  When I specified a correct promo code in the promo code field
  And clicked "Apply" button
  Then I see the notification that promo code is applied
  And total price is recalculated
  And promo code field is empty
...

This is not all scenarios, but the main idea should be more or less clear. We actually have to add a scenario for statuses of the "Apply" button, if the code field is empty. Additionally, we have to describe what will happen in case of invalid codes. I think if you tried to write these scenarios you would face the repetition of some steps in several or all scenarios. Don't be afraid it is fully fine and even good because in tests you don't need to write code more than once. Moreover, you can use Background and Scenario Outline for simplifying you tests , but make sure that tests framework supports these keywords.
You can say: “Ok, but what if I need to change the scenario during the development?”. The answer is simple - do it. The main idea of whole this process is to make stories available for editing by team members. Just ask PO to verify changes after you've done them. Sometimes corrections might be applied in the review stage, but it's usually related to grammar or wording.

We're writing tests right away, so scenarios will be used immediately and the majority of changes will appear in the first hour of development. Often the only changes we made is adding new scenarios for covering things we missed.

What else can you do to improve your stories?

Despite the fact that I consider Gherkin useful for development in general, there are some tips and tricks that I found while working with it, maybe it will be helpful:

The goal of the task should be written before the scenarios and all of them should be consistent. We use “As a … I want … so that …” for describing goals(you can see it in the example above). It's an important thing because every person on the team will understand why you're going to do this feature
Scenarios should not be too long, ideally, you will have only "Given", "When", "Then" steps. If this is not possible - add "And", "But" steps with additional details, but don’t overuse them (I would recommend not more than 3 such steps) to not lose readability
Steps have to be short clear and unambiguous. I will not promise, that it will be easy to achieve, sometimes you will have to add some notes outside the scenario to make it more clear, but you need to pursue it. I use the Notes section for adding additional details, but again it should not be huge.
Every scenario should have only one "When" step. It's necessary to make your scenarios atomic and simple to comprehend. If you need to describe several related actions you can add several "And" steps to your "When", but make sure that it's not different scenarios. if you have doubts - split it into several scenarios.
I would not also recommend using the exact values of labels button names etc in Gherkin scenarios(not tests) if it's not necessary from the Business perspective side. Such values may make your scenarios brittle, after any changes, they become not actual anymore even though the behavior itself was not changed. If we're talking about the UI, from my experience, it changes regularly and such items as labels, messages, and button names are not good anchors. After some time scenarios with them won't be understandable to anyone. First of all, scenarios have to describe the application behavior, not the exact implementation. If you need to check that table has specific columns - just add the verification of it in the implementation of the steps and add a generic phrase to the scenario like this "Table contains proper columns". More about it might be found in this article - better gherkin

Potential problems

In our team, Gherkin was adopted fairly easily, but it doesn't mean that approach will work in such a way for every team. Badly written scenarios are hard to read and difficult to support. It might become a huge pain relatively quickly. You mustn't allow it to happen. It's better to spend more time writing fewer but good scenarios.

Writing and using scenarios it's a skill, that depends on the whole team. You need to have a really good level of communication between team members and aspirations for a better understanding of the business goals otherwise you won't be able to use Gherkin benefits.
Describing some of the features might be really challenging because it's difficult to place all the details in scenario form. For such cases, we're using Notes and splitting the work into simple chunks.

Conclusion

Gherkin helped our team with an understanding of our products and improved their quality and made our communication more productive. I can easily say which user scenarios are covered with tests in our projects and every developer can. We're kind of sharing the same vision of product across the team and that allows us to move faster with fewer gotchas.
At the same time, I would not consider this approach a silver bullet, because it won't solve problems instead of you. It requires some discipline and several iterations of enhancement to make this approach really useful, but if you asked me - I would answer "It's worth trying!"