js/k6/exec: test.options object

[codebien]

This PR adds the capability for fetching the consolidated and derived options for tests using the k6/execution API. It adds a test.options object exporting all the potential set properties.

A simple example of the expected API:

import exec from 'k6/execution';

export const options = {
  vus: 10,
  duration : '30s'
};

export default function() {
  console.log(exec.test.options.scenarios.default.vus) // 10
}

Open questions

1. We are defining the default values for some objects/arrays as null. An example is Thresholds.
   Which value do we expect to get if we access properties like Thresholds? undefined or null or {} (empty object)? We will use the same value returned from the JSON marshal, at the moment, the k6 options' values are Nullable so the default value will be null.

import exec from 'k6/execution';

export const options = {
  vus: 10,
  duration : '30s'
};

export default function() {
  console.log(exec.test.options.thresholds) // what do you expect to get?
}

2. This point from the original issue is missing:

A deprecation warning should be added when a set operation on the options object is executed. (Maybe also on getting?)

In case of const, it seems not possible by spec to set back an eventual wrap/proxy for warning the access. Do we have an alternative? We used a classic JS Object but with the Object.freeze function applied.

I would define these cases before polishing and addressing edge cases.

Closes #2450

[mstoykov]

Have you thought about freezing the object that is returned so that users will get an error if they try to modify something?

[codebien]

Have you thought about freezing the object that is returned so that users will get an error if they try to modify something?

@mstoykov it would add a breaking change, if we have to do it I think could be good to give to the users at least one release before doing it, so they would have the time to migrate. WDYT?

[mstoykov]

I meant the exec.test.options ... which a completely new API - so no breaking changes ... or am I missing something?

[codebien]

Oh, you're right. 🤦‍♂️ I thought you meant the exported options object.

[olegbespalov]

Overall looks good, left a small comment 👍

[codebien]

Have you thought about freezing the object that is returned so that users will get an error if they try to modify something?

The goja.Object doesn't provide a freezing method from Go or at least I didn't find it, so I added the properties to the JS object as read-only.

I also added an integration test for monitoring the default values. Unfortunately, they will be null even in the case where we have set a value. This happens because we are coding nullable types as valid: false when we set them for default values.

Here, an example:

k6/lib/executor/ramping_vus.go

Lines 68 to 74 in 57e9942

	func NewRampingVUsConfig(name string) RampingVUsConfig {
	return RampingVUsConfig{
	BaseConfig: NewBaseConfig(name, rampingVUsType),
	StartVUs: null.NewInt(1, false),
	GracefulRampDown: types.NewNullDuration(30*time.Second, false),
	}
	}

Of course, they will be set when the user explicitly set them or the config is derived.

[mstoykov]

doesn't provide a freezing method from Go

It doesn't, but I managed to make it work for the original SharedArray implementation https://github.com/grafana/k6/pull/1739/files

[codebien]

Added the object freeze:

import exec from 'k6/execution'

export default function() {
	console.log(Object.isFrozen(exec.test.options))
	console.log(Object.isFrozen(exec.test.options.paused))
	console.log(Object.isFrozen(exec.test.options.httpDebug))
	console.log(Object.isFrozen(exec.test.options.dns))
	console.log(Object.isFrozen(exec.test.options.scenarios))
	console.log(Object.isFrozen(exec.test.options.scenarios.default))
	console.log(Object.isFrozen(exec.test.options.scenarios.default.iterations))
}

INFO[0000] true                                          source=console
INFO[0000] true                                          source=console
INFO[0000] true                                          source=console
INFO[0000] true                                          source=console
INFO[0000] true                                          source=console
INFO[0000] true                                          source=console
INFO[0000] true                                          source=console

[olegbespalov]

💪

[oleiade]

This looks awesome, congrats! Special kudos for adding the FreezeObject construct! 👍🏻 🦖

Regarding the default values of thresholds, I would prefer it to be an empty object {}, but if I console.log(options.thresholds) as of today, it prints undefined which makes sense. I can see both work, so up to you 🦕

[codebien]

Regarding the default values of thresholds, I would prefer it to be an empty object {}, but if I console.log(options.thresholds) as of today, it prints undefined which makes sense. I can see both work, so up to you 🦕

@oleiade I updated the description with the decision applied for that part, sorry for not doing it before. Reporting here also ⬇️ :

We will use the same value returned from the JSON marshal, at the moment, the k6 options' values are Nullable so the default value will be null.

At the moment, it is also the same default value reported in the docs so it shouldn't change the current UX.

[mstoykov]

LGTM

[codebien]

I rebased the fixups and applied the @mstoykov's suggestion

[codebien]

This PR will implement the doc: grafana/k6-docs#629