k6/html

HTML parsing utilities for extracting and manipulating HTML content

The k6/html module provides functionality for parsing and manipulating HTML content in k6 scripts. It offers a jQuery-like API for selecting and extracting data from HTML responses.

Overview

Use this module to:

• Parse HTML responses from HTTP requests
• Extract data using CSS selectors
• Validate HTML structure and content
• Scrape data for parameterization

Importing the Module

import { parseHTML } from 'k6/html';

API Reference

Functions

parseHTML(src) · function

Parses an HTML string and returns a Selection object for querying the DOM.

Parameters:

src · string · required

HTML content to parse (typically from an HTTP response body)

Returns:

selection · Selection

A Selection object representing the document root

Selection Class

The Selection object provides a jQuery-like API for traversing and manipulating HTML documents.

Common Methods

find(selector) · function

Returns elements matching the CSS selector.

Parameters:

selector · string · required

CSS selector (e.g., "div.class", "#id", "a[href]")

text() · function

Returns the text content of the selection.

Returns:

text · string

Combined text content of all matched elements

html() · function

Returns the HTML content of the selection.

Returns:

html · string

HTML content of the first matched element

attr(name) · function

Returns the value of an attribute.

Parameters:

name · string · required

Attribute name (e.g., "href", "src", "class")

each(callback) · function

Iterates over matched elements.

Parameters:

callback · function · required

Function called for each element: (index, element) => void

size() · function

Returns the number of matched elements.

Returns:

count · number

Number of elements in the selection

eq(index) · function

Returns the element at the specified index.

Parameters:

index · number · required

Zero-based index of the element

Traversal Methods

children([selector]) · function

Returns child elements, optionally filtered by selector.

parent([selector]) · function

Returns parent elements, optionally filtered by selector.

siblings([selector]) · function

Returns sibling elements, optionally filtered by selector.

next([selector]) · function

Returns the next sibling element.

prev([selector]) · function

Returns the previous sibling element.

closest(selector) · function

Returns the closest ancestor matching the selector.

Element Class

Represents a single HTML DOM element.

nodeName · string

The tag name of the element (e.g., "div", "a", "span")

nodeType · number

The type of the node (1 for element nodes)

textContent · string

The text content of the element

innerHTML · string

The HTML content of the element

attributes · object

Map of attribute names to values

Examples

Parsing HTTP Response

Basic HTML Parsing

import http from 'k6/http';
import { parseHTML } from 'k6/html';
import { check } from 'k6';

export default function () {
  const res = http.get('https://test.k6.io');
  const doc = parseHTML(res.body);
  
  const pageTitle = doc.find('head title').text();
  
  check(pageTitle, {
    'page title is correct': (title) => title === 'test.k6.io',
  });
}

import http from 'k6/http';
import { parseHTML } from 'k6/html';

export default function () {
  const res = http.get('https://test.k6.io');
  const doc = parseHTML(res.body);
  
  const links = [];
  
  doc.find('a').each((index, element) => {
    const href = element.attr('href');
    if (href) {
      links.push(href);
    }
  });
  
  console.log(`Found ${links.length} links`);
}

Data Extraction and Validation

import http from 'k6/http';
import { parseHTML } from 'k6/html';
import { check } from 'k6';

export default function () {
  const res = http.get('https://test.k6.io/news.php');
  const doc = parseHTML(res.body);
  
  // Extract all article titles
  const articles = doc.find('article h2').map((i, el) => el.text());
  
  check(articles, {
    'has articles': (a) => a.length > 0,
    'first article exists': (a) => a[0] !== undefined,
  });
  
  // Extract form action URL
  const formAction = doc.find('form').attr('action');
  console.log(`Form submits to: ${formAction}`);
}

Working with Tables

import http from 'k6/http';
import { parseHTML } from 'k6/html';

export default function () {
  const res = http.get('https://test.k6.io/contacts.php');
  const doc = parseHTML(res.body);
  
  const contacts = [];
  
  doc.find('table tbody tr').each((index, row) => {
    const cells = row.find('td');
    
    contacts.push({
      name: cells.eq(0).text(),
      email: cells.eq(1).text(),
      phone: cells.eq(2).text(),
    });
  });
  
  console.log(`Extracted ${contacts.length} contacts`);
  console.log('First contact:', JSON.stringify(contacts[0]));
}

Form Data Extraction

import http from 'k6/http';
import { parseHTML } from 'k6/html';

export default function () {
  const res = http.get('https://test.k6.io/my_messages.php');
  const doc = parseHTML(res.body);
  
  // Extract CSRF token from hidden input
  const csrfToken = doc.find('input[name="csrf_token"]').attr('value');
  
  // Extract form action
  const formAction = doc.find('form').attr('action');
  
  console.log(`CSRF Token: ${csrfToken}`);
  console.log(`Form Action: ${formAction}`);
  
  // Use extracted data in subsequent request
  http.post(`https://test.k6.io${formAction}`, {
    csrf_token: csrfToken,
    message: 'Test message',
  });
}

CSS Selector Examples

import http from 'k6/http';
import { parseHTML } from 'k6/html';

export default function () {
  const res = http.get('https://test.k6.io');
  const doc = parseHTML(res.body);
  
  // Select by tag
  const allDivs = doc.find('div');
  
  // Select by ID
  const header = doc.find('#header');
  
  // Select by class
  const cards = doc.find('.card');
  
  // Select by attribute
  const externalLinks = doc.find('a[target="_blank"]');
  
  // Complex selector
  const navLinks = doc.find('nav ul li a');
  
  // Attribute contains
  const images = doc.find('img[src*=".png"]');
  
  // Multiple selectors
  const headings = doc.find('h1, h2, h3');
  
  console.log(`Found ${navLinks.size()} navigation links`);
}

Content Verification

import http from 'k6/http';
import { parseHTML } from 'k6/html';
import { check } from 'k6';

export default function () {
  const res = http.get('https://test.k6.io');
  const doc = parseHTML(res.body);
  
  check(doc, {
    'has login form': (d) => d.find('form#login').size() > 0,
    'has footer': (d) => d.find('footer').size() > 0,
    'has navigation': (d) => d.find('nav').size() > 0,
    'logo image present': (d) => d.find('img.logo').size() > 0,
  });
  
  // Verify specific text content
  const welcomeText = doc.find('.welcome').text();
  check(welcomeText, {
    'welcome message contains "k6"': (text) => text.includes('k6'),
  });
}

Common Use Cases

Web Scraping for Test Data

Extract dynamic values from HTML to use in subsequent requests:

• CSRF tokens from forms
• Session identifiers from hidden fields
• Product IDs from listings
• Dynamic URLs from navigation

HTML Structure Validation

Verify that pages contain expected elements:

• Forms have required fields
• Navigation links are present
• Images have alt text
• Headers follow hierarchy

Content Verification

Validate page content matches requirements:

• Check for specific text or messages
• Verify data is displayed correctly
• Ensure error messages appear when expected
• Validate dynamic content rendering

Performance Considerations

HTML parsing has overhead. For high-performance tests:

• Only parse when you need to extract data
• Use http response checks for simple validation
• Cache parsed documents if parsing the same content multiple times
• Consider using check() on response body strings for simple text matching

Related Resources

HTTP Module

Make HTTP requests

Checks

Validate responses

CSS Selectors

Learn CSS selector syntax

Data Correlation

Extract and reuse dynamic data