Implementation:Webdriverio Webdriverio StaticServerLauncher Class

Knowledge Sources	Webdriverio_Webdriverio
Domains	Static_Server, Service_Lifecycle
Last Updated	2026-02-12 00:00 GMT

Overview

Express-based static file server service launcher that serves local files during WebdriverIO test runs.

Description

StaticServerLauncher implements Services.ServiceInstance and provides a lightweight HTTP server using Express. The constructor accepts a configuration object with folders (one or more mount-path pairs), an optional port (defaulting to 4567), and optional middleware (custom Express middleware). During the onPrepare lifecycle hook, it creates an Express app, optionally configures Morgan request logging to the outputDir, mounts each folder as static content via express.static(), registers custom middleware, and starts listening on the configured port. This allows tests to access locally served files without requiring an external web server.

Usage

Use this service when tests need to load local HTML, CSS, JavaScript, or other static assets via HTTP. Register it in the WebdriverIO configuration with folder paths and mount points. It is commonly used for testing static sites, component libraries, or single-page applications during local development and CI.

Code Reference

Source Location

• Repository: Webdriverio_Webdriverio
• File: packages/wdio-static-server-service/src/launcher.ts

Signature

export default class StaticServerLauncher implements Services.ServiceInstance {
    private _folders: FolderOption[] | null
    private _port: number
    private _middleware: MiddleWareOption[]
    private _server?: Express

    constructor({ folders, port, middleware }: {
        folders?: FolderOption[] | FolderOption,
        port?: number,
        middleware?: MiddleWareOption[]
    })

    async onPrepare({ outputDir }: { outputDir?: string }): Promise<void>
}

Import

import StaticServerLauncher from '@wdio/static-server-service/launcher'

I/O Contract

Inputs

Name	Type	Required	Description
folders	FolderOption[] or FolderOption	No	Folder-mount pairs to serve as static content; each has mount (URL path) and path (filesystem path)
port	number	No	Port to bind the Express server (default: 4567)
middleware	MiddleWareOption[]	No	Custom Express middleware to register, each with mount and middleware properties
outputDir	string	No	Output directory for Morgan request logs (file: wdio-static-server-service.log)

Outputs

Name	Type	Description
void	void	The server starts listening on the configured port; no return value

Methods

constructor(options)

Initializes the launcher with folder configurations (normalizing a single FolderOption to an array), port number, and middleware array. If no folders are provided, _folders is set to null and the server will not start.

onPrepare({ outputDir })

Called by the WebdriverIO test runner before tests begin. Creates an Express app, optionally sets up Morgan logging to a file in outputDir, mounts each folder path as static content at its corresponding mount point, registers custom middleware, and starts the server on the configured port. If _folders is null, it returns immediately without starting a server.

Usage Examples

// wdio.conf.ts
export const config = {
    services: [
        ['static-server', {
            folders: [
                { mount: '/', path: './dist' },
                { mount: '/assets', path: './public/assets' }
            ],
            port: 8080
        }]
    ]
}

// Programmatic usage
import StaticServerLauncher from '@wdio/static-server-service/launcher'

const launcher = new StaticServerLauncher({
    folders: [{ mount: '/', path: './build' }],
    port: 3000
})

await launcher.onPrepare({ outputDir: './logs' })
// Server is now running at http://localhost:3000

Related Pages

• Principle:Webdriverio_Webdriverio_Service_Lifecycle