VS Code Features

Norn is not just a file format. The extension adds editor actions, test integration, Swagger coverage tooling, and environment-aware execution inside VS Code.

CodeLens in .norn Files

Clickable CodeLens actions appear directly above relevant lines in .norn files.

• ▶ Send Request appears above standalone HTTP requests outside sequences.
• ▶ Run Sequence appears above runnable sequence and test sequence declarations.
• ▷ Debug Sequence appears next to runnable sequences for step-through debugging.
• env: ... or + Add env file appears next to request and sequence actions so you can switch or create environments without leaving the editor.
• Open Contract and View Contract appear on matchesSchema assertions.

GET https://api.example.com/health

test sequence ContractCheck
    GET https://api.example.com/users/1
    assert $1.body matchesSchema "./schemas/user.schema.json"
end sequence

▶ Send Request does not appear for requests inside a sequence because those requests run as part of the sequence action instead.

Contract Validation

Schema assertions integrate with the editor workflow, so you can move from a failing response to the exact contract mismatch quickly.

• Open Contract opens the schema file referenced by a matchesSchema assertion. Paths can be relative or use the @/ alias for the workspace contracts/ folder.
• View Contract reruns the enclosing sequence and opens a contract report for that assertion.
• Hovering a validated matchesSchema line shows the current pass or fail status, schema path, last run, and a shortcut to open the contract view.
• Response panel results show contract cards with the schema name, validation counts, validated properties, and the most relevant issues.
• When schema validation fails in the response panel, the assertion output includes View Contract Details so you can inspect the mismatch directly from the run results and return with Back to Results.

test sequence GetUserContract
    GET {{baseUrl}}/users/1
    assert $1.status == 200
    assert $1.body matchesSchema "@/users/get-user-200.schema.json"
end sequence

The contract report separates breaking issues from warnings and lets you switch between the issue list, validated properties, annotated response, and resolved schema.

Response-Body IntelliSense and Diagnostics

After a successful explicit VS Code run, Norn can reuse sampled response-shape metadata to make body-path authoring faster without storing live payload data.

• Send Request and Run Sequence cache bounded response-shape metadata in .norn-cache/api-response-intellisense.json.
• Later completions for $1.body. and captured response variables such as user.body. can suggest cached properties, including nested object paths.
• The cache stores property names, type summaries, request identity, and cachedAt, but not raw response values, request bodies, headers, cookies, tokens, or secrets.
• CLI runs do not write this IntelliSense cache.
• Diagnostics flag undefined base variables in bare expressions such as assert missing.status == 200 while keeping runtime-shaped JSON property paths quiet when the base variable exists.

sequence InspectUser
    var user = GET https://api.example.com/users/1

    # After the first successful VS Code run, both lines benefit from cached body-path completion.
    assert user.body.profile.email exists
    assert $1.body.profile.email exists
end sequence

CodeLens in .nornapi Files

Swagger lines in .nornapi files expose API-definition actions.

• Import Endpoints parses the OpenAPI/Swagger spec and generates endpoint definitions.
• Generate Schemas creates JSON Schema files from response definitions.
• Show Coverage opens API coverage for that .nornapi file and its folder scope.
• Endpoint URLs and header groups highlight {{variables}} the same way as .norn files, and diagnostics flag unresolved environment-backed endpoint variables.

swagger "https://petstore.swagger.io/v2/swagger.json"

CodeLens in .nornenv Files

.nornenv files get editor support for environment authoring and secret-management actions.

• Template references such as {{appDb_server}} get IntelliSense, including single-brace completion while typing.
• Template tokens are highlighted inside variable and connection-string values.
• Diagnostics catch unsupported template references, missing variables, and invalid references between environment-specific values.
• Encrypt Secret appears on plaintext secret values.
• View Decrypted, Rotate Secret, and Delete Secret appear on encrypted secret lines.

[env:prelive]
secret apiKey = ENC[NORN_AGE_V1:kid=team-main:abc123xyz]

SQL Files (.nornsql)

SQL files get dedicated editor support so database setup and verification behave like first-class Norn assets instead of opaque scripts.

• .nornsql files have syntax highlighting for declaration lines and SQL bodies.
• Import completion in .norn files suggests .nornsql files alongside other Norn imports.
• Diagnostics catch invalid SQL-file structure, bad imports, duplicate SQL operation names, and invalid run sql calls.
• The sidebar starter catalogue includes a runnable SQL demo and a separate real database connection starter.

connection appDb

query ListUsersByStatus(status)
select Id, Email, Status
from Users
where Status = :status
end query

command UpdateUserStatus(id, status)
update Users
set Status = :status
where Id = :id
end command

Project Setup and MCP Tools

The sidebar home card includes a Project Setup menu so teams can scaffold starter samples and MCP configuration without leaving VS Code.

• Starter catalogue opens a sample list with a Back button. Each selected sample is created in its own new folder to avoid collisions.
• The catalogue includes simple requests, scripts with JSON data, a runnable SQL demo, a real SQL connection starter, and an advanced end-to-end flow with contract validation.
• Create MCP starter config remains a direct setup action that scaffolds norn.config.json with inline guidance fields for alias naming, local vs remote servers, and optional settings.
• The Explorer folder context menu can open the same starter catalogue and still includes the MCP setup action.
• norn.config.json gets JSON schema validation in the editor.
• run mcp list and run mcp call get syntax highlighting, diagnostics, server-alias completions, cached tool-name completions, and parameter hints after a successful list call.
• MCP steps show up in the response panel with dedicated styling instead of sharing SQL visuals.

test sequence TimeTools
    var tools = run mcp list localTools
    var result = run mcp call localTools get_current_time("UTC")

    assert tools.count > 0
    assert result.isError == false
end sequence

Test Explorer

Norn integrates with VS Code's built-in Testing sidebar.

• All test sequence blocks are discovered automatically.
• Plain sequence blocks stay as helpers and do not show up as tests.
• Tests are grouped by file, and then by their primary tag when tags exist.
• @data and @theory sequences show one child test per data case.
• Both run and debug profiles are available.
• Execution output streams into the test run so you can inspect requests, assertions, waits, scripts, and print statements.

@smoke
test sequence HealthCheck
    GET {{baseUrl}}/health
    assert $1.status == 200
end sequence

@data(1, 2, 3)
test sequence TodoTest(id)
    GET {{baseUrl}}/todos/{{id}}
    assert $1.status == 200
end sequence

Swagger Coverage

Norn can calculate coverage for Swagger-defined endpoints and response codes.

• Coverage counts response codes separately, not just endpoints.
• Show Coverage on a swagger line scopes coverage to that .nornapi file and its folder plus subfolders.
• When a .nornapi file is active and Swagger data exists, the status bar shows Coverage with a shortcut to the coverage panel.
• Norn: Refresh API Coverage recalculates the panel.
• Coverage updates after sequence execution.

test sequence OrderTests
    var found = GET GetOrderById(1)
    assert found.status == 200

    var missing = GET GetOrderById(999999)
    assert missing.status == 404
end sequence

TLS Verification

HTTPS certificate verification is enabled by default in the extension.

{
  "norn.security.verifyTlsCertificates": true
}

Set norn.security.verifyTlsCertificates to false only for trusted local development environments with self-signed certificates. The setting affects both request execution and Swagger/OpenAPI fetches.

If you need the same behavior in the CLI, use --insecure for that run instead of changing editor settings globally.