feat: add the ability to write log to file (#41)

mato533 · web-flow · commit 87ba6ace59fd · 2025-06-03T00:25:00.000+09:00
## Proposed changes Add the ability to output logs to a file, mainly for the purpose of analyzing logs output to OutputChannel when the screen cannot be referenced, such as E2E testing in CI. If a directory path is set in the environment variable `VSCODE_WDIO_TRACE_LOG_PATH`, a file `vscode-webdriverio.log` will be output to that directory, and all log messages will be output to that file. This will contain all output regardless of the log level setting. ## Types of changes [//]: # 'What types of changes does your code introduce to WebdriverIO?' [//]: # '_Put an `x` in the boxes that apply_' - [ ] Polish (an improvement for an existing feature) - [ ] Bugfix (non-breaking change which fixes an issue) - [X] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update (improvements to the project's docs) - [ ] Internal updates (everything related to internal scripts, governance documentation and CI files) ## Checklist [//]: # "_Put an `x` in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code._" - [X] I have read the [CONTRIBUTING](https://github.com/webdriverio/vscode-webdriverio/blob/main/CONTRIBUTION.md) doc - [X] I have added tests that prove my fix is effective or that my feature works - [X] I have added the necessary documentation (if appropriate) - [ ] I have added proper type definitions for new commands (if appropriate) ## Further comments [//]: # 'If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...' ### Reviewers: @webdriverio/project-committers
diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md
@@ -94,6 +94,27 @@ Like in many Open Source projects we ask you to sign a **CLA** which is a Contri
 
 The WebdriverIO maintainer will review your pull request as soon as possible. They will then either approve and merge your changes, request modifications or close with an explanation.
 
+### Analyze the output of the `vscode.OutputChannel`
+
+If you would to read or save the log message of vscode.OutputChannel, you can set the directory path of the log file as environment variable `VSCODE_WDIO_TRACE_LOG_PATH`.
+Then You will then find a file called `vscode-webdriverio.log`, which contains log messages for all levels.
+
+e.g.
+
+```bash
+$ VSCODE_WDIO_TRACE_LOG_PATH=/path/to/log code .
+
+# Execute some test on the vscode with our extension.
+
+$ ls /path/to/log
+vscode-webdriverio.log
+
+$ cat /path/to/log/vscode-webdriverio.log
+[01-15 15:03:40+00:00] [INFO]  WebdriverIO Runner extension is now active
+[01-15 15:03:40+00:00] [DEBUG] Target workspace path: D:\a\vscode-webdriverio\vscode-webdriverio\samples\e2e\mocha
+[01-15 15:03:40+00:00] [DEBUG] Detecting the configuration file for WebdriverIO...: **/wdio.conf.{ts,js}
+```
+
 ### Package structure
 
 This Extension consists of several packages. Eventually, these packages will be bundled with `esbuild` and published as an Extension of VSCode.
diff --git a/packages/vscode-wdio-logger/src/fileLogger.ts b/packages/vscode-wdio-logger/src/fileLogger.ts
@@ -0,0 +1,88 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import type * as vscode from 'vscode'
+
+const LOG_FILE_NAME = 'vscode-webdriverio.log'
+
+export class FileLogger implements vscode.Disposable {
+    private _writeStream: fs.WriteStream
+    private _isDisposed = false
+    private _isWritable = false
+
+    constructor(logFilePath: string) {
+        try {
+            const absLogFilePath = path.normalize(
+                path.isAbsolute(logFilePath)
+                    ? path.join(logFilePath, LOG_FILE_NAME)
+                    : path.join(process.cwd(), logFilePath, LOG_FILE_NAME)
+            )
+
+            // Ensure directory exists
+            const logDir = path.dirname(absLogFilePath)
+            if (!fs.existsSync(logDir)) {
+                fs.mkdirSync(logDir, { recursive: true })
+            }
+
+            // Create write stream
+            this._writeStream = fs.createWriteStream(absLogFilePath, {
+                flags: 'a', // append mode
+                encoding: 'utf8',
+            })
+
+            this._isWritable = true
+
+            // Handle stream errors
+            this._writeStream.on('error', () => {
+                this.dispose()
+                this._isWritable = false
+            })
+        } catch (error) {
+            throw new Error(
+                `Failed to initialize FileLogger: ${error instanceof Error ? error.message : String(error)}`
+            )
+        }
+    }
+
+    /**
+     * Get writable status
+     */
+    public get isWritable(): boolean {
+        return this._isWritable && !this._isDisposed
+    }
+
+    /**
+     * Write log message to file
+     * @param message - Log message to write
+     */
+    public write(message: string): void {
+        if (!this.isWritable) {
+            return
+        }
+
+        try {
+            this._writeStream.write(`${message}\n`)
+        } catch (error) {
+            this._isWritable = false
+            this.dispose()
+            throw new Error(`Failed to write log: ${error instanceof Error ? error.message : String(error)}`)
+        }
+    }
+
+    /**
+     * Dispose the file logger and close the write stream
+     */
+    public dispose(): void {
+        if (this._isDisposed) {
+            return
+        }
+
+        try {
+            this._writeStream.end()
+        } catch {
+            // pass
+        } finally {
+            this._isDisposed = true
+        }
+    }
+}
diff --git a/packages/vscode-wdio-logger/src/logger.ts b/packages/vscode-wdio-logger/src/logger.ts
@@ -1,6 +1,7 @@
 import { EXTENSION_ID, LOG_LEVEL } from '@vscode-wdio/constants'
 import * as vscode from 'vscode'
 
+import { FileLogger } from './fileLogger.js'
 import type { LoggerInterface, WdioLogLevel } from '@vscode-wdio/types'
 
 export const LOG_LEVEL_NAMES: Record<LOG_LEVEL, string> = {
@@ -12,17 +13,27 @@ export const LOG_LEVEL_NAMES: Record<LOG_LEVEL, string> = {
     [LOG_LEVEL.SILENT]: 'SILENT ',
 } as const
 
-export class VscodeWdioLogger implements LoggerInterface {
+export class VscodeWdioLogger implements LoggerInterface, vscode.Disposable {
     private _timezoneString: string | undefined
     private _disposables: vscode.Disposable[] = []
     private _logLevel: LOG_LEVEL
+    private _fileLogger: FileLogger | undefined
 
     constructor(
         logLevel?: WdioLogLevel,
         private _outputChannel = vscode.window.createOutputChannel('WebdriverIO')
     ) {
         this._logLevel = this.updateLogLevel(logLevel)
 
+        if (process.env.VSCODE_WDIO_TRACE_LOG_PATH) {
+            try {
+                this._fileLogger = new FileLogger(process.env.VSCODE_WDIO_TRACE_LOG_PATH)
+                this._disposables.push(this._fileLogger)
+            } catch (error) {
+                this.error(error instanceof Error ? error.message : String(error))
+            }
+        }
+
         _outputChannel.show(true)
         this._disposables.push(_outputChannel)
 
@@ -61,15 +72,24 @@ export class VscodeWdioLogger implements LoggerInterface {
     }
 
     private log(level: LOG_LEVEL, message: unknown): void {
-        if (level < this._logLevel) {
-            return
-        }
-
         const timestamp = `[${this.getDateTime()}]`
         const serializedMsg = typeof message !== 'string' ? JSON.stringify(message) : message
         const levelText = `[${LOG_LEVEL_NAMES[level]}] `.substring(0, 7)
         const logMessage = `${timestamp} ${levelText} ${serializedMsg}`
-        this._outputChannel.appendLine(logMessage)
+
+        if (level >= this._logLevel) {
+            this._outputChannel.appendLine(logMessage)
+        }
+
+        if (this._fileLogger) {
+            try {
+                this._fileLogger.write(logMessage)
+            } catch (error) {
+                this._fileLogger = undefined
+                console.log('====')
+                this.error(error instanceof Error ? error.message : String(error))
+            }
+        }
     }
 
     public trace(message: unknown): void {
@@ -114,4 +134,10 @@ export class VscodeWdioLogger implements LoggerInterface {
 
         this._timezoneString = `${sign}${String(offsetHours).padStart(2, '0')}:${String(offsetMins).padStart(2, '0')}`
     }
+
+    dispose() {
+        for (const disposable of this._disposables) {
+            disposable.dispose()
+        }
+    }
 }
diff --git a/packages/vscode-wdio-logger/tests/fileLogger.test.ts b/packages/vscode-wdio-logger/tests/fileLogger.test.ts
@@ -0,0 +1,151 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { FileLogger } from '../src/fileLogger.js'
+
+vi.mock('node:fs', () => {
+    return {
+        existsSync: vi.fn(),
+        mkdirSync: vi.fn(),
+        createWriteStream: vi.fn(() => ({
+            on: vi.fn(),
+        })),
+    }
+})
+
+describe('FileLogger', () => {
+    const mockFileAbsPath = process.platform === 'win32' ? 'c:\\work\\path\\to\\log' : '/work/path/to/log'
+    const mockFileRelativePath = process.platform === 'win32' ? 'path\\to\\log' : 'path/to/log'
+
+    const mockStream = {
+        on: vi.fn(),
+        end: vi.fn(),
+        write: vi.fn(),
+    } as unknown as fs.WriteStream
+
+    afterEach(() => {
+        vi.restoreAllMocks()
+    })
+
+    describe('constructor', () => {
+        it('should create WriteStream with absolute directory path', () => {
+            new FileLogger(mockFileAbsPath)
+
+            expect(fs.createWriteStream).toHaveBeenCalledWith(path.join(mockFileAbsPath, 'vscode-webdriverio.log'), {
+                flags: 'a',
+                encoding: 'utf8',
+            })
+        })
+
+        it('should create WriteStream with relative directory path', () => {
+            new FileLogger(mockFileRelativePath)
+
+            expect(fs.createWriteStream).toHaveBeenCalledWith(
+                path.join(process.cwd(), mockFileRelativePath, 'vscode-webdriverio.log'),
+                {
+                    flags: 'a',
+                    encoding: 'utf8',
+                }
+            )
+        })
+
+        it('should ensure directory exists', () => {
+            const logFilePath = path.join(mockFileAbsPath, 'vscode-webdriverio.log')
+            vi.mocked(fs.existsSync).mockReturnValue(false)
+
+            new FileLogger(mockFileAbsPath)
+
+            expect(fs.mkdirSync).toHaveBeenCalledWith(path.dirname(logFilePath), {
+                recursive: true,
+            })
+        })
+
+        it('should throw error when failed to create stream', () => {
+            vi.mocked(fs.createWriteStream).mockImplementation(() => {
+                throw new Error('DUMMY ERROR')
+            })
+
+            expect(() => new FileLogger(mockFileAbsPath)).toThrowError('Failed to initialize FileLogger: DUMMY ERROR')
+        })
+
+        it('should not write the logs when error occurred once', () => {
+            vi.mocked(fs.createWriteStream).mockReturnValue(mockStream)
+
+            const fileLogger = new FileLogger(mockFileAbsPath)
+
+            const event = vi.mocked(mockStream.on).mock.calls[0][0]
+            const cb = vi.mocked(mockStream.on).mock.calls[0][1] as Function
+
+            // Emulate the Error
+            cb()
+            fileLogger.write('Expects that this is not written')
+
+            // Assertions
+            expect(event).toBe('error')
+            expect(fileLogger.isWritable).toBe(false)
+            expect(mockStream.write).not.toHaveBeenCalled()
+        })
+    })
+
+    describe('write', () => {
+        it('should write the logs', () => {
+            const dummyMsg = 'log message'
+
+            vi.mocked(fs.createWriteStream).mockReturnValue(mockStream)
+
+            const fileLogger = new FileLogger(mockFileAbsPath)
+            fileLogger.write(dummyMsg)
+
+            expect(mockStream.write).toHaveBeenCalledWith(`${dummyMsg}\n`)
+        })
+
+        it('should be disposed when error occurred', () => {
+            vi.mocked(mockStream.write).mockImplementation(() => {
+                throw new Error('DUMMY ERROR')
+            })
+            const dummyMsg = 'log message'
+
+            vi.mocked(fs.createWriteStream).mockReturnValue(mockStream)
+
+            const fileLogger = new FileLogger(mockFileAbsPath)
+            expect(() => fileLogger.write(dummyMsg)).toThrowError('Failed to write log: DUMMY ERROR')
+            expect(fileLogger.isWritable).toBe(false)
+            expect(mockStream.end).toHaveBeenCalledOnce()
+        })
+    })
+
+    describe('dispose', () => {
+        it('should call end of the WriteStream', () => {
+            vi.mocked(fs.createWriteStream).mockReturnValue(mockStream)
+            const fileLogger = new FileLogger(mockFileAbsPath)
+
+            // Pre-assertion
+            expect(fileLogger.isWritable).toBe(true)
+
+            // Act
+            fileLogger.dispose()
+
+            // Assertions
+            expect(mockStream.end).toHaveBeenCalledOnce()
+            expect(fileLogger.isWritable).toBe(false)
+        })
+
+        it('should call end of the WriteStream only once', () => {
+            vi.mocked(fs.createWriteStream).mockReturnValue(mockStream)
+            const fileLogger = new FileLogger(mockFileAbsPath)
+
+            // Pre-assertion
+            expect(fileLogger.isWritable).toBe(true)
+
+            // Act
+            fileLogger.dispose()
+            fileLogger.dispose()
+
+            // Assertions
+            expect(mockStream.end).toHaveBeenCalledOnce()
+            expect(fileLogger.isWritable).toBe(false)
+        })
+    })
+})
diff --git a/packages/vscode-wdio-logger/tests/logger.test.ts b/packages/vscode-wdio-logger/tests/logger.test.ts
