#@lynx-js/testing-environment

npm · Source · Changelog

@lynx-js/testing-environment is a pure-JavaScript implementation of the Lynx Spec, notably the Element PAPI and Dual-threaded Model for use with Node.js. In general, the goal of the project is to emulate enough of a subset of a Lynx environment to be useful for testing.

The Element PAPI implementation is based on jsdom, for example __CreateElement will return a LynxElement, which extends HTMLElement from jsdom. You can reuse the testing utilities that are commonly used for DOM testing, such as @testing-library/dom (for DOM querying) and @testing-library/jest-dom (custom jest matchers for the DOM), etc.

#Usage

import { LynxTestingEnv } from '@lynx-js/testing-environment';
import { JSDOM } from 'jsdom';

const lynxTestingEnv = new LynxTestingEnv({ window: new JSDOM().window });

To use @lynx-js/testing-environment, you will primarily use the LynxTestingEnv constructor, which is a named export of the package. You will get back a LynxTestingEnv instance, which has a number of methods of useful properties, notably switchToMainThread and switchToBackgroundThread, which allow you to switch between the main thread and background thread.

Use the background thread API:

lynxTestingEnv.switchToBackgroundThread();
// use the background thread global object
globalThis.lynxCoreInject.tt.OnLifecycleEvent(...args);
// or directly use `lynxCoreInject` since it's already injected to `globalThis`
// lynxCoreInject.tt.OnLifecycleEvent(...args);

Use the main thread API:

lynxTestingEnv.switchToMainThread();
// use the main thread Element PAPI
const page = __CreatePage('0', 0);
const view = __CreateView(0);
__AppendElement(page, view);

Note that you can still access the other thread's globals without switching threads:

lynxTestingEnv.switchToMainThread();
// use the `backgroundThread` global object even though we're on the main thread
lynxTestingEnv.backgroundThread.tt.OnLifecycleEvent(...args);

#Use in Vitest

It is recommended to configure as Vitest's test environment, for example:

// vitest.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: require.resolve(
      '@lynx-js/testing-environment/env/vitest',
    ),
  },
});

After configuration, you can directly access the lynxTestingEnv object globally in the test.

If you want to use @lynx-js/testing-environment for unit testing in ReactLynx, you usually don't need to specify this configuration manually.

Please refer to ReactLynx Testing Library to inherit the configuration from @lynx-js/react/testing-library.

#Use in Rstest

If your runner already provides a window global via jsdom, you can load the shared Lynx test environment with:

import '@lynx-js/testing-environment/env/rstest';

#Credits

Thanks to:

• jsdom for the pure-JavaScript implementation of DOM API.

A pure-JavaScript implementation of the Lynx Spec, notably the Element PAPI and Dual-threaded Model for use with Node.js.

#Classes

• GlobalEventEmitter
• LynxTestingEnv

#Interfaces

• LynxElement
• LynxEnv
• LynxGlobalThis

#Type Aliases

• ElementTree
• ElementTreeGlobals
• FilterUnderscoreKeys
• PickUnderscoreKeys

#Functions

• initElementTree
• installLynxTestingEnv
• uninstallLynxTestingEnv