How To Get Started With Cypress Debugging

Using debugger in Cypress

Sometimes, when running tests, especially large and complicated ones, it could be very difficult for you to know what exactly went wrong and which part of the code failed to do as expected.

The debugger is very helpful in these kinds of situations. You can stop the test execution at any time and look up the application’s state to see if everything works as it should.

If you have been in the development field for quite a while, you might already know how to use the debugger in other parts of your applications.

However, if you are unfamiliar with Cypress debugging, using the debugger in Cypress might work differently than you think it should.

Even though using a debugger in Cypress is quite similar to using the debugger in other parts of your application (like your front end), it doesn’t work the same way.

You can only use the debugger in Cypress inside the.then() function. Otherwise, it does not work the way it is supposed to.

Let me explain…

Let’s see what goes wrong if we add the debugger outside a .then() function.

it('should work as usual', () => {
  cy.visit('https://ecommerce-playground.lambdatest.io')
 
  cy.get('[data-test="some-selector"]')
  debugger // Doesn't work
})

Running the test:

As you can see, the debugger will pause the test to run before the test even starts.

If you have used a debugger before, your expectation might be that first, the cy.visit() and cy.get() functions should run and complete, and then the debugger should pause the test, but that’s not the case.

So, what happened there? Why did the test pause immediately?

Based on the Cypress documentation, it is said that the commands in Cypress are all “Asynchronous,” so what does that mean?

In Cypress, when a set of commands are invoked, they get enqueued for later, and after the whole, it() block is finished, Cypress will run all of the commands in order.

it('hides the thing when it is clicked', () => {
  cy.visit('/my/resource/path') // Nothing happens yet
 
  cy.get('.hides-when-clicked') // Still nothing happening
    .should('be.visible') // Still absolutely nothing
    .click() // Nope, nothing
    .should('not.be.visible') // Definitely nothing happening yet
})
 
// Ok, the test function has finished executing...
// We've queued all of these commands and now
// Cypress will begin running them in order!

Based on this information, now you should know why the debugger pauses the test immediately instead of pausing the test after the other two commands have finished running.

The two commands that come before the debugger are only being enqueued to run later, but the debugger, which is not a Cypress command, will not be enqueued and will be invoked immediately.

Causing the test to pause immediately before the other commands can be executed in the queue.

That’s why you should always use the debugger inside the .then() function. This will ensure that the Cypress command will run and complete, and then the debugger will pause the execution of the tests.

Now, let’s re-write the test again, but this time using the debugger inside of the .then() function

it('should only pause when the cy.get() function finishes executing', () => {
  cy.visit('https://ecommerce-playground.lambdatest.io/')
 
  cy.get('h2')
    .should('exist')
    .then($h2 => {
      debugger
    })
})

In this section of this tutorial on Cypress debugging, the debugger will only pause the test if the h2 element exists in the DOM since we are saying that the debugger should only pause the test only if the h2 element exists in the DOM.

Now, let’s run the test.

As you can see, now the debugger only pauses the test after it gets the element and makes sure that the element does exist in the DOM; otherwise, it will throw an error.

Let’s fail the assertion on purpose and see if the .then() function runs or not

it('should only pause when the cy.get() function finishes executing', () => {
  cy.visit('https://ecommerce-playground.lambdatest.io/')
 
  cy.get('[data-cy="some-selector-which-does-not-exist"]')
    .should('exist')
    .then($h1 => {
      debugger
    })
})

Running the test:

As you can see from the screenshot above, the debugger will never pause the test since the assertion has failed and the .then() block did not have a chance to be executed.

Using the .debug() method for Cypress debugging

The .debug() method is a shortcut for Cypress debugging, which you can chain to every other Cypress command wherever in your tests.

It will expose some details in the browser’s console when the .debug() function triggers:

• Command Name: the name of the last command invoked before the .debug() triggered.
• Command Args: the list of arguments passed to the last method before the .debug() invocation.
• Current Subject: a new variable will be created inside the browser with the name subject, which you can interact with using the browser’s console.

The subject variable is the return value of the Cypress command and can be interacted with by using the browser’s console.

Let’s try it out. In this example, I will get the first h2 element on the page.

it('should pause the test by using the .debug() command', () => {
  cy.visit('https://ecommerce-playground.lambdatest.io/')
 
  cy.get('h2')
    .should('exist')
    .debug() // debugger
})

Execution:

In this case, the subject variable represents the return value of the cy.get('h2') command, which means the subject variable is an h2 element.

When we run the subject.text(), this will give us the text content inside the h2 element.

Using stack trace for Cypress debugging

A stack trace shows a list of method calls that lead to the exception being thrown, together with the filenames and line numbers where the calls happened.

Cypress also translates the stack trace so that the actual source file is shown along with its line numbers instead of the file loaded by the browser.

The Cypress console could be very useful whenever you face an error, luckily, most of the Cypress errors are well explained, and you can easily understand what is going on by simply reading the stack trace.

You can also integrate it with the VSCode IDE to jump right to where the error was thrown and shown in the stack trace.

For example, let’s introduce an error by trying to get an element that doesn’t exist in the DOM

it("should throw an error", () => {
  cy.visit("https://ecommerce-playground.lambdatest.io/")
 
  cy.get("some-selector-which-does-not-exist").click()
})

Running the test:

As you can see, Cypress does a great job explaining why and where the error happened.

If you click the “View stack trace” button, you can see the file name in which the error was thrown.

If you click on it, it will ask you to select your IDE to open it. You can choose VSCode from there. If you can not open it, go to the Settings tab -> Device Settings -> External Editor -> Visual Studio Code or your preferred IDE.

Now, if you click on the link on the stack trace dropdown, it will automatically open that file and navigate to that specific line where the error was introduced.

This is a very good feature of Cypress UI automation tool, helps you easily spot errors and locate where the error happened.

Note: Run End-to-End Cypress tests on the cloud grid. Try TestMu AI Now!

Using .pause() command for Cypress debugging

Cypress exposes another command which helps in pausing the test execution and making it easily debuggable, you can then manually start the test again and resume executing Cypress commands.

The .pause() command is also a Cypress chainable and can be chained with any other Cypress command.

Cypress.pause() example of use

it("should pause the test", () => {
  cy.visit("https://ecommerce-playground.lambdatest.io/")
 
  cy.get("input[name='search']")
    .first()
    .should("exist")
    .and("be.visible")
    // pauses the command execution
    .pause()
    .type("Iphone 12")
})

In this section of this tutorial on Cypress debugging we are getting the input elements in the DOM, which has a “name” attribute of “search,” and we are selecting the first one by running the .first() command.

And we are asserting two assertions on them; after that, we are typing something inside of the input, but just before typing the input, we have run the .pause() method.

The code will run the first three commands and pause before running the fourth and final commands.

Running the test:

As you can see, a new button has appeared on the top of the Cypress console, and also, we can see in the final output of the logs it is written - pause, which is caused by our pause command.

Now, if we press the play button, the test will resume, and the commands will resume executing again.

Resuming the test execution:

The test will resume, and the last command will then be executed. Finally, the text will be typed inside of the search input.

How Do AI Agents Debug Cypress Tests?

AI agents debug Cypress tests by reading real run data instead of guessing from your source code. Cypress Cloud MCP is a remote Model Context Protocol server that hands an AI assistant your run statuses, failure details, error messages and stack traces.

• Cloud MCP access: the agent queries Cypress Cloud over HTTP for run status, failure details and flaky test reports, so it answers from the run that actually failed.
• Test Replay links: the agent returns the Test Replay URL for a failed run, so you open the recorded DOM, console and network state instead of re-running the spec locally.
• Assistant coverage: any agentic environment that supports remote MCP servers can connect, including Claude, Cursor, GitHub Copilot and the OpenAI Codex CLI.
• Flaky test triage: the agent ranks specs that pass and fail on the same commit, which is the question a single stack trace cannot answer.
• No auto-repair: Cloud MCP explains a failure, it does not rewrite a selector, so the fix still lands in your spec file by hand or through your coding assistant.

For teams working on flaky tests or brittle selectors, Cypress AI adds self-healing mechanics on top of Cloud MCP, surfacing root causes from stack traces and suggesting fixes without leaving the development environment.

Conclusion

In this Cypress debugging tutorial, we have discussed the best ways to debug Cypress tests easily. Cypress UI testing is an excellent framework for validating your front-end applications. It provides us with many great features to debug our test suites easily.

Here are the different ways to debug your Cypress tests:

• Using a debugger.
• Using .debug() Cypress command.
• Using the stack trace.
• Using logs console.log() and cy.log().
• Using the Cypress .pause() command.
• Using AI agents through Cypress Cloud MCP.
• Using TypeScript to reduce type errors.