What is jest-environment-puppeteer?
The jest-environment-puppeteer package provides a Jest test environment that uses Puppeteer, a headless Chrome Node API, to run browser tests. This allows you to write tests that interact with a real browser, making it ideal for end-to-end (E2E) testing, UI testing, and web scraping.
What are jest-environment-puppeteer's main functionalities?
End-to-End Testing
This feature allows you to perform end-to-end testing by interacting with a real browser. The code sample demonstrates how to navigate to Google's homepage and check if the text 'google' is present on the page.
const puppeteer = require('puppeteer');
describe('Google', () => {
beforeAll(async () => {
await page.goto('https://google.com');
});
it('should display "google" text on page', async () => {
const text = await page.evaluate(() => document.body.textContent);
expect(text).toContain('google');
});
});
UI Testing
This feature allows you to perform UI testing by simulating user interactions. The code sample demonstrates how to click a button on a webpage and verify that a message is displayed as a result.
const puppeteer = require('puppeteer');
describe('Button Click', () => {
beforeAll(async () => {
await page.goto('https://example.com');
});
it('should click a button and display a message', async () => {
await page.click('#myButton');
const message = await page.$eval('#message', el => el.textContent);
expect(message).toBe('Button clicked!');
});
});
Web Scraping
This feature allows you to perform web scraping by extracting information from web pages. The code sample demonstrates how to navigate to a webpage and scrape the title of the page.
const puppeteer = require('puppeteer');
describe('Web Scraping', () => {
beforeAll(async () => {
await page.goto('https://example.com');
});
it('should scrape the title of the page', async () => {
const title = await page.title();
expect(title).toBe('Example Domain');
});
});
Other packages similar to jest-environment-puppeteer
jest-puppeteer
jest-puppeteer provides a similar environment for running Puppeteer tests with Jest. It offers a more integrated setup with additional utilities and configurations specifically designed for Puppeteer, making it easier to write and manage browser tests.
puppeteer
Puppeteer is a Node library that provides a high-level API to control Chrome or Chromium over the DevTools Protocol. While it doesn't integrate directly with Jest, it can be used in conjunction with Jest to perform browser automation tasks. jest-environment-puppeteer essentially builds on top of Puppeteer to provide a seamless Jest environment.
cypress
Cypress is an end-to-end testing framework that provides a complete solution for running browser tests. Unlike jest-environment-puppeteer, Cypress comes with its own test runner and assertion library, offering a more comprehensive and user-friendly experience for writing and running browser tests.
jest-environment-puppeteer
![npm dt](https://img.shields.io/npm/dt/jest-environment-puppeteer.svg)
Run your tests using Jest & Puppeteer 🎪✨
npm install jest-environment-puppeteer puppeteer
Usage
Update your Jest configuration:
{
"globalSetup": "jest-environment-puppeteer/setup",
"globalTeardown": "jest-environment-puppeteer/teardown",
"testEnvironment": "jest-environment-puppeteer"
}
Use Puppeteer in your tests:
describe("Google", () => {
beforeAll(async () => {
await page.goto("https://google.com");
});
it('should display "google" text on page', async () => {
const text = await page.evaluate(() => document.body.textContent);
expect(text).toContain("google");
});
});
API
global.browser
Give access to the Puppeteer Browser.
it("should open a new page", async () => {
const page = await browser.newPage();
await page.goto("https://google.com");
});
global.page
Give access to a Puppeteer Page opened at start (you will use it most of time).
it("should fill an input", async () => {
await page.type("#myinput", "Hello");
});
global.context
Give access to a browser context that is instantiated when the browser is launched. You can control whether each test has its own isolated browser context using the browserContext
option in your jest-puppeteer.config.js
.
global.jestPuppeteer.debug()
Put test in debug mode.
- Jest is suspended (no timeout)
- A
debugger
instruction to Chromium, if Puppeteer has been launched with { devtools: true }
it will stop
it("should put test in debug mode", async () => {
await jestPuppeteer.debug();
});
global.jestPuppeteer.resetPage()
Reset global.page
beforeEach(async () => {
await jestPuppeteer.resetPage();
});
global.jestPuppeteer.resetBrowser()
Reset global.browser, global.context, and global.page
beforeEach(async () => {
await jestPuppeteer.resetBrowser();
});
jest-puppeteer.config.js
You can specify a jest-puppeteer.config.js
at the root of the project or define a custom path using JEST_PUPPETEER_CONFIG
environment variable. It should export a config object or a Promise for a config object.
interface JestPuppeteerConfig {
connect?: ConnectOptions;
launch?: PuppeteerLaunchOptions;
server?: JestDevServerConfig | JestDevServerConfig[];
browserPerWorker?: boolean;
browserContext?: "default" | "incognito";
exitOnPageError?: boolean;
runBeforeUnloadOnClose?: boolean;
}
Example 1
module.exports = {
launch: {
dumpio: true,
headless: process.env.HEADLESS !== "false",
},
server: {
command: "node server.js",
port: 4444,
launchTimeout: 10000,
debug: true,
},
};
Example 2
This example uses an already running instance of Chrome by passing the active web socket endpoint to connect
. This is useful, for example, when you want to connect to Chrome running in the cloud.
const dockerHost = "http://localhost:9222";
async function getConfig() {
const data = await fetch(`${dockerHost}/json/version`).json();
const browserWSEndpoint = data.webSocketDebuggerUrl;
return {
connect: {
browserWSEndpoint,
},
server: {
command: "node server.js",
port: 3000,
launchTimeout: 10000,
debug: true,
},
};
}
module.exports = getConfig();
Inspiration
Thanks to Fumihiro Xue for his great Jest example.