Tungsten Frontend Framework

Docs

Component testing

Test-specific APIs are available from tungsten/testing and are not exported from Tungsten's main entry point. A test project supplies its own DOM implementation, such as happy-dom or jsdom:

import { Window } from 'happy-dom'
import { createTestApp } from 'tungsten/testing'

describe('RootComponent', () => {
    it('responds to a button click', async () => {
        const window = new Window()
        const testApp = await createTestApp(RootComponent, {
            document: window.document as unknown as Document,
            props: { initialName: 'Robert' },
            location: '/',
        })

        try {
            const button = testApp.container.querySelector('button')
            expect(button).not.toBeNull()

            button!.dispatchEvent(new window.Event('click') as unknown as Event)
            await testApp.resolved()

            expect(testApp.container.textContent).toContain('Robert')
        } finally {
            await testApp.unmount()
        }
    })
})

The casts are only needed when a DOM package publishes types which are not structurally compatible with the TypeScript DOM library version used by the test project.

createTestApp() completes the initial client render before returning. resolved() subsequently waits for Tungsten updates, DOM reconciliation, lifecycle-triggered updates, and promises returned by registered event handlers. It does not wait for unrelated timers, network requests, or promises which the application has not returned to Tungsten.

An automatically created container is appended to the supplied document body and removed by unmount(). A caller-supplied container must be empty; it is emptied but retained during unmount.

Registered stores are created independently for each test application. Use testStore() to initialize one before the root component starts:

import { createTestApp, testStore } from 'tungsten/testing'

const testApp = await createTestApp(RootComponent, {
    document,
    stores: [testStore(userStore, store => {
        store.user.set(mockUser)
    })],
})

Tests containing Tungsten JSX must be compiled through tungsten compile so they use Tungsten's JSX runtime and application transforms.

Preparing code for tests

Run a one-shot development compilation without starting a server:

tungsten compile

By default this compiles JavaScript (including JSX and Tungsten's Babel transforms), stylesheets, client support files, assets, and public files into .tungsten/dev. Each selected target's existing generated output is cleaned before the initial compilation, including when watch mode is used. Pass --no-clean to preserve existing output.

Use --output to select an independent output root. The layout below that root is the same as .tungsten/dev, including code, .client, .static, .assets, .public, .componentCss, and .packages:

tungsten compile --output .tungsten/test
tungsten compile --output .tungsten/test --watch

Cleaning and generated package-cache data are scoped to the selected output. Limit the work with one or more options:

tungsten compile --js
tungsten compile --css
tungsten compile --client
tungsten compile --assets
tungsten compile --public
tungsten compile --js --css

--all explicitly selects all five targets.

Add --watch to keep the JavaScript, stylesheet, asset, and/or public-file compiler running after the initial pass. Client support files are still generated once:

tungsten compile --watch
tungsten compile --js --watch

For process orchestration, --ready-file <file> writes a small JSON file only after the initial compilation succeeds. A failed JavaScript watch cycle removes the file, and a later successful cycle recreates it. --quiet suppresses per-file transformation messages while retaining errors and cycle status:

tungsten compile --watch --output .tungsten/test \
  --ready-file .tungsten/test.ready --quiet

Preserving package imports in selected files

Use skipPackageCompilation in tungsten.config.js for files that should be transformed and emitted without Tungsten traversing or copying their package dependencies. Bare package imports in matching files are left unchanged:

export default {
    skipPackageCompilation: '**/*.domTest.js'
}

The option accepts one glob or an array of globs. Patterns match the actual JavaScript files received by Tungsten; extensions are not translated.