DEV Community: Marcelo C.

How I leveraged Claude Code skills to help me migrate Cypress 16 deprecations in time

Marcelo C. — Fri, 03 Jul 2026 15:05:58 +0000

Have you ever stared at a deprecation warning scrolling by in your terminal and thought "eh, future me will deal with that"? We all have! But here's the thing about future you: he eventually shows up. And in my case, he showed up wearing a shirt that said Cypress v16, holding a changelog, and pointing at the line that says Cypress.env() will be fully removed.

Warning in 15.10. Gone in 16. And sprinkled across every config, page object, and spec file in the massive E2E repository I maintain at my work monorepo. Configs, support files, fluent page-object chains — everywhere.

So let's get to the grain here: even though Cypress has a great documentation about it, I didn't want to execute a find-and-replace job manually, and I also wanted to move fast. So instead of pasting a prompt into a chat window forty times, I did something better: I turned the migration playbook itself into a Claude Code Skill — a reusable, self-triggering unit of expertise that lives in my machine and outlives this one migration.

Why Cypress.env() had to die

If you've written E2E tests, you know Cypress.env(). Synchronous, available everywhere, dead simple.

And that simplicity was exactly the problem: it hydrated the entire env object straight into the browser runtime. Every value. Including the ones a given test never reads. Your admin password, your API tokens — all of it, sitting in browser-accessible memory, one window inspection away, in every single spec.

Easy to use? Absolutely. A credential-leaking surface baked into your test runner? Also absolutely.

The v16 API splits the concern into two deliberately asymmetric halves:

cy.env(['key']).then(...) — asynchronous, resolved Node-side, strictly read-only. Values never touch the browser context until you explicitly consume them inside the callback. This is where credentials and tokens live now.
Cypress.expose('key') — synchronous, a drop-in replacement, but only for values you've explicitly opted in to exposing via a new top-level expose: block in your config (a sibling to env:, not nested inside it).

Notice the design: the safe path is ergonomic, the sensitive path is deliberately awkward. That asymmetry is the whole point.

The strategy: teaching the AI a classification heuristic

Doing a mindless regex sweep across thousands of files would have been fast — and catastrophically wrong, because every single call site needed a classification decision first. So instead of doing the work 3,000 times, I did it once: I encoded a strict heuristic and let Claude Code apply it mechanically.

The heuristic:

Does the value contain a password, a username paired with a password, or any secret? → It's sensitive. It stays in the env: block and every read site gets rewritten to the async cy.env([...]).then(...) form.
Is it a feature flag (our idp_active, xbrl_active), a locale, a timeout, a base URL fragment? → It's public. It moves to the expose: block and the read becomes a one-line swap to Cypress.expose().

Rule 2 is boring. Rule 1 is where the migration earns its war stories.

From prompt to Skill: making the knowledge permanent

The Cypress team actually ships an official starting point for this — the remove-cypress-env-usage prompt from the Cypress AI Toolkit:

It's good. But a prompt in a library has two problems: you have to remember it exists, and you have to re-paste it every session. A Claude Code Skill solves both. A Skill is just a folder with a SKILL.md — a markdown file with a small YAML frontmatter (name + description) followed by the instructions. Claude Code scans the descriptions on every task and auto-loads the skill when the context matches, so the moment I say "migrate this spec off Cypress.env", the whole playbook is already in its head. No copy-paste, no drift between sessions.

~/
└── .claude/
    └── skills/
        └── cypress-v16-migration/
            └── SKILL.md    # frontmatter + the full migration playbook

But here's the important part — I didn't just copy the official prompt into a file. I transformed it, layering in everything the generic version can't know about my repo:

The classification heuristic above, with our real flag names (idp_active, xbrl_active) as worked examples, so it never has to guess what "sensitive" means in our codebase.
The command-queue traps you're about to read below, written as explicit "never do this / always do this" rules — because I hit them once and never wanted the AI to reproduce them.
Our repo topology: all four active config files that need the expose: block and the final flag flip, so nothing gets a partial migration.
The verification sequence (grep → flag → CI) as a mandatory checklist the skill must run before declaring victory.

The generic prompt is the textbook; the Skill is the textbook annotated by someone who took the exam. And since it's a personal skill (kept local, not committed to the repo), I can keep sharpening it without a PR review debate about my prompt-engineering style. 😄

Where the plot thickens 🕵️

You might be thinking: "Ok, this is still just a glorified find-and-replace with two output templates. What's the big deal?"

The big deal is the Cypress command queue.

Swapping a synchronous read for an asynchronous one inside a fluent page-object chain changes the execution semantics of everything around it. Take our global cy.login() command — the one every spec in the codebase depends on:

// BEFORE — synchronous, credentials resolved at enqueue time
Cypress.Commands.add('login', () => {
  const user = Cypress.env('username');
  const pass = Cypress.env('password');

  cy.session([user], () => {
    loginPage.visit().typeUser(user).typePass(pass).submit();
  });
  cy.goToHome();
});

Naive migration attempt:

// BROKEN — do you see it?
Cypress.Commands.add('login', () => {
  cy.env(['username', 'password']).then(({ username, password }) => {
    cy.session([username], () => {
      loginPage.visit().typeUser(username).typePass(password).submit();
    });
  });
  cy.goToHome(); // 💥
});

Looks reasonable. It's a time bomb. Here's why:

Trap #1 — silent reordering. Cypress enqueues commands synchronously as JavaScript executes, but runs them later. That trailing cy.goToHome() gets enqueued before the .then() callback ever fires — and any non-Cypress code after the block (variable assignments, page-object state mutations) executes immediately, before the credentials even exist. No error. No warning. Just your test quietly doing things in the wrong order. This is, by far, the easiest mistake to make in the entire migration, and grep will never find it for you.

Trap #2 — cy.session() needs a resolved ID. The session ID argument is evaluated at call time, not at run time. You can't hand it a promise or a pending value. So the entire cy.session(...) invocation — not just its setup callback — has to move inside the cy.env().then() callback:

// CORRECT — everything downstream of the credentials lives inside the callback
Cypress.Commands.add('login', () => {
  cy.env(['username', 'password']).then(({ username, password }) => {
    cy.session([username], () => {
      loginPage.visit().typeUser(username).typePass(password).submit();
    });
    cy.goToHome();
  });
});

And here's the payoff of years of discipline: because every login flow was registered through Cypress.Commands.add, this entire architectural shift happened behind the command boundary. Thousands of cy.login() call sites across the specs didn't change by a single character. The abstraction held. This, kids, is why you wrap your login logic in a custom command instead of copy-pasting it into 5k tests (ask me how I know 😉).

The final lockdown 🔒

A migration you can't verify is just a migration you hope worked. Cypress v16 gives you a kill switch for exactly this: allowCypressEnv: false. With it set, any surviving Cypress.env() call becomes a hard runtime failure — not a warning, a crash.

My verification sequence:

grep the branch for live Cypress.env( calls → zero hits (comments and the migration doc don't count).
Flip allowCypressEnv: false across all four active config files — no partial lockdowns, no "we'll enable it on that config later."
Ship it to CI and let the full E2E stages be the judge.

Green across the board. And here's the subtle part that made it safe: we only changed the read API, never the injection mechanism. Every CI secret, every --env CLI override, every pipeline variable kept flowing exactly as before — they just land in a place the browser can no longer see by default.

The commit log tells the real story 📜

Want proof that the Skill approach actually moved fast? Read the git history like a detective:

First PR:
Tue 11:27  Migration to v16
Tue 12:11  [E2E] Migration to Cypress v16 architecture
Tue 14:44  Updating Cypress env flag
Wed 16:04  Updating Typescript types

Fixing login issue:
Thu 10:23  [E2E] Fixing idp override with v16 Cy migration

Look at Tuesday morning: the bulk rewrite of the entire architecture landed in about 45 minutes, between the first pass and the structured [E2E] commit. That's thousands of call sites, classified and rewritten, in less time than a sprint planning meeting. Two hours later, allowCypressEnv: false was already flipped — the kill switch armed on day one.

Then comes the honest part, the part most migration posts conveniently forget: the long tail. Wednesday was TypeScript's turn — cy.env() returning a promise-like of a keyed object meant the old string-based typings had to be reshaped, so the compiler could catch a mistyped key at build time instead of CI catching it at run time.

And Thursday? Thursday delivered the one trap the Skill didn't know about yet — Trap #3, the runtime override. One special spec family runs against a different server with IDP/SSO enabled, and it used to flip that on with a runtime Cypress.env('idp_active', true) in a beforeEach. In v16, idp_active now lives in the expose: block — and exposed values are resolved from config, read-only at runtime. The old setter didn't crash; it just silently did nothing, and the spec calmly logged into the wrong server. The fix was moving the override where v16 wants it: into the spec-level config override, resolved before the test runs, not mutated during it.

Guess what happened next? That trap went straight into the SKILL.md. The next migration Claude Code runs already knows about runtime overrides of exposed values. That's the whole point of a Skill over a prompt: it compounds.

The takeaway

A breaking-change migration at this scale isn't a refactor problem, it's a classification + execution-semantics problem. The AI didn't make the hard decisions — the heuristic did. The AI just made applying that heuristic across thousands of files not cost me a month of my life. And by encoding it as a Skill instead of a throwaway prompt, every trap I hit made the next migration cheaper.

What about you? Have you ever had to architect a massive, breaking-change migration across thousands of tests? What was the trap that almost got you — and did your abstractions hold when it mattered? Leave me a comment, I'd love to hear!

How I stopped declaring login in each of my 5k tests

Marcelo C. — Fri, 27 Feb 2026 19:26:44 +0000

Have you ever encountered a testing codebase that many portions are repeated over and over? We all have! Of course, I could be talking about DRY princples (Don't Repeat Yourself), but lets keep that aside for now and focus on a Cypress trick up it's sleeve that can go unnoticed for many senior devs: the global hooks.

And what do I mean by "global" hooks? They're called like that because you only declare them once and they're applied to all your tests instantly.

So let's get to the grain here: when installing Cypress it already comes with a file at created at cypress/support/e2e.<ts|js> level. This is usually where you declare some important commands imports that your E2E testing will need to access and run properly.

But it's also responsible for adding let's say before, beforeEach, or after, afterEach hooks that will be applied by all your tests. This can be responsible for login hooks, clean-ups to the database after the tests run, screenshots resolutions configuration -- a million of possibilities here.

I guess that the "global hooks" makes more sense now, right?

The challenge

At my workplace, I encountered the command to login, called cy.login, declared in each of the 5.634 tests that we have. For a while it bothered me a lot, because I always wanted to remove this codelines, and make my life easier with a simple e2e.ts file that handled all existing and new login logic for future tests.

But if I knew how it worked, why didn't I just do it already?

Becuase, for the first time (for me), I was dealing with a really complex system: a big chunk of the legacy tests ran with testIsolation: false. That meant that they only login once, and the it blocks don't load a new baseURL after each one is done. They do it all in one session.

Because? Well, that would be another story, so let's just accept their done like that for "system requirements" at the time.

Ok, so I basically needed:

before() → cy.login() beforeEach() → cy.login() only if testIsolation is true

Easy right? Not yet. The complexity resides because different spec families have different needs: different credentials, different environments, different session strategies, and different testIsolation settings.

There are two needs here to login:

Which login method?

cy.login(): Default specs with standard app with default credential.
cy.loginDemo(): Presentation specs with different environment, likely SSO or different credentials.
Custom (own login): Need specific credentials or totally different E2E tests outside enviroment.

When to login? (before vs beforeEach)

This is driven by Cypress's testIsolation setting:

testIsolation: true — Cypress clears browser state (cookies, storage) between each test. Session is lost → must re-login before each test.
testIsolation: false — Cookies persist across tests in the same spec → login once is enough.

Now, here is where the plot thickens. I had to declare folders, tests, paths that needed to be skipped (or not), because on the same folder I had testIsolation: true/false. So, follow me along:

1. Legacy specs (/legacy/ folder)

before() → skip entirely
beforeEach() → only call cy.login() if testIsolation is true

Legacy specs use specific credentials. If the global before() called cy.login() first, cy.session() would cache the wrong credentials, causing 500 errors when the spec then tries to login with different ones. So global before() is completely skipped. In beforeEach(), it only re-validates when state is actually cleared (testIsolation: true).

2. Training portal specs (/training/ folder) + Custom login specs

before() → skip entirely
beforeEach() → skip entirely

These specs manage their own login end-to-end. The global hooks stay completely out of the way. Some tests likely test login flows themselves or use role-specific credentials.

3. BEFORE_LOGIN_DEMO_SPECS

before() → cy.loginDemo() + cy.goToHome()
beforeEach() → skip (already logged in)

Login once per spec, reused across all tests. These are demo/presentation specs where re-logging in per test would be slow and unnecessary.

4. BEFORE_EACH_LOGIN_DEMO_SPECS

before() → nothing
beforeEach() → cy.loginDemo() + cy.goToHome()

Similar to above but login is repeated per test because testIsolation: true, the state is cleared between tests, so they must re-login each time.

5. LOGIN_DEMO_SPECIAL_SPECS

before() → nothing
beforeEach() → override baseUrl + timeout + idp_active env, then cy.loginDemo()

This spec runs against a completely different server, with an IDP/SSO active flag and a much longer timeout. The config must be set before each test because test isolation may reset Cypress config state.

6. Default specs (everything else, A.K.A the MOST important logic!)

before() → cy.login()
beforeEach() → cy.login() only if testIsolation is true

Standard app, default credentials. Login once in before(), then beforeEach() only re-validates the session if Cypress actually cleared it (testIsolation: true). If testIsolation is false, cookies persist and calling cy.login() again would navigate back to home, breaking any test that expects to be on a specific page.

The key insight: why before AND beforeEach?

You're asking "are you mental? why on earth would you declare login TWICE?", basically because:

before() → establishes the initial session (runs once)
beforeEach() → re-validates/restores the session if testIsolation cleared it

For specs with testIsolation: false, beforeEach() is a no-op (or returns early) because the session is still alive. For specs with testIsolation: true, beforeEach() must re-run the login to restore the cleared session — but it uses cy.session() internally which caches credentials.

Here's a sneak peek of how my e2e.ts file looks in it's (hopefully) final form:

And I basically removed the cy.login function from more than 1k files in my codebase, leaving me or any other engineer to not worry anymore about the login being declared at test level, it handles everything for me now, as it should.

What about you? Have you ever encountered a challenging and complex test codebase to deal with? What was the most difficult change you had to make? Leave me a comment, I would love to hear!

How to validate tables, rows or any content of an Excel file using Cypress

Marcelo C. — Fri, 31 Oct 2025 11:43:24 +0000

At the company I work for, we already have many test cases to validate a key behavior of our SaaS, which through the user downloads a table as an Excel file of the information needed. But there was a need to validate some edge cases, in which we also needed to validate that the content corresponds to what the table showed.

This would mean that Cypress needs to deterministically validate rows, numbers, names and even colors inside the Excel file set by our user flows. After some research, we basically came upon two Node.js libs: @e965/xlsx and exceljs.

While @e965/xlsx is mostly used for data content validation, as in validating a JSON rows straight from the sheet - exceljs is more focused for style assertion, meaning assertions like “is A1 light-green?”. All right, so now we could split keeps tests readable and fast.

Configuring @e965/xlsx library

First, wire up the configuration in Cypress. Head off to Node with cy.task(). It’s the official way to run filesystem code from Cypress tests: register tasks in setupNodeEvents and they’ll return values back to your spec.

Remember to also import the package on the config file:

//cypress.config.ts

const xlsx = require('@e965/xlsx');
...
...
...
      on('task', {
        async readExcelByPattern(pattern: string, timeoutMs = 15000) {
          const re = new RegExp(pattern);
          const end = Date.now() + timeoutMs;

          while (Date.now() < end) {
            const files = fs.readdirSync(downloadsDir).filter(f => re.test(f) && !f.endsWith('.crdownload') && !f.endsWith('.tmp'));

            if (files.length) {
              const { fullPath } = files
                .map(f => {
                  const fullPath = path.join(downloadsDir, f);
                  return { fullPath, mtime: fs.statSync(fullPath).mtimeMs };
                })
                .sort((a, b) => b.mtime - a.mtime)[0];

              await sleep(200);

              const wb = xlsx.readFile(fullPath);
              const sheet = wb.Sheets[wb.SheetNames[0]];
              const data = xlsx.utils.sheet_to_json(sheet);
              return { fileName: path.basename(fullPath), data };
            }

            await sleep(300);
          }

          throw new Error(`File .xlsx taht matches /${pattern}/ not found on "${downloadsDir}" inside ${timeoutMs}ms`);
        },

You can see that readExcelByPattern is the task we should call to validate the content like rows, tables and any information inside the Excel file. You can then define it inside your test context and methods (or define it globally over commands.ts if you plan to use it in many tests), but for a single test it should look something like this:

//my-testing-context.ts

  @step('Read downloaded excel values')
  readExcelDownloadedFile(
    pathToFile: string = 'excel_export/bugs/',
    fixture: string,
    fileName: string
  ): ExportPrintableReportContext<TParent> {
    cy.fixture(pathToFile + fixture).then((expected: any[]) => {
      cy.task('readExcelByPattern', fileName).then(({ data }: { data: any[] }) => {
        expect(data.length, 'Table length').to.equal(expected.length);
        expected.forEach((expectedRow, i) => {
          const actualRow = data[i];
          Object.entries(expectedRow).forEach(([key, expectedValue]) => {
            const actualValue = actualRow[key] === undefined ? null : actualRow[key];
            expect(actualValue, `Row ${i} - Column "${key}"`).to.equal(expectedValue);
          });
        });
      });
    });
    return this;
  }

As you can see it's pretty straight forward, it calls for a JSON file inside 'fixtures/excel_export/bugs/' that already has the values you want to validate and should be equal to the Excel file and executes a forEach of the Table length, and each row, which already awaits for a value.

And this is how it would look inside a test:

import { testContext } from '@/my-testing-context'

const testingContext = new testContext();

describe('example of reading excel files', => ()
  it('case 1', () => {
    testingContext.readExcelDownloadedFile('excel_export/bugs/', tk, 'Excel.xlsx');
  });
});

Basically it checked 171 rows of the file content and succeeded in 40 seconds.

For the second part of this tutorial, I'll expand on how to validate Excel colors as well. Happy testing!

How to get most out of cy.prompt() - 6 tips and tricks for your new AI tool!

Marcelo C. — Thu, 09 Oct 2025 13:54:06 +0000

I know, I know, Cypress has just announced a game changing feature with cy.prompt() that is going to change the way we test - or at least approach how we think of it. You're going to use Natural Language all the way to test your new app? Read through my recommendations then!

As a Cypress Ambassador I was lucky enough to be using cy.prompt for the past weeks and here are a few tips to make your testing and usage go a bit smoothly.

1) Start your phrase with the action or assertion you want

Instead of giving it an instruction like:

When the page loads, check that the header is seen and then click on Create button

Would be better to:

Wait 8 seconds for the page to load
Assert that the header is visible
Click on create button

Now Cypress will translate your instructions more easily - a hardcoded wait, followed by an assertion, followed by a click.

2) Try to separate instructions

The previous step gave it away already! Cypress prompt works as any other LLM - give clear instructions of what you want to do and it'll have a better chance to execute it.

Do not mix assertions, with force clicks, with reloads in the same line of action! The prompt needs to go through, so in a way try to act as a prompt engineer and step by step you'll get there.

3) You can have up to 20 steps for each prompt you execute

20 is the limit, ok. But that doesn't mean that you need to have 20 steps each prompt. Also, the more steps you add, the prone it is to ask for clarifications or make mistakes.

Think of it as this: each plain English text line you introduce is an abstraction layer, right? Do want an over-complicated test, or a easy to read through, understandable (for non-developers specially) test?

Lesser is better in some cases!

4) Leave some tests in prompt in order to validate flaky behavior

Got a new feature? Want to avoid brittle in your E2E test? Want to check for any weird behavior here and there? Then cy.prompt is your way to go! You can always leave your tests in plain English to see if the BDD/TDD behavior stays the same.

Remember: it works in both local and CI - but it only supports Chrome or Chromium browsers (Edge/Electron). Any others are out (sorry Firefox!). Leave it a few days or weeks in your CI in prompt scenario and see what happens.

5) Portability first?

For me any test that is written in plain English has a natural advantage over each other. It doesn't need to be refactored into any other programming language. So if you already know that the application you're working now is starting to be ported into another modern framework, leave your tests in prompt format. Your devs will appreaciate!

6) It's always cached

Another advantage with cy.prompt is that once it runs, it will cache the steps in order to avoid LLM interaction. But if you change one line in your prompt - wait 15 seconds instead of 8, for example - it will execute all over again.

Remember this to focus on speed and reliability in your tests!

How Cypress will revolutionize the use of AI in testing with cy.prompt()

Marcelo C. — Thu, 09 Oct 2025 10:28:22 +0000

Cypress has become the go-to testing framework for SDETs and QA engineers to validate modern web apps. It’s fast, reliable, and backed by a mature ecosystem—both in software updates and excellent documentation. Add to that the vibrant community building powerful plugins and extensions, and it’s clear why Cypress dominates the testing landscape.

Cypress is taking a bold step into AI-powered testing with the upcoming cy.prompt(). Unlike typical AI integrations that act as external copilots or rely on general-purpose MCP-style assistants, cy.prompt() adds the intent (what we want) built directly into the testing workflow.

This means no context switching, no juggling between an IDE plugin and your test runner. Instead, Cypress allows you to describe your intent in plain English, and the AI automatically generates selectors, actions, and assertions right inside your test.

It’s a shift from writing tests line by line to guiding your tests conversationally. Think less about cy.get() or cy.click() and more about telling Cypress what you want verified, letting the framework translate that into executable code.

Here’s a video demonstration of cy.prompt() in action:

This is the code that I used in the validation:

And here is what the prompt suggests of code locators right after is executed:

Also, you can leave the prompt as it is and push to your CI/CD pipeline:

With cy.prompt(), Cypress is no longer “just” a testing framework—it’s stepping into the AI-assisted development era. For SDETs and QA engineers, this means faster authoring, smarter locator handling, and easier onboarding for teams.

The possibilities of cy.prompt()

Cy.prompt focus on the intent: what we want, not how do do it. It's a great tool for non-developers, or anyone who doesn’t want to dive deep into app implementation.
Imagine writing the BDD (Behavior Driven Development) acceptance criteria directly into the test. You'll have the best of both worlds here, BDD criteria that is understood by all stakeholders (Project Managers, Product Owners), and the code being executed in the background.
TDD (Test-Driven-Development) is also covered for the developers. Imagine developing a feature until is ready and, step by step (word by word, line by line) it start to pass. Until is ready for deployment.
Portability is here: Need to refactor your project? Move from one programming language to another? Don't need to change a thing in your tests written in plain English, they can be easily shared, exported, or integrated across different systems.
Also, another great benefit here are the self-healing tests, they’re more resilient to changes in the DOM or selectors. This feature could fundamentally change how we approach automation.

The future of QA is not just code—it’s collaboration between AI and testers.

What are your thoughts?

Share, comment or connect with me directly in LinkedIn!