fs on Grafana Labs

File

Mon, 21 Sep 2026 15:16:28 +0000

File

The File class represents a file with methods for reading, seeking, and obtaining file stats. It’s returned by the open function.

Properties

Property	Type	Description
path	string	The absolute path to the file.

Methods

Method	Description
read	Reads up to `buffer.byteLength` bytes from the file into the passed `buffer`. Returns a promise resolving to the number of bytes read.
seek	Sets the file position indicator for the file to the passed `offset` bytes. Returns a promise resolving to the new offset.
stat	Returns a promise resolving to a FileInfo object with information about the file.

Example

import { open, SeekMode } from 'k6/experimental/fs';

const file = await open('bonjour.txt');

export default async function () {
  // Seek to the beginning of the file
  await file.seek(0, SeekMode.Start);

  // About information about the file
  const fileinfo = await file.stat();
  if (fileinfo.name != 'bonjour.txt') {
    throw new Error('Unexpected file name');
  }

  const buffer = new Uint8Array(4);

  let totalBytesRead = 0;
  while (true) {
    // Read into the buffer
    const bytesRead = await file.read(buffer);
    if (bytesRead == null) {
      // EOF
      break;
    }

    // Do something useful with the content of the buffer
    totalBytesRead += bytesRead;

    // If bytesRead is less than the buffer size, we've read the whole file
    if (bytesRead < buffer.byteLength) {
      break;
    }
  }

  // Check that we read the expected number of bytes
  if (totalBytesRead != fileinfo.size) {
    throw new Error('Unexpected number of bytes read');
  }
}

open

Mon, 21 Sep 2026 15:16:28 +0000

open

The open function opens a file and returns a promise that resolves to a File instance. Unlike the traditional open function, which loads a file multiple times into memory, the filesystem module reduces memory usage by loading the file as little possible, and sharing the same memory space between all VUs. This approach reduces the risk of encountering out-of-memory errors, especially in load tests involving large files.

Parameters

Parameter	Type	Description
path	string	The path to the file to open. Relative paths are resolved relative to the k6 script.

Returns

A promise resolving to a File instance.

Example

import { open } from 'k6/experimental/fs';

// k6 doesn't support async in the init context. We use a top-level async function for `await`.
//
// Each Virtual User gets its own `file` copy.
// So, operations like `seek` or `read` won't impact other VUs.
const file = await open('bonjour.txt');

export default async function () {
  // About information about the file
  const fileinfo = await file.stat();
  if (fileinfo.name != 'bonjour.txt') {
    throw new Error('Unexpected file name');
  }

  console.log(JSON.stringify(fileinfo));
}

FileInfo

Mon, 21 Sep 2026 15:16:28 +0000

FileInfo

The FileInfo class represents information about a file.

Properties

Property	Type	Description
name	string	The name of the file.
size	number	The size of the file in bytes.

Example

import { open, SeekMode } from 'k6/experimental/fs';

const file = await open('bonjour.txt');

export default async function () {
  // Retrieve information about the file
  const fileinfo = await file.stat();
  if (fileinfo.name != 'bonjour.txt') {
    throw new Error('Unexpected file name');
  }
}

SeekMode

Mon, 21 Sep 2026 15:16:28 +0000

SeekMode

The SeekMode enum specifies the position from which to seek in a file.

Members

Member	Value	Description
Start	0	Seek from the start of the file.
Current	1	Seek from the current position in the file.
End	2	Seek from the end of the file.

Example

import { open, SeekMode } from 'k6/experimental/fs';

const file = await open('bonjour.txt');

export default async function () {
  // Seek 6 bytes from the start of the file
  await file.seek(6, SeekMode.Start);

  // Seek 2 more bytes from the current position
  await file.seek(2, SeekMode.Current);

  // Seek backwards 2 bytes from the end of the file
  await file.seek(-2, SeekMode.End);
}