Tests

Tests

Overview of the extension's tests and how to run them.

Test types

Type	Runner	Location	Requires database?
Unit	node --test	src/test/unit/	No
Integration	@vscode/test-cli	src/test/integration/	Optional (with .env)

Unit tests

Test pure modules (no vscode dependency) — the full list of compiled files:

src/test/unit/  (TypeScript source; runs in out/test/unit/)
├── cobertura.test.ts
├── codelens.test.ts
├── compileForDebug.test.ts
├── config.test.ts
├── connectionProfiles.test.ts
├── coverage.test.ts
├── dbSourceProvider.test.ts
├── dbmsDebug.test.ts
├── debounce.test.ts
├── debugger.test.ts
├── decorations.test.ts
├── discovery.test.ts
├── i18n.test.ts
├── junit.test.ts
├── logger.test.ts
├── manifestDebugger.test.ts
├── matching.test.ts
├── matrixConfig.test.ts
├── oracleClient.test.ts
├── oracleRunner.test.ts
├── oracledb-default-absent.test.ts
├── oracledb-missing-catch.test.ts
├── packageTarget.test.ts
├── plsqlDeclarations.test.ts
├── quickfix.test.ts
├── quickfixActivation.test.ts
├── rerun.test.ts
├── results.test.ts
├── runner.test.ts
├── scriptRunner.test.ts
├── scriptsCli.test.ts
├── selectReporterCommand.test.ts
├── state.test.ts
├── statusBar.test.ts
├── suiteParser.test.ts
├── testTree.test.ts
└── viewCoverage.test.ts

Tests using mock.module (oracledb-missing-catch.test.ts, oracledb-default-absent.test.ts) need --experimental-test-module-mocks. That flag is already wired into npm run test:unit and npm run test:coverage.

There is also TypeScript coverage with c8:

npm run test:coverage   # thresholds: 90% lines/statements/functions, 85% branches

How to create a test

1. Create src/test/unit/my_module.test.ts:

import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { myFunction } from '../../my_module.js';

describe('myFunction', () => {
  it('returns x for input y', () => {
    assert.strictEqual(myFunction('y'), 'x');
  });

  it('throws an error for invalid input', () => {
    assert.throws(() => myFunction(null));
  });
});

2. If the test uses vscode-dependent modules, add the following line at the top:

import './setup.js';  // redirects require('vscode') → stub

How to run

# All
npm test

# Specific file
node --test out/test/unit/junit.test.js

# By name pattern
node --test --test-name-pattern "parse" out/test/unit/**/*.test.js

node --test <directory> fails (tries to load the folder as a module). Always use the glob out/test/unit/**/*.test.js. Compile before running (npm run compile).

Integration tests

Test the extension inside a real VSCode instance:

src/test/integration/
├── extension.test.ts
├── oracleCapabilities.test.ts
├── v012-features.test.ts
├── v013-features.test.ts
├── compileForDebug.test.ts
├── dbPaths.test.ts
├── prd70-sqlplus.test.ts
├── schemaRun.test.ts
├── debuggerE2E.test.ts
├── debuggerStandaloneFn.test.ts
└── thickMode.test.ts

Integration tests have two modes:

• Without database: test discovery, commands, UI — do not require Oracle
• With database (describeDB): test real execution, coverage, reporters — require Oracle + environment variables

Fast subsets / modes:

• npm run test:integration:smoke — only Oracle capabilities + the DBMS_DEBUG cycle (package via direct call and standalone function/namespace toplevel, ~1 min).
• npm run test:integration:thick — thick mode (Instant Client) in an isolated host; needs ORACLE_CLIENT_LIB_DIR.
• npm run db:matrix — runs the suite against multiple Oracle versions (see Contributing).

Setup

Create a .env file at the project root:

UTPLSQL_CONN=UT3/password@//localhost:1521/XEPDB1

Database fixtures

Tests with database use a test schema with example packages:

src/test/integration/fixtures/
├── setup.sh                       ← environment setup script
├── setup.sql                      ← schema creation + grants (idempotent)
├── compile_packages.sql           ← test package compilation
├── settings.example.json          ← example workspace settings
├── test_betwnvarchar.pks          ← example suite 1
├── test_calculator.pks/.sql       ← suite + production object
├── test_employees.pks             ← example suite 3
├── test_math.pks                  ← example suite 4
└── test_math_fail.pks             ← suite with intentional failure

How to run

npm run test:integration

VSCode stub

Modules that depend on vscode use src/test/vscode-stub.ts — a complete mock of the VSCode APIs (TestController, TestRun, workspace, etc.). The stub is loaded in two ways:

1. import './setup.js' at the top of the test file (explicit)
2. --require scripts/test-setup.cjs in the global runner (safety net)