If you’re using Cypress for end-to-end testing and wondering how to work with objects and convert them into JSON using cy.wrap, this article is just for you. Understanding cy.wrap is essential for writing efficient Cypress tests, especially when dealing with complex data structures. In this guide, we’ll break down everything you need to know about cy.wrap, its use cases, and how you can use it to convert objects into JSON in Cypress. Whether you’re a beginner or just need a quick refresher, we’ve got you covered.
What is cy.wrap in Cypress?
Cypress is one of the most popular tools for automated testing, and cy.wrap is an important function in its toolbox. But what exactly is it? In simple terms, cy.wrap is a Cypress command that allows you to take any object, value, or promise and “wrap” it, turning it into a Cypress chainable object.
A chainable object means you can perform Cypress commands on it. For example, if you have a JavaScript object, you can use cy.wrap to bring it into the Cypress testing scope and then use additional commands to interact with it.
Here’s an example:
javascript
CopyEdit
const myObject = { name: “Alice”, age: 25 };
cy.wrap(myObject).should(‘deep.include’, { name: “Alice” });
In this example, cy.wrap allows us to interact with the myObject using Cypress assertions.
Why Do We Need cy.wrap?
At first glance, cy.wrap might seem unnecessary, especially if you’re already familiar with JavaScript. However, cy.wrap plays a critical role in Cypress for a few key reasons:
- Interacting with Non-Cypress Values: Cypress commands are asynchronous by nature, meaning they follow their own execution chain. If you want to bring external data (e.g., a JavaScript object, API response, or even a promise) into this chain, cy.wrap makes it possible.
- Enhanced Test Readability: Wrapping objects into the Cypress chain ensures that all actions, assertions, and commands are part of the same test flow, making your tests easier to read and debug.
- Handling Promises Easily: If you’re working with asynchronous data (e.g., API calls), you can use cy.wrap to resolve the promise and continue chaining Cypress commands seamlessly.
In short, cy.wrap bridges the gap between Cypress commands and other JavaScript data, making it an indispensable tool for testers.
How Does cy.wrap Work with Objects?
When working with JavaScript objects, cy.wrap allows you to interact with them in the Cypress environment. Once wrapped, you can apply Cypress commands, assertions, or even manipulate the data.

For example:
javascript
CopyEdit
const user = { id: 1, name: “John Doe”, active: true };
cy.wrap(user).should(‘have.property’, ‘name’, ‘John Doe’);
Here, cy.wrap ensures the user object becomes part of Cypress’s test execution chain. You can now use Cypress-specific assertions or manipulate the object.
Can cy.wrap Handle JSON Data?
Yes, cy.wrap can handle JSON data effortlessly. Since JSON is simply a string representation of a JavaScript object, you can pass JSON data to cy.wrap and perform assertions or other operations.
For example:
javascript
CopyEdit
const jsonData = JSON.stringify({ id: 1, name: “John Doe” });
cy.wrap(jsonData).should(‘include’, ‘John Doe’);
This makes it easy to work with API responses, configurations, or any other data in JSON format.
How to Convert an Object to JSON Using cy.wrap
Converting an object into JSON is a common task in testing, especially when you need to work with API requests or validate responses. In JavaScript, the JSON.stringify() method is used to convert objects into JSON strings. You can combine cy.wrap with JSON.stringify() to achieve this in Cypress.
Here’s a simple example:
javascript
CopyEdit
const user = { id: 1, name: “Alice” };
cy.wrap(user).then((obj) => {
const jsonString = JSON.stringify(obj);
cy.log(jsonString); // Logs the JSON string in the Cypress console
});
Using cy.wrap, you can chain other commands after wrapping the object, making the process seamless and efficient.
Writing a Simple Cypress Test for Conversion
Let’s put everything together into a simple Cypress test:
javascript
CopyEdit
describe(‘Convert Object to JSON Using cy.wrap’, () => {
it(‘should convert an object to JSON’, () => {
const data = { title: “Cypress Test”, status: “success” };
// Wrap the object
cy.wrap(data).then((obj) => {
// Convert to JSON
const jsonString = JSON.stringify(obj);
// Perform assertions
expect(jsonString).to.include(‘Cypress Test’);
expect(jsonString).to.include(‘success’);
});
});
});
This test demonstrates how you can use cy.wrap and JSON.stringify() to handle objects and convert them to JSON in Cypress.
Using JavaScript Methods with cy.wrap
You’re not limited to just JSON.stringify() when using cy.wrap. You can also leverage other JavaScript methods to manipulate or analyze your data. For instance:
javascript
CopyEdit
const items = [1, 2, 3, 4];
cy.wrap(items).then((array) => {
const doubled = array.map((item) => item * 2);
cy.log(doubled); // Logs [2, 4, 6, 8]
});
This flexibility allows you to incorporate custom logic and operations within your Cypress tests.
Quick Example: cy.wrap + JSON.stringify
To illustrate the power of cy.wrap and JSON.stringify together, consider this quick example:
javascript
CopyEdit
const car = { make: “Toyota”, model: “Camry”, year: 2021 };
cy.wrap(car).then((obj) => {
const carJSON = JSON.stringify(obj);
cy.log(`Car details in JSON: ${carJSON}`);
});
Here, we converted the car object into a JSON string and logged it in the Cypress test runner.
Step-by-Step Example for Beginners
If you’re just starting out with Cypress, here’s a step-by-step guide to convert objects to JSON using cy.wrap:

Define an Object in Your Test
First, define a JavaScript object. This will be the data you want to work with in your Cypress test.
javascript
CopyEdit
const product = { id: 101, name: “Laptop”, price: 1200 };
Use cy.wrap to Interact With It
Wrap the object using cy.wrap. This ensures that it becomes part of Cypress’s test chain.
javascript
CopyEdit
cy.wrap(product).should(‘have.property’, ‘name’, ‘Laptop’);
Convert It to JSON with JSON.stringify
Finally, use the JSON.stringify() method to convert the object into a JSON string.
javascript
CopyEdit
cy.wrap(product).then((obj) => {
const jsonString = JSON.stringify(obj);
cy.log(jsonString); // Output the JSON string
});
Common Mistakes and How to Avoid Them
While using cy.wrap is straightforward, there are some common pitfalls to watch out for:
- Forgetting to Use then: Remember that cy.wrap returns a Cypress chainable object. To interact with the underlying data, use .then().
- Directly Using JSON.stringify: Always use JSON.stringify() inside a .then() block when working with wrapped objects. Otherwise, Cypress commands might not execute in the expected order.
- Assertions Outside Cypress Chain: Always keep assertions or commands within the Cypress chain to maintain proper flow.
The Bottom Line
Using cy.wrap to convert objects to JSON is a powerful feature in Cypress testing. It helps you seamlessly integrate JavaScript data into your test flow, perform assertions, and manipulate data efficiently. By following the examples and tips in this guide, even beginners can confidently work with cy.wrap and JSON.stringify.
Whether you’re validating API responses or performing advanced testing scenarios, cy.wrap is an essential tool in your Cypress arsenal. Start experimenting with it today and take your end-to-end testing skills to the next level!