Testing from the command line

The testing CLI uses the same workspace suites and test runners as Nexo’s Testing region. It can run SQL, TypeScript, Bash, Windows batch (.bat / .cmd), PowerShell (.ps1) and Oracle utPLSQL packages. Start with the complete testing tutorial if you have not created tests yet.

Get a ready-to-use command

1. Install Nexo SQL Studio 2.4.0 or later, sign in, and open your test project in VS Code.
2. Save the database profiles you want to use and configure nexo.test.json as shown in the testing tutorial.
3. Open the command palette and run Nexo SQL: Copy test CLI command. Nexo prepares its runtime and copies a shell function with the correct executable, secure-helper path and workspace.
4. Paste the copied function into PowerShell on Windows or Bash on macOS/Linux, and press Enter. Then run:

nexo-test --help
nexo-test list
nexo-test run

The function lasts for that terminal session. Copy it again after an extension/runtime update, or when changing the project folder. On Windows, defining the function in PowerShell can run every supported test type, including Bash and batch. The terminal hosting the CLI does not determine the test file’s interpreter.

The copied command contains local paths and configuration, not database passwords. The CLI reads credentials from Nexo’s protected store and uses your authorized workspace and saved connection safeguards. It needs the same valid Nexo access as the connector. On first access, a native authorization prompt may ask you to approve the client/workspace; confirmations configured on connections or environments still apply.

The database, required script interpreters and any external tools used by your tests must be available on the machine running the CLI. Keep using Nexo’s connection settings to manage credentials and access.

Discover and filter workspace tests

# List the tests without opening a database session.
nexo-test list

# Run only SQL files.
nexo-test run --kind sql

# Run TypeScript tests whose suite or test name includes "orders".
nexo-test run --kind ts --grep orders

# Run every supported shell format: Bash, batch and PowerShell.
nexo-test run --kind sh

# Include any test tagged smoke or regression.
nexo-test run --tag smoke --tag regression

# Stop scheduling additional workspace tests after a failure.
nexo-test run --bail

--grep is a case-insensitive substring match on workspace suite/test names. Tags match any listed value, including tags inherited from suites. Repeat --kind to combine providers. Use include in nexo.test.json when you want to choose exact files or file extensions. Script formats share the sh provider name.

The runner executes prepare and finalize for selected suites. A failed prepare prevents its tests from running, and finalize still gets a cleanup attempt. Cancellation and --bail can leave unstarted tests marked skipped; review the run status and hooks along with assertion counts.

Set timeouts in nexo.test.json: timeoutMs controls individual tests and hooks. TypeScript files have a separate ts.fileTimeoutMs limit, defaulting to 30 minutes, so large parameterized files do not depend on the editor’s estimated test count.

Choose the workspace, default connection and environment

nexo-test run --workspace ./my-project
nexo-test run --connection app
nexo-test run --environment qa
nexo-test run --environment qa --kind sql --tag smoke

--connection sets the default connection reference. A test or suite with its own @connection/connection still uses that explicit value. Aliases resolve against nexo.test.json; --environment chooses their environment mapping. It does not rename a literal connection reference.

Relative report paths are resolved from the selected workspace, even if your terminal is elsewhere. Scripts run from their own file’s folder.

Run Oracle utPLSQL packages

Compile your test packages into the application schema first. The CLI runs installed packages; it does not install utPLSQL or compile package files automatically. Use Nexo’s setup assistant and utPLSQL tutorial for initial setup.

# Run only one package on the default application connection.
nexo-test run --kind utplsql --utplsql APP_00001.NEXO_TEST_MATH

# Run several packages and export the results.
nexo-test run --kind utplsql --utplsql APP_00001.NEXO_TEST_MATH --utplsql APP_00001.TEST_ORDERS --junit reports/packages.xml

# Run workspace tests and then the specified package in one report.
nexo-test run --utplsql APP_00001.NEXO_TEST_MATH --json reports/all-tests.json

--utplsql accepts an unquoted PACKAGE or SCHEMA.PACKAGE name and can be repeated. Without --kind utplsql, selected workspace tests run first, followed by those packages. Package execution uses the default connection; pass --connection if needed. Use the application account that owns or has access to the tests.

Workspace --grep and --tag filters do not filter individual routines inside these package runs. The package’s utPLSQL annotations control its disabled tests. list --utplsql ... shows the requested package names without connecting or discovering their routines.

Use Run with coverage in the Testing UI for utPLSQL line coverage. The CLI’s --coverage flag collects available workspace SQL object coverage; it cannot be combined with --utplsql.

Export results and use exit codes

nexo-test run --junit reports/tests.xml --json reports/tests.json

The CLI prints individual outcomes and a final count. It also saves the run in the workspace’s private .nexo/test/runs history. JUnit XML is suitable for build-server test reports. Nexo JSON preserves the run, assertion details, hook results and available coverage.

Example output:

PASSED prepare tests/orders/prepare.sql
PASSED calculates the baseline total
PASSED reads the database
SKIPPED example to implement later: Waiting for the discount rule
PASSED finalize tests/orders/finalize.sql
4 tests: 3 passed, 0 failed, 0 errored, 1 skipped

Counts depend on the files and filters you choose. A skipped test is not a failed assertion. A failed prepare/finalize still makes the command fail.

Exit code	Meaning
0	The selected run finished without failed/errored tests or failed hooks.
1	A test failed, execution errored, a hook failed, or the run failed.
2	Invalid arguments/configuration, an initialization error, or no matching tests.
130	The run was cancelled, for example with Ctrl+C.

For example, in PowerShell:

nexo-test run --junit reports/tests.xml --json reports/tests.json
$testExit = $LASTEXITCODE
if ($testExit -ne 0) {
  Write-Error "Nexo tests did not pass (exit $testExit). See reports/tests.json."
  exit $testExit
}

Or in Bash:

set -euo pipefail
nexo-test run --junit reports/tests.xml --json reports/tests.json

These examples assume you first pasted the copied nexo-test function into that shell. A fresh CI worker does not inherit a developer’s function, saved connections or protected credentials. Configure Nexo’s runtime and authorized store on the runner before using it there. Interactive native approvals require an interactive user session; the copy action is intended for a machine with a configured Nexo installation, rather than a password-based unattended bootstrap.

Options reference

Run nexo-test --help for the installed version’s exact options.

Option	Purpose
run	Execute tests; this is also the default command.
list	Discover selected workspace tests without database execution.
--workspace <folder>	Choose the project folder.
--connection <name>	Set the default saved connection name or alias.
--environment <name>	Choose an alias environment mapping.
--kind <sql|ts|sh|utplsql>	Restrict providers; repeat to combine them.
--grep <text>	Match workspace names by substring.
--tag <tag>	Include workspace tests with any matching tag; repeatable.
--utplsql <package>	Run an installed Oracle package; repeatable.
--coverage	Collect available workspace SQL object coverage.
--bail	Stop scheduling more workspace tests after a failure.
--junit <file>	Export a JUnit XML report.
--json <file>	Export a Nexo JSON report.
--bun <executable>	Override Bun used for TypeScript tests and hooks.
--helper <file>	Secure helper path; already included in the copied function.
--store-scope <name>	Protected store scope; already included when needed.
--api-url <url>	Nexo account endpoint; already included in the copied function.

Troubleshooting

If the function is unknown, paste the copied command in the current terminal again. If its executable path no longer exists, recopy it after updating Nexo. If no tests match, run list, check your include/exclude patterns, and temporarily remove filters.

For connection or access errors, open that workspace in Nexo, check sign-in, confirm that the profile is available to the workspace, and review its connection/environment safeguards. The CLI never reads a database password from nexo.test.json. SQL tests require write-capable access because they create isolated transactions and may execute setup, cleanup or DML.

For script failures, inspect captured output in the JSON report. Check that Bash/Git Bash, curl, Windows PowerShell or pwsh is available as appropriate. Batch files require Windows. For TypeScript, the copied command uses Nexo’s Bun; ts.runner: "auto" can use the project’s Vitest installation when present.

Back to the complete testing tutorial →