Skip to content
Latte v0.16.0

Headless Browser

If you need to interact with a website, you can use the built-in headless browser. This is useful for web scraping, testing, and more.

Access to the Browser

The Browser object is available in the global scope with B name. Also, you can import it from the latte package.

import { B } from "@olton/latte";


beforeAll(async () => {
    await B.create();
});


afterAll(async () => {
    await B.bye();
});


describe("Google", () => {
    it("Search", async () => {
        await B.visit("https://example.com");
        const title = await B.document.title();
        expect(title).toBe("Example Domain");
    });
});

Methods

The Browser object provides a set of methods to interact with the browser. The methods are grouped into categories for better organization.

Core

B.create()

Creates a new browser instance. This method returns a promise that resolves when the browser is ready to use.

const options = {
    headless: "shell",
    args: [
        '--no-sandbox',
    ],
    detached: true,
    dumpio: false,
    env: {},
    executablePath: undefined,
    handleSIGHUP: true,
    handleSIGINT: true,
    handleSIGTERM: true,
    onExit: undefined,
    pipe: false,
    log: false,
    coverage: {
        filter: '',
        reportFileName: 'lcov-browser.info',
        includeRawScriptCoverage: true,
        reportAnonymousScripts: true,
        resetOnNavigation: true,
        useBlockCoverage: true,
    }
};
await B.create(options);

B.bye()

Closes the browser instance. This method returns a promise that resolves when the browser is closed.

await B.bye();

B.emulate()

Emulates a device. This method returns a promise that resolves when the device is emulated.

await B.emulate(device);

To get the list of devices, use the B.devices property.

const devices = B.devices;
Click to see the list of devices

Blackberry PlayBook, Blackberry PlayBook landscape, BlackBerry Z30, BlackBerry Z30 landscape, Galaxy Note 3, Galaxy Note 3 landscape, Galaxy Note II , Galaxy Note II landscape, Galaxy S III, Galaxy S III landscape, Galaxy S5, Galaxy S5 landscape, Galaxy S8, Galaxy S8 landscape, Galaxy S9+ , Galaxy S9+ landscape, Galaxy Tab S4, Galaxy Tab S4 landscape, iPad, iPad landscape, iPad (gen 6), iPad (gen 6) landscape, iPad (gen 7) , iPad (gen 7) landscape, iPad Mini, iPad Mini landscape, iPad Pro, iPad Pro landscape, iPad Pro 11, iPad Pro 11 landscape, iPhone 4 , iPhone 4 landscape, iPhone 5, iPhone 5 landscape, iPhone 6, iPhone 6 landscape, iPhone 6 Plus, iPhone 6 Plus landscape, iPhone 7 , iPhone 7 landscape, iPhone 7 Plus, iPhone 7 Plus landscape, iPhone 8, iPhone 8 landscape, iPhone 8 Plus, iPhone 8 Plus landscape , iPhone SE, iPhone SE landscape, iPhone X, iPhone X landscape, iPhone XR, iPhone XR landscape, iPhone 11, iPhone 11 landscape, iPhone 11 Pro , iPhone 11 Pro landscape, iPhone 11 Pro Max, iPhone 11 Pro Max landscape, iPhone 12 , iPhone 12 landscape, iPhone 12 Pro, iPhone 12 Pro landscape , iPhone 12 Pro Max, iPhone 12 Pro Max landscape, iPhone 12 Mini, iPhone 12 Mini landscape, iPhone 13, iPhone 13 landscape, iPhone 13 Pro , iPhone 13 Pro landscape, iPhone 13 Pro Max, iPhone 13 Pro Max landscape, iPhone 13 Mini, iPhone 13 Mini landscape, iPhone 14, iPhone 14 landscape , iPhone 14 Plus, iPhone 14 Plus landscape, iPhone 14 Pro, iPhone 14 Pro landscape, iPhone 14 Pro Max, iPhone 14 Pro Max landscape, iPhone 15 , iPhone 15 landscape, iPhone 15 Plus, iPhone 15 Plus landscape, iPhone 15 Pro, iPhone 15 Pro landscape, iPhone 15 Pro Max, iPhone 15 Pro Max landscape , JioPhone 2, JioPhone 2 landscape, Kindle Fire HDX, Kindle Fire HDX landscape, LG Optimus L70, LG Optimus L70 landscape, Microsoft Lumia 550 , Microsoft Lumia 950, Microsoft Lumia 950 landscape, Nexus 10, Nexus 10 landscape, Nexus 4, Nexus 4 landscape, Nexus 5, Nexus 5 landscape , Nexus 5X, Nexus 5X landscape, Nexus 6, Nexus 6 landscape, Nexus 6P, Nexus 6P landscape, Nexus 7, Nexus 7 landscape, Nokia Lumia 520 , Nokia Lumia 520 landscape, Nokia N9, Nokia N9 landscape, Pixel 2, Pixel 2 landscape, Pixel 2 XL, Pixel 2 XL landscape, Pixel 3, Pixel 3 landscape , Pixel 4, Pixel 4 landscape, Pixel 4a (5G), Pixel 4a (5G) landscape, Pixel 5, Pixel 5 landscape, Moto G4, Moto G4 landscape

Pages

B.pages()

Returns an array of all pages in the browser. This method returns a promise that resolves to an array of pages.

const pages = await B.pages();

B.page()

Returns the page by index. If page index is not specified, it returns the current page. This method returns a promise that resolves to the page.

const page = await B.page(index);

B.pageCount()

Returns the number of pages in the browser. This method returns a promise that resolves to the number of pages.

const count = await B.pageCount();

B.newPage()

Creates a new page in the browser. This method returns a promise that resolves to the new page.

const page = await B.newPage();

B.setPage()

Sets the current page. Page is a page object. This method returns a promise that resolves when the page is set.

await B.setPage(page);

B.setPageByIndex()

Sets the current page by index. This method returns a promise that resolves when the page is set.

await B.setPageByIndex(index);

B.close()

Closes the current page. This method returns a promise that resolves when the page is closed.

await B.close();

B.closeAll()

Closes all pages in the browser. This method returns a promise that resolves when all pages are closed.

await B.closeAll();

B.closePage()

Closes the page by index or page object or current. This method returns a promise that resolves when the page is closed.

const runBeforeOnLoad = false


await B.closePage(index, runBeforeOnLoad);
await B.closePage(page, runBeforeOnLoad);
await B.closePage(null, runBeforeOnLoad);

Elements

B.$()

Finds elements on the page. This method returns a promise that resolves to the element.

const element = await B.$("selector");

B.find()

Finds elements on the page. This method returns a promise that resolves to an array of elements.

const elements = await B.find("selector");

B.findFirst()

Finds the first element on the page. This method returns a promise that resolves to the element.

const element = await B.findFirst("selector");

B.waitFor()

Waits for an element to be added to the page. This method returns a promise that resolves when the element is added.

const element = await B.waitFor("selector", timeout);

Interaction

B.click()

Clicks on an element. This method returns a promise that resolves when the element is clicked.

const element = await B.click("selector");

B.tap()

Taps on an element. This method returns a promise that resolves when the element is tapped.

const element = await B.tap("selector");

B.type()

Types text into an element. This method returns a promise that resolves when the text is typed.

const element = await B.type("selector", "text");

CSS

B.addCss()

Adds CSS to the page. This method returns a promise that resolves when the CSS is added.

const css = `
    body {
        background: red;
    }
`;
await B.addCss({content: css, path: "/path_to_file/style.css", url: "https://example.com/style.css"});

You can specify the following options:

  • content - CSS content
  • path - path to the CSS file
  • url - URL to the CSS file

B.addCssFromString()

Adds CSS to the page from a string. This method returns a promise that resolves when the CSS is added.

const css = `
    body {
        background: red;
    }
`;
await B.addCssFromString(css);

B.addCssFromFile()

Adds CSS to the page from a file. This method returns a promise that resolves when the CSS is added.

const path = "/path_to_file/style.css";
await B.addCssFromFile(path);

B.addCssFromUrl()

Adds CSS to the page from a URL. This method returns a promise that resolves when the CSS is added.

const url = "https://example.com/style.css";
await B.addCssFromUrl(url);

JavaScript

B.addJs()

Adds JavaScript to the page. This method returns a promise that resolves when the JavaScript is added.

const js = `
    function hello() {
        console.log('Hello world');
    }
`;
await B.addJs({content: js, path: "/path_to_file/script.js", url: "https://example.com/script.js"});

You can specify the following options:

  • content - JavaScript content
  • path - path to the JavaScript file
  • url - URL to the JavaScript file
  • id - id of the script tag
  • type - type of the script tag

B.addFunction()

Adds a function to the page. The method adds a function called name on the page’s window object.

await B.addFunction("hello", () => {
    console.log("Hello world");
});


await B.exec(async () => {
    await window.hello();
})

B.exec()

Executes a js code in the context of the page. This method returns a promise that resolves to the result of the function.

Function object

const result = await B.exec(() => {
  return Promise.resolve(8 * 7);
});
console.log(result); // prints "56"

Function as string

const result = await B.exec("1 + 2");

Pass arguments

const bodyHandle = await page.$('body');
const html = await B.exec(body => body.innerHTML, bodyHandle);
await bodyHandle.dispose();

B.visit()

Navigate to a URL. This method returns a promise that resolves when the page is loaded.

await B.visit("https://example.com", {
    referer: "https://google.com",
    refererPolicy: "no-referrer"
});

B.back()

Goes back to the previous page. This method returns a promise that resolves when the page is loaded.

await B.back();

B.forward()

Goes forward to the next page. This method returns a promise that resolves when the page is loaded.

await B.forward();

B.reload()

Reloads the current page. This method returns a promise that resolves when the page is reloaded.

await B.reload();

Document

The document object is a wrapper around the page’s document object. It provides methods to interact with the page’s DOM.

B.document.title()

The title of the page. This method returns a promise that resolves to the title of the page.

const title = await B.document.title();

B.document.html()

The full HTML contents of the page, including the DOCTYPE. This method returns a promise that resolves to the HTML of the page.

const html = await B.document.html();

B.document.url()

The URL of the page. This method returns a promise that resolves to the URL of the page.

const url = await B.document.url();

B.document.cookies()

The cookies of the page. You can pass an array of URLs to get cookies for specific pages. This method returns a promise that resolves to an array of cookies.

const cookies = await B.document.cookies(urls = []);

B.document.body()

The body of the page. This method returns a promise that resolves to the body of the page.

const body = await B.document.body();

Window

The window object is a wrapper around the page’s window object. It provides methods to interact with the page’s window.

B.window()

Get the window object of the page. This method returns a promise that resolves to the window object.

const window = await B.window();

Utils

B.screenshot()

Takes a screenshot of the page. This method returns a promise that resolves to the screenshot.

const options = {
    fullPage: false,
    quality: 100, // 0-100
    type: "png", // png, jpeg, webp
}
const screenshot = await B.screenshot(path, options);

B.pdf()

Generates a PDF of the page. This method returns a promise that resolves to the PDF.

const options = {
}
const pdf = await B.pdf(path, options);

B.metrics()

Returns the metrics of the page. This method returns a promise that resolves to the metrics of the page.

const metrics = await B.metrics();
console.log(metrics);

Code Coverage

B.startCoverage()

Starts code coverage. This method returns a promise that resolves when the coverage is started.

You can pass an options object to specify the coverage options:

const coverageOptions = {
    includeRawScriptCoverage: true,
    reportAnonymousScripts: true,
    resetOnNavigation: true,
    useBlockCoverage: true
}


await B.startCoverage(coverageOptions);

B.stopCoverage()

Stops code coverage. This method returns a promise that resolves when the coverage is stopped.

const coverage = await B.stopCoverage();
console.log(coverage);