Skip to main 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

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',
  });
}

​
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

HTTP Module

Make HTTP requests

Checks

Validate responses

CSS Selectors

Learn CSS selector syntax

Data Correlation

Extract and reuse dynamic data

Build docs developers (and LLMs) love

Get started for freeTalk to us