k6deps

package module
v0.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 27, 2025 License: AGPL-3.0 Imports: 13 Imported by: 5

README

Go Reference GitHub Release Go Report Card GitHub Actions codecov GitHub Downloads

k6deps

Dependency analysis for k6 tests

The goal of k6deps is to extract dependencies from k6 test scripts. For this purpose, k6deps analyzes the k6 test scripts and the modules imported from it in a recursive manner.

k6deps is primarily used as a go library. In addition, it also contains a command-line tool, which is suitable for listing the dependencies of k6 test scripts.

The command line tool can be integrated into other command line tools as a subcommand. For this purpose, the library also contains the functionality of the command line tool as a factrory function that returns cobra.Command.

Install

Precompiled binaries can be downloaded and installed from the Releases page.

If you have a go development environment, the installation can also be done with the following command:

go install github.com/grafana/k6deps/cmd/k6deps@latest

Usage

Dependencies can come from three sources: k6 test script, manifest file, K6_DEPENDENCIES environment variable. Instead of these three sources, a k6 archive can also be specified, which can contain all three sources (currently two actually, because the manifest file is not yet included in the k6 archive).

In the simplest use, we only extract the dependencies from the script source.

with pragma 
package k6deps_test

import (
	"fmt"

	"github.com/grafana/k6deps"
)

const scriptWithPragma = `
"use k6 > 0.54";
"use k6 with k6/x/faker > 0.4.0";
"use k6 with k6/x/sql >= 1.0.1";

import { Faker } from "k6/x/faker";
import sql from "k6/x/sql";
import driver from "k6/x/sql/driver/ramsql";

export default function() {
}
`

func ExampleAnalyze_with_pragma() {
	deps, _ := k6deps.Analyze(&k6deps.Options{
		Script: k6deps.Source{
			Name:     "script.js",
			Contents: []byte(scriptWithPragma),
		},
		// disable automatic source detection
		Manifest: k6deps.Source{Ignore: true},
		Env:      k6deps.Source{Ignore: true},
	})

	fmt.Println(deps.String())

	out, _ := deps.MarshalJSON()
	fmt.Println(string(out))
	// Output:
	// k6>0.54;k6/x/faker>0.4.0;k6/x/sql>=1.0.1;k6/x/sql/driver/ramsql*
	// {"k6":">0.54","k6/x/faker":">0.4.0","k6/x/sql":">=1.0.1","k6/x/sql/driver/ramsql":"*"}
}
without pragma 
package k6deps_test

import (
	"fmt"

	"github.com/grafana/k6deps"
)

const scriptWithoutPragma = `
import { Faker } from "k6/x/faker";
import sql from "k6/x/sql";
import driver from "k6/x/sql/driver/ramsql";

export default function() {
}
`

func ExampleAnalyze_without_pragma() {
	deps, _ := k6deps.Analyze(&k6deps.Options{
		Script: k6deps.Source{
			Name:     "script.js",
			Contents: []byte(scriptWithoutPragma),
		},
		// disable automatic source detection
		Manifest: k6deps.Source{Ignore: true},
		Env:      k6deps.Source{Ignore: true},
	})

	fmt.Println(deps.String())

	out, _ := deps.MarshalJSON()
	fmt.Println(string(out))
	// Output:
	// k6/x/faker*;k6/x/sql*;k6/x/sql/driver/ramsql*
	// {"k6/x/faker":"*","k6/x/sql":"*","k6/x/sql/driver/ramsql":"*"}
}

CLI

k6deps

Extension dependency detection for k6.

Synopsis

Analyze the k6 test script and extract the extensions that the script depends on.

Sources

Dependencies can come from three sources: k6 test script, manifest file, K6_DEPENDENCIES environment variable. Instead of these three sources, a k6 archive can also be specified, which can contain all three sources (currently two actually, because the manifest file is not yet included in the k6 archive).

The name of k6 test script or archive can be specified as the positional argument in the command invocation. Alternatively, the content can be provided in the stdin. If stdin is used, the input format ('js' for script of or 'tar' for archive) must be specified using the --input parameter.

Primarily, the k6 test script is the source of dependencies. The test script and the local and remote JavaScript modules it uses are recursively analyzed. The extensions used by the test script are collected. In addition to the require function and import expression, the "use k6 ..." directive can be used to specify additional extension dependencies. If necessary, the "use k6 ..." directive can also be used to specify version constraints.

"use k6 > 0.54";
"use k6 with k6/x/faker > 0.4.0";
"use k6 with k6/x/sql >= 1.0.1";

import { Faker } from "k6/x/faker";
import sql from "k6/x/sql";
import driver from "k6/x/sql/driver/ramsql";

Dependencies and version constraints can also be specified in the so-called manifest file. The default name of the manifest file is package.json and it is automatically searched from the directory containing the test script up to the root directory. The dependencies property of the manifest file contains the dependencies in JSON format.

{"dependencies":{"k6":">0.54","k6/x/faker":">0.4.0","k6/x/sql":>=v1.0.1"}}

Dependencies and version constraints can also be specified in the K6_DEPENDENCIES environment variable. The value of the variable is a list of dependencies in a one-line text format.

k6>0.54;k6/x/faker>0.4.0;k6/x/sql>=v1.0.1

Format

By default, dependencies are written as a JSON object. The property name is the name of the dependency and the property value is the version constraints of the dependency.

{"k6":">0.54","k6/x/faker":">0.4.0","k6/x/sql":">=1.0.1","k6/x/sql/driver/ramsql":"*"}

Additional output formats:

  • text - One line text format. A semicolon-separated sequence of the text format of each dependency. The first element of the series is k6 (if there is one), the following elements follow each other in lexically increasing order based on the name.

     k6>0.54;k6/x/faker>0.4.0;k6/x/sql>=1.0.1;k6/x/sql/driver/ramsql*

  • js - A consecutive, one-line JavaScript string directives. The first element of the series is k6 (if there is one), the following elements follow each other in lexically increasing order based on the name.

     "use k6>0.54";
 "use k6 with k6/x/faker>0.4.0";
 "use k6 with k6/x/sql>=v1.0.1";

Output

By default, dependencies are written to standard output. By using the -o/--output flag, the dependencies can be written to a file.

k6deps [flags] [script-file]

Flags

      --format json|text|js   output format, possible values: json,env,script (default json)
  -h, --help                  help for k6deps
      --ignore-manifest       disable package.json detection and processing
      --ignore-script         disable script processing
      --ingnore-env           ignore K6_DEPENDENCIES environment variable processing
  -i, --input string          input format ('js' or 'tar' for archives)
      --manifest string       manifest file to analyze (default 'package.json' nearest to script-file)
  -o, --output string         write output to file (default stdout)

Contribute

If you want to contribute or help with the development of k6pack, start by reading CONTRIBUTING.md.

Documentation

Overview

Package k6deps contains the data model of the k6 script dependencies and the operations related to them.

Index

Examples

Constants

View Source 
const (
	// ConstraintsAny is a wildcard constraint that any version matches.
	ConstraintsAny = "*"

	// NameK6 is the name of the k6 dependency, its value is "k6".
	NameK6 = "k6"
)
View Source 
const EnvDependencies = "K6_DEPENDENCIES"

EnvDependencies holds the name of the environment variable thet describes additional dependencies.

Variables

View Source 
var (
	ErrConstraints = errors.New("constraints error")
	ErrDependency  = errors.New("dependency error")
)

Functions

This section is empty.

Types

type Dependencies 

type Dependencies map[string]*Dependency

Dependencies contains the dependencies of the k6 test script in map format. The key of the map is the name of the dependency.

func Analyze 

func Analyze(opts *Options) (Dependencies, error)

Analyze searches, loads and analyzes the specified sources, extracting the k6 extensions and their version constraints. Note: if archive is specified, the other three sources will not be taken into account, since the archive may contain them.

Example (With_pragma) 
package main

import (
	"fmt"

	"github.com/grafana/k6deps"
)

const scriptWithPragma = `
"use k6 > 0.54";
"use k6 with k6/x/faker > 0.4.0";
"use k6 with k6/x/sql >= 1.0.1";

import { Faker } from "k6/x/faker";
import sql from "k6/x/sql";
import driver from "k6/x/sql/driver/ramsql";

export default function() {
}
`

func main() {
	deps, _ := k6deps.Analyze(&k6deps.Options{
		Script: k6deps.Source{
			Name:     "script.js",
			Contents: []byte(scriptWithPragma),
		},
		// disable automatic source detection
		Manifest: k6deps.Source{Ignore: true},
		Env:      k6deps.Source{Ignore: true},
	})

	fmt.Println(deps.String())

	out, _ := deps.MarshalJSON()
	fmt.Println(string(out))
}

Output:

k6>0.54;k6/x/faker>0.4.0;k6/x/sql>=1.0.1;k6/x/sql/driver/ramsql*
{"k6":">0.54","k6/x/faker":">0.4.0","k6/x/sql":">=1.0.1","k6/x/sql/driver/ramsql":"*"}
Example (Without_pragma) 
package main

import (
	"fmt"

	"github.com/grafana/k6deps"
)

const scriptWithoutPragma = `
import { Faker } from "k6/x/faker";
import sql from "k6/x/sql";
import driver from "k6/x/sql/driver/ramsql";

export default function() {
}
`

func main() {
	deps, _ := k6deps.Analyze(&k6deps.Options{
		Script: k6deps.Source{
			Name:     "script.js",
			Contents: []byte(scriptWithoutPragma),
		},
		// disable automatic source detection
		Manifest: k6deps.Source{Ignore: true},
		Env:      k6deps.Source{Ignore: true},
	})

	fmt.Println(deps.String())

	out, _ := deps.MarshalJSON()
	fmt.Println(string(out))
}

Output:

k6/x/faker*;k6/x/sql*;k6/x/sql/driver/ramsql*
{"k6/x/faker":"*","k6/x/sql":"*","k6/x/sql/driver/ramsql":"*"}

func (Dependencies) MarshalJS 

func (deps Dependencies) MarshalJS() ([]byte, error)

MarshalJS marshals dependencies into a consecutive, one-line JavaScript string directive format. The first element of the series is "k6" (if there is one), the following elements follow each other in lexically increasing order based on the name.

func (Dependencies) MarshalJSON 

func (deps Dependencies) MarshalJSON() ([]byte, error)

MarshalJSON marshals dependencies into JSON object format. The property names will be the dependency names, and the property values ​​will be the text format used by MarshalText of the given dependency.

func (Dependencies) MarshalText 

func (deps Dependencies) MarshalText() ([]byte, error)

MarshalText marshals the dependencies into a single-line text format. The text format is a semicolon-separated sequence of the text format of each dependency. The first element of the series is "k6" (if there is one), the following elements follow each other in lexically increasing order based on the name. For example: k6>0.49;k6/x/faker>=0.2.0;k6/x/toml>v0.1.0;xk6-dashboard*

func (Dependencies) Merge 

func (deps Dependencies) Merge(from Dependencies) error

Merge updates deps dependencies based on from dependencies. Adds a dependency that doesn't exist yet. If the dependency exists in both collections, but one of them does not have version constraints, then the dependency with version constraints is placed in deps. Otherwise, i.e. if the dependency is included in both collections and in both with version constraints, an error is generated.

func (Dependencies) Sorted added in v0.1.2 

func (deps Dependencies) Sorted() []*Dependency

Sorted returns dependencies as an array, with "k6" as a first element (if any) and the rest of the array is sorted by name lexicographically.

func (Dependencies) String 

func (deps Dependencies) String() string

String converts the dependencies to displayable text format. The format is the same as that used by MarshalText.

func (*Dependencies) UnmarshalJS 

func (deps *Dependencies) UnmarshalJS(text []byte) error

UnmarshalJS unmarshals dependencies from a series of string directives in the format used by MarshalJS.

func (*Dependencies) UnmarshalJSON 

func (deps *Dependencies) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals dependencies from a JSON object in the format used by MarshalJSON.

func (*Dependencies) UnmarshalText 

func (deps *Dependencies) UnmarshalText(text []byte) error

UnmarshalText parses the one-line text dependencies format into the *deps variable.

type Dependency 

type Dependency struct {
	// Name is the name of the dependency.
	Name string `json:"name,omitempty"`
	// Constraints contains the version constraints of the dependency.
	Constraints *semver.Constraints `json:"constraints,omitempty"`
}

Dependency contains the properties of a k6 dependency (extension or k6 core).

func NewDependency 

func NewDependency(name, constraints string) (*Dependency, error)

NewDependency creates a new Dependency instance with the given name. If the constraints parameter is not empty, it will be parsed as version constraints.

func (*Dependency) GetConstraints added in v0.1.2 

func (dep *Dependency) GetConstraints() *semver.Constraints

GetConstraints returns Constraints or the default constraints ("*") if Constraints is nil

func (*Dependency) MarshalJS 

func (dep *Dependency) MarshalJS() ([]byte, error)

MarshalJS marshals the dependency into a one-line JavaScript string directive format. For example: "us k6 with k6/x/faker>0.1.0";

func (*Dependency) MarshalText 

func (dep *Dependency) MarshalText() ([]byte, error)

MarshalText marshals the dependency into a single-line text format. For example: k6/x/faker>0.1.0

func (*Dependency) String 

func (dep *Dependency) String() string

String converts the dependency to displayable text format. The format is the same as that used by MarshalText.

func (*Dependency) UnmarshalText 

func (dep *Dependency) UnmarshalText(text []byte) error

UnmarshalText parses the one-line text dependency format into the *dep variable.

type Options 

type Options struct {
	// Script contains the properties of the k6 test script to be analyzed.
	Script Source
	// Archive contains the properties of the k6 archive to be analyzed.
	// If archive is specified, the other three sources will not be taken into account,
	// since the archive may contain them.
	// An archive is a tar file, which can be created using the k6 archive command, for example.
	Archive Source
	// Manifest contains the properties of the manifest file to be analyzed.
	// If the Ignore property is not set and no manifest file is specified,
	// the package.json file closest to the script is searched for.
	Manifest Source
	// Env contains the properties of the environment variable to be analyzed.
	// If the Ignore property is not set and no variable is specified,
	// the value of the variable named K6_DEPENDENCIES is read.
	Env Source
	// LookupEnv function is used to query the value of the environment variable
	// specified in the Env option Name if the Contents of the Env option is empty.
	// If empty, os.LookupEnv will be used.
	LookupEnv func(key string) (value string, ok bool)
	// FindManifest function is used to find manifest file for the given scriptfile
	// if the Contents of Manifest option is empty.
	// If the scriptfile parameter is empty, FindManifest starts searching
	// for the manifest file from the current directory
	// If missing, the closest manifest file will be used.
	FindManifest func(scriptfile string) (contents []byte, filename string, ok bool, err error)
}

Options contains the parameters of the dependency analysis.

type Source 

type Source struct {
	// Name contains the name of the source (file, environment variable, etc.).
	Name string
	// Reader provides streaming access to the source content as an alternative to Contents.
	Reader io.Reader
	// Contents contains the content of the source (e.g. script)
	Contents []byte
	// Ignore disables automatic search and processing of that source.
	Ignore bool
}

Source describes a generic dependency source. Such a source can be the k6 script, the manifest file, or an environment variable (e.g. K6_DEPENDENCIES).

func (*Source) IsEmpty added in v0.2.3 

func (s *Source) IsEmpty() bool

IsEmpty returns true if the source is empty.

Source Files

View all Source files

Directories

Path Synopsis
cmd
Package cmd contains k6deps cobra command factory function.
 Package cmd contains k6deps cobra command factory function.
k6deps
Package main contains the main function for k6deps CLI tool.
 Package main contains the main function for k6deps CLI tool.
tools
gendoc
Package main contains CLI documentation generator tool.
 Package main contains CLI documentation generator tool.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.