utPLSQL Test Runner

Integrates utPLSQL into VSCode, bringing PL/SQL tests to the native Test Explorer, with context menu and visual coverage.

• 🧪 Native Test Explorer — suites and tests appear in the testing view; run by test, suite, file, or folder.
• 🔍 CodeLens — Run/Run with Coverage buttons over %suite and %test in the editor, without leaving your code.
• ⌨️ Keyboard shortcuts — Ctrl+Shift+U prefix + key for the main commands (R = Run All, T = Run File, L = Rerun Last, etc.).
• 🖱️ Context menu — right-click a folder or a .pks/.pkb file (in the Explorer or in the editor) to run tests.
• 📊 Visual coverage — colored gutters per line (covered/not covered) and per-file percentage in the Coverage tab.
• ✅ Inline decorations — ✓/✗/⚠ icons in the editor after execution, with failure tooltip and overview ruler.
• 📌 Status Bar — indicator with pass/fail count, duration, and real-time progress.
• 🔁 Smart Re-run — Rerun Last, Run at Cursor, Run Failed Only with a single shortcut.
• 🚀 Oracle direct (via node-oracledb) — real-time streaming, without waiting for the batch to finish.
• 🔧 Setup diagnostics — proactive validation of connection, grants, and version with quick-fix.
• 🧩 Schema-aware tree — organize tests by Schema > Package > Suite > Test in the Test Explorer.
• 🎯 Jump to failure — direct navigation to the line of the assertion that failed (via native "Go to Error").
• 🔌 Connection profiles — save and switch between multiple environments (DEV/TEST/PROD) with per-profile settings, via status bar or command palette.
• 📜 SQL scripts — run the current script, an Explorer file, or a whole folder against the active connection profile (charset-aware, with DBMS_OUTPUT and stopOnError).
• 📈 Statement and view coverage — the Coverage tab shows % of statements (PROCEDURE/FUNCTION) per file and tracks views executed via V$SQL.
• 🏷️ Tags and random order — filter tests with utplsql.tags (e.g. fast & !integration) and run in random order with a reproducible seed (utplsql.run.randomOrder).
• 🎯 Coverage scope — include/exclude objects and schema/object regexes (utplsql.coverage.*) to drop framework noise and add dynamically reached objects.
• 🗄️ Database-first discovery — build the tree from ut_runner.get_suites_info and rebuild the annotation cache from the palette.
• 🐛 PL/SQL Debug — breakpoints and step debugging of utPLSQL tests via DBMS_DEBUG (native Debug Adapter).
• 🌍 i18n — 24 languages — utplsql.language follows VSCode (24 locales: pt-br, en, en-gb, es, zh-cn, zh-tw, ja, de, fr, it, ko, ru, tr, pl, cs, hu, bg, el, id, ro, sr, th, uk, vi).

Installation

The extension can be installed in two ways:

1. From the Marketplace: Search for utPLSQL Test Runner in the VSCode extensions panel (Ctrl+Shift+X) and click Install.
2. Manually (.vsix): Download the .vsix file of the desired version and install it in VSCode:
   • Via Command Line: code --install-extension vscode-utplsql-<version>.vsix
   • Via Interface: Open the Extensions panel (Ctrl+Shift+X), click the three dots ... (top-right corner) and select Install from VSIX....

Requirements

• utPLSQL (UT3) installed in the Oracle database.
• VSCode 1.88+ (Test Coverage API).

The extension connects directly to the Oracle database via node-oracledb (thin driver, no Instant Client required). The VSIX already includes the oracledb package.

Oracle / utPLSQL compatibility:

Connection

The extension needs an Oracle connection string to run tests. Resolution follows this order:

1. Active connection profile — utplsql.activeProfile pointing to a profile in utplsql.profiles (overrides everything below).
2. utplsql.connection setting — read from the project/user settings.json.
3. UTPLSQL_CONN environment variable — set before opening VSCode.
4. Session cache — if the user already typed the connection via prompt.
5. Prompt to the user — asks and keeps it only in the current session.

Connection profiles (utplsql.profiles) can also override sourcePath, coverageOwner, etc. per environment — see utplsql.activeProfile in the configuration table.

⚠️ Security recommendation: the connection string contains a password. DO NOT use the utplsql.connection setting in shared environments (settings.json may be versioned or visible to others). Instead, use the UTPLSQL_CONN environment variable:

# PowerShell
$env:UTPLSQL_CONN = "user/password@//host:1521/service"
code .

# Bash
export UTPLSQL_CONN="user/password@//host:1521/service"
code .

If neither the setting nor the env var is defined, the extension asks for the connection and keeps it only in memory during the session — use the command utPLSQL: Clear session connection (command palette) to clear it.

Accepted formats:

• EZ Connect: user/pass@//host:1521/service
• TNS alias: user/pass@tns_alias (requires TNS_ADMIN configured)
• Wallet (Oracle Cloud): user/pass@tcps://host:1522/service?wallet_location=/path/wallet

How it works

The extension connects directly to the Oracle database via node-oracledb, streams test results in real-time, and translates them into VSCode's native APIs.

No temporary files, no waiting for the batch. Results appear in the Test Explorer as each test finishes.

Configuration

Example (project .vscode/settings.json):

{
  "utplsql.sourcePath": "install",
  // utplsql.connection stays empty -> use the UTPLSQL_CONN environment variable
}

And, before opening VSCode (or in the PowerShell profile):

$env:UTPLSQL_CONN = "DEV/password@//localhost:1521/XEPDB1"

For contributors

Create a .env file at the project root (gitignored) with the environment variables used by the integration tests:

UTPLSQL_CONN=your_user/password@//host:1521/service

Usage

1. Open the PL/SQL project (with the code and test packages).
2. Compile the code and tests in the database (Oracle extension / SQLcl).
3. Open the Testing view → the suites appear.
4. Run:
   • Via CodeLens — ▶ Run/Run with Coverage buttons over each %suite and %test in the editor.
   • Via the gutter next to each test/suite, or
   • Via the keyboard shortcuts (Ctrl+Shift+U R = Run All, Ctrl+Shift+U T = Run File, etc.), or
   • The Run Tests button of the Test Explorer view, or
   • Right-click a folder/file → utPLSQL: Run tests… (with or without coverage).
5. After execution, see:
   • Inline decorations (✓/✗/⚠) in the editor next to the test annotations.
   • Status Bar with pass/fail count and total duration.
   • Test Explorer with detailed results.
6. For coverage, use the Run with Coverage profile (or the "with coverage" menu item).
7. To quickly repeat executions:
   • Ctrl+Shift+U L — Rerun Last (repeats the last execution, with or without coverage).
   • Ctrl+Shift+U U — Run at Cursor (runs the %test/%suite under the cursor).
   • Ctrl+Shift+U X — Run Failed Only (runs only the tests that failed).
8. For diagnostics, use utPLSQL: Show information in the palette — shows API/DB versions with a copy option.
9. utPLSQL: Select additional reporter... — QuickPick with the reporters available in the database.
10. utPLSQL: Cancel run — stops the running execution (Escape during execution).
11. utPLSQL: Refresh tests — forces rediscovery of .pks.

💡 When writing tests: the parser is token-driven — just have %suite and the create package declaration in the file, and each %test followed by its PROCEDURE. There is no blank-line requirement.

Supported annotations (v0.10.0+)

Besides %suite and %test, discovery understands:

Annotations are case-insensitive. In the suite header (between %suite and the first %test) they apply to the suite; after %test, they apply to the test.

Commands

All extension commands (palette Ctrl+Shift+P prefix utPLSQL:):

Recompile UT3 (utplsql.recompileUt3) is not a palette command — it is an internal quick-fix of the "utPLSQL Setup" diagnostic (invalid objects in the utPLSQL schema).

Keybindings

All shortcuts use the Ctrl+Shift+U prefix (Cmd+Shift+U on Mac):

Coverage

• Executed lines turn green in the gutter; not executed lines turn red.
• The Test Coverage tab shows the percentage per file/folder.

Coverage is reported via ut_coverage_cobertura_reporter and mapped to source files automatically using the utplsql.sourcePath setting and the utplsql.coverageOwner schema. The extension resolves package, package body, function, procedure, type body, trigger and view objects, trying .sql, .pks, .pkb, .prc, .fnc, .trg, .tpb and .bdy under the source folders.

Reporters

The extension always includes two default reporters: ut_documentation_reporter (stdout) and ut_junit_reporter (results → Test Explorer). The ut_coverage_cobertura_reporter is added only when running with coverage.

Dynamic validation — before running with coverage, the extension queries the database via TABLE(ut_runner.get_reporters_list()) to verify that UT_COVERAGE_COBERTURA_REPORTER exists. If it doesn't (e.g. outdated utPLSQL), coverage is skipped with a warning in the output. Test execution is never blocked.

Additional fixed reporters — setting utplsql.additionalReporters:

"utplsql.additionalReporters": ["UT_COVERAGE_HTML_REPORTER"]

The default reporters are automatically deduplicated, even if listed here.

Volatile per-session reporter — command utPLSQL: Select additional reporter... opens a QuickPick with the dynamic list from the database. The chosen reporter is stored in the session and applied to the next run (consumeExtraReporter(), logged as [info] Reporter adicional da sessão).

Database requirements

Coverage (always) — enables the profiler:

GRANT EXECUTE ON SYS.DBMS_PROFILER TO <schema_that_runs_the_tests>;
GRANT EXECUTE ON SYS.DBMS_PLSQL_CODE_COVERAGE TO <schema_that_runs_the_tests>;

Without this, tests run but coverage comes out empty.

Test discovery in OTHER schemas (utPLSQL shared install, e.g. owner UT3): for the framework to see and parse the tests of the application schemas, the utPLSQL owner needs to read the dictionary of those schemas:

GRANT SELECT ON SYS.DBA_SOURCE     TO <ut3_owner>;
GRANT SELECT ON SYS.DBA_OBJECTS    TO <ut3_owner>;
GRANT SELECT ON SYS.DBA_PROCEDURES TO <ut3_owner>;

• SELECT ANY DICTIONARY alone is NOT enough — it needs the direct grants on those views (because of dbms_assert.sql_object_name in definer context).
• The utPLSQL DDL trigger must also be installed (keeps the annotation cache up to date).
• Verification (as the owner): SELECT ut_metadata.get_source_view_name FROM dual; should return dba_source.

In per-schema installs (utPLSQL in the same schema as the tests), these cross-schema grants are not needed — the framework reads its own source.

Known limitations

• The result→test mapping is done by package name + test name/description; identical descriptions in different packages can create ambiguity (the index is scoped by package to minimize this).
• Considers the first workspace folder to resolve sourcePath.
• Discovery reads the .pks (specs); keep the %suite/%test annotations in the spec.

Troubleshooting

Disclaimer

This is an independent community project. It is not affiliated with, endorsed by, or sponsored by the utPLSQL framework team or Oracle Corporation. utPLSQL and Oracle are trademarks of their respective owners.

License

MIT © Gil Cleber Barboza