feat: add project settings, getCodeReport function and Gherkin step functions

README.md

@@ -412,17 +412,25 @@ If the wait is longer than this timeout, then the promise returned by the `waitF
 `waitForResponseTimeout: number`: default timeout (in milliseconds) for `waitForResponse`/`waitForResponseToRoute` functions.
 If the wait is longer than this timeout, then the promise returned by the `waitForResponse`/`waitForResponseToRoute` function will be rejected.
 
-### Environment variables
+### Project settings
+
+General static project settings are stored in file `./autotests/projectSettings.json`. They apply to all project packs.
 
-Required environment variables are defined in the `./autotests/variables.env` file (they cannot be deleted):
+`allTestFileGlobs: string`: an array of globs covering all project test files across all packs
+(used to generate a code report).
 
-`E2ED_DOCKER_IMAGE`: the name of the docker image where the tests will run.
+`dockerImage: string | null`: the name of the docker image where the tests will run.
 The image must be based on the `e2ed` base image.
 
-`E2ED_PATH_TO_TS_CONFIG_OF_PROJECT_FROM_ROOT`: the path to TypeScript config file of the project
+`pathToTsConfigFromRoot: string`: the path to TypeScript config file of the project
 from the root directory of the project. The project should have one common TypeScript config
 for both the application code and the autotest code.
 
+`testIdentifierKey: Record<string, string>`: an object with a single field that serves as the test identifier key in the test `meta`.
+If the project does not use such a key, leave the object empty.
+
+### Environment variables
+
 You can pass the following optional environment variables to the `e2ed` process in any standard way:
 
 `E2ED_ORIGIN`: origin-part of the url (`protocol` + `host`) on which the tests will be run. For example, `https://bing.com`.

autotests/bin/runDocker.sh

@@ -5,16 +5,15 @@ set +u
 CONTAINER_LABEL="e2ed"
 DEBUG_PORT=$([[ $E2ED_DEBUG == inspect-brk:* ]] && echo "${E2ED_DEBUG#inspect-brk:}" || echo "")
 DIR="${E2ED_WORKDIR:-$PWD}"
+E2ED_DOCKER_IMAGE=$(grep -m1 \"dockerImage\": $DIR/autotests/projectSettings.json | cut -d '"' -f 4)
 E2ED_TIMEOUT_FOR_GRACEFUL_SHUTDOWN_IN_SECONDS=16
 MOUNTDIR="${E2ED_MOUNTDIR:-$DIR}"
 WITH_DEBUG=$([[ -z $DEBUG_PORT ]] && echo "" || echo "--publish $DEBUG_PORT:$DEBUG_PORT --publish $((DEBUG_PORT + 1)):$((DEBUG_PORT + 1))")
 VERSION=$(grep -m1 \"e2ed\": $DIR/package.json | cut -d '"' -f 4)
 
-source ./autotests/variables.env
-
 if [[ -z $E2ED_DOCKER_IMAGE ]]
 then
-    echo "Error: The \"autotests/variables.env\" file does not contain E2ED_DOCKER_IMAGE variable."
+    echo "Error: The \"autotests/projectSettings.json\" file does not contain dockerImage variable."
     echo "Add it so that \"runDocker.sh\" script can run the docker image."
     echo "Exit with code 9"
     exit 9

autotests/configurator/index.ts

@@ -9,6 +9,7 @@ export {mapLogPayloadInReport} from './mapLogPayloadInReport';
 export {matchScreenshot} from './matchScreenshot';
 export {regroupSteps} from './regroupSteps';
 export {skipTests} from './skipTests';
+export {testIdentifierKey} from './testIdentifierKey';
 export type {
   DoAfterPack,
   DoBeforePack,

autotests/configurator/regroupSteps.ts

@@ -1,4 +1,4 @@
-import {LogEventStatus, LogEventType} from 'e2ed/constants';
+import {LOG_EVENT_STEP_TYPES, LogEventStatus, LogEventType} from 'e2ed/constants';
 import {setReadonlyProperty} from 'e2ed/utils';
 
 import type {LogEvent, Mutable} from 'e2ed/types';
@@ -8,6 +8,7 @@ import type {LogEvent, Mutable} from 'e2ed/types';
  */
 export const regroupSteps = (logEvents: readonly LogEvent[]): readonly LogEvent[] => {
   const topLevelTypes: readonly LogEventType[] = [
+    ...LOG_EVENT_STEP_TYPES,
     LogEventType.Action,
     LogEventType.Assert,
     LogEventType.Entity,

autotests/configurator/testIdentifierKey.ts

@@ -0,0 +1,11 @@
+import {getTestIdentifierKey} from 'e2ed/configurator';
+
+import projectSettings from '../projectSettings.json';
+
+import type {GetTestIdentifierKey} from 'e2ed/types';
+
+/**
+ * Project test identifier key in test meta.
+ */
+export const testIdentifierKey: GetTestIdentifierKey<typeof projectSettings> =
+  getTestIdentifierKey(projectSettings);

autotests/configurator/types/testMeta.ts

@@ -1,6 +1,8 @@
+import type {testIdentifierKey} from 'autotests/configurator';
+
 /**
  * Test metadata parameters (testId, severity, etc).
  */
 export type TestMeta = Readonly<{
-  testId: string;
+  [testIdentifierKey]: string;
 }>;

autotests/projectSettings.json

@@ -0,0 +1,7 @@
+{
+  "allFeatureFileGlobs": [],
+  "allTestFileGlobs": ["**/autotests/tests/**/*.ts"],
+  "dockerImage": "e2edhub/e2ed",
+  "pathToTsConfigFromRoot": "./tsconfig.json",
+  "testIdentifierKey": {"testId": "key of the test identifier in test meta"}
+}

autotests/types/typeChecks.ts

@@ -0,0 +1,11 @@
+import type {Pack, testIdentifierKey} from 'autotests/configurator';
+import type {pack as allTestsPack} from 'autotests/packs/allTests';
+import type {Expect, IsEqual, IsUnion, Not} from 'e2ed/types';
+
+/**
+ * Type checks of all project packs and test identifier key.
+ */
+export type TypeChecks = [
+  Expect<IsEqual<Pack, typeof allTestsPack>>,
+  Expect<Not<IsUnion<typeof testIdentifierKey>>>,
+];

package.json

@@ -16,7 +16,7 @@
   },
   "bugs": "https://github.com/joomcode/e2ed/issues",
   "engines": {
-    "node": ">=22.14.0"
+    "node": ">=24.14.0"
   },
   "packageManager": "npm@11",
   "homepage": "https://github.com/joomcode/e2ed#readme",

src/README.md

@@ -1,6 +1,7 @@
 ## Dependency graph
 
-This is a graph of the base modules of the project with dependencies between them.
+This is a graph of the base modules of the project with dependencies between them
+(for runtime values only, not for types).
 
 Modules in the dependency graph should only import the modules above them:
 
@@ -14,46 +15,50 @@ Modules in the dependency graph should only import the modules above them:
 7. `configurator`
 8. `utils/getHash`
 9. `generators`
-10. `utils/headers`
-11. `utils/screenshot`
-12. `utils/viewport`
-13. `utils/parse`
-14. `utils/distanceBetweenSelectors`
-15. `utils/getDurationWithUnits`
-16. `utils/valueToString`
-17. `utils/error`
-18. `utils/asserts`
-19. `utils/object`
-20. `utils/uiMode`
-21. `utils/runLabel`
-22. `utils/clone`
-23. `utils/notIncludedInPackTests`
+10. `utils/require`
+11. `utils/headers`
+12. `utils/screenshot`
+13. `utils/viewport`
+14. `utils/parse`
+15. `utils/distanceBetweenSelectors`
+16. `utils/getDurationWithUnits`
+17. `utils/valueToString`
+18. `utils/error`
+19. `utils/asserts`
+20. `utils/object`
+21. `utils/uiMode`
+22. `utils/runLabel`
+23. `utils/clone`
 24. `utils/userland`
 25. `utils/fn`
 26. `utils/environment`
 27. `utils/packCompiler`
-28. `config`
-29. `utils/config`
-30. `utils/generalLog`
-31. `utils/testFilePaths`
-32. `utils/exit`
-33. `utils/promise`
-34. `utils/resourceUsage`
-35. `utils/fs`
-36. `utils/completedTestRuns`
-37. `utils/getGlobalErrorHandler`
-38. `utils/tests`
-39. `utils/end`
-40. `utils/pack`
-41. `useContext`
-42. `context`
-43. `utils/step`
-44. `utils/apiStatistics`
-45. `utils/selectors`
-46. `selectors`
-47. `utils/log`
-48. `step`
-49. `utils/waitForEvents`
-50. `utils/expect`
-51. `expect`
-52. ...
+28. `utils/config`
+29. `utils/generalLog`
+30. `utils/testFilePaths`
+31. `utils/exit`
+32. `utils/promise`
+33. `utils/resourceUsage`
+34. `utils/fs`
+35. `utils/completedTestRuns`
+36. `utils/getGlobalErrorHandler`
+37. `utils/tests`
+38. `utils/end`
+39. `utils/pack`
+40. `useContext`
+41. `context`
+42. `utils/step`
+43. `utils/apiStatistics`
+44. `utils/selectors`
+45. `selectors`
+46. `utils/log`
+47. `step`
+48. `utils/waitForEvents`
+49. `utils/expect`
+50. `expect`
+51. `config`
+
+No module imports `config`, so it is at the very bottom of the graph: it is required only lazily,
+inside the body of `getFullPackConfig` from `utils/config` (a deliberate exception to the rule
+above), and Playwright reads it by the `CONFIG_PATH` file path (as the `--config` CLI argument),
+not by import.

src/configurator/getTestIdentifierKey.ts

@@ -0,0 +1,9 @@
+import type {GetTestIdentifierKey, ProjectSettings} from '../types/internal';
+
+/**
+ * Get test identifier key from project settings.
+ */
+export const getTestIdentifierKey = <const Settings extends ProjectSettings>(
+  projectSettings: Settings,
+): GetTestIdentifierKey<Settings> =>
+  Object.keys(projectSettings.testIdentifierKey)[0] as GetTestIdentifierKey<Settings>;

src/configurator/index.ts

@@ -2,6 +2,7 @@ export type {UserlandPack as PackConfig} from '../types/internal';
 export {getDurationWithUnits} from '../utils/getDurationWithUnits';
 export {getShallowCopyOfObjectForLogs, getStringTrimmedToMaxLength} from '../utils/valueToString';
 export {RunEnvironment, startTimeInMs} from './constants';
+export {getTestIdentifierKey} from './getTestIdentifierKey';
 export {replaceFields} from './replaceFields';
 export {isDockerRun, isLocalRun, runEnvironment} from './runEnvironment';
 /** @internal */

src/constants/index.ts

@@ -9,6 +9,11 @@ export {
   NOT_FOUND_STATUS_CODE,
   OK_STATUS_CODE,
 } from './http';
-export {BACKEND_RESPONSES_LOG_MESSAGE, LogEventStatus, LogEventType} from './log';
+export {
+  BACKEND_RESPONSES_LOG_MESSAGE,
+  LOG_EVENT_STEP_TYPES,
+  LogEventStatus,
+  LogEventType,
+} from './log';
 export {FAILED_TEST_RUN_STATUSES, TestRunStatus} from './testRun';
 export {ANY_URL_REGEXP, SLASHES_AT_THE_END_REGEXP, SLASHES_AT_THE_START_REGEXP} from './url';

src/constants/internal.ts

@@ -39,7 +39,12 @@ export {
   MAX_ELEMENTS_COUNT_IN_PRINTED_ARRAY,
   MAX_STRING_LENGTH_IN_PRINTED_VALUE,
 } from './inspect';
-export {BACKEND_RESPONSES_LOG_MESSAGE, LogEventStatus, LogEventType} from './log';
+export {
+  BACKEND_RESPONSES_LOG_MESSAGE,
+  LOG_EVENT_STEP_TYPES,
+  LogEventStatus,
+  LogEventType,
+} from './log';
 /** @internal */
 export {ADDITIONAL_STEP_TIMEOUT, MESSAGE_BACKGROUND_COLOR_BY_STATUS} from './log';
 /** @internal */
@@ -54,7 +59,6 @@ export {
   COMPILED_USERLAND_CONFIG_DIRECTORY,
   COMPLETED_TEST_RUNS_PATH,
   CONFIG_PATH,
-  DOT_ENV_PATH,
   EVENTS_DIRECTORY_PATH,
   EXPECTED_SCREENSHOTS_DIRECTORY_PATH,
   GLOBAL_ERRORS_PATH,
@@ -63,6 +67,7 @@ export {
   INTERNAL_DIRECTORY_NAME,
   INTERNAL_REPORTS_DIRECTORY_PATH,
   NOT_INCLUDED_IN_PACK_TESTS_PATH,
+  PROJECT_SETTINGS_PATH,
   REPORTS_DIRECTORY_PATH,
   SCREENSHOTS_DIRECTORY_PATH,
   START_INFO_PATH,

src/constants/log.ts

@@ -33,8 +33,33 @@ export const enum LogEventType {
   InternalCore = 7,
   InternalUtil = 8,
   Unspecified = 9,
+  Given = 10,
+  When = 11,
+  Then = 12,
+  And = 13,
+  But = 14,
+  Star = 15,
 }
 
+/**
+ * `LogEvent` types of steps.
+ */
+export const LOG_EVENT_STEP_TYPES: [
+  LogEventType.Given,
+  LogEventType.When,
+  LogEventType.Then,
+  LogEventType.And,
+  LogEventType.But,
+  LogEventType.Star,
+] = [
+  LogEventType.Given,
+  LogEventType.When,
+  LogEventType.Then,
+  LogEventType.And,
+  LogEventType.But,
+  LogEventType.Star,
+] as const;
+
 /**
  * Background color of log message by test run status.
  * @internal

src/constants/paths.ts

@@ -37,10 +37,13 @@ export const INSTALLED_E2ED_DIRECTORY_PATH = relative(
 export const AUTOTESTS_DIRECTORY_PATH = 'autotests' as DirectoryPathFromRoot;
 
 /**
- * Relative (from root) path to `variables.env` file in directory with autotests.
+ * Relative (from root) path to `projectSettings.json` file in directory with autotests.
  * @internal
  */
-export const DOT_ENV_PATH = join(AUTOTESTS_DIRECTORY_PATH, 'variables.env') as FilePathFromRoot;
+export const PROJECT_SETTINGS_PATH = join(
+  AUTOTESTS_DIRECTORY_PATH,
+  'projectSettings.json',
+) as FilePathFromRoot;
 
 /**
  * Relative (from root) path to reports directory.

src/index.ts

@@ -15,4 +15,4 @@ export {WebSocketRoute} from './WebSocketRoute';
 export {createClientFunction} from './createClientFunction';
 export {createTestFunction} from './createTestFunction';
 export {expect} from './expect';
-export {step} from './step';
+export {And, But, Given, Star, step, Then, When} from './step';