bim+ websdk

bim+ websdk is a javascript wrapper around the bim+ api

Quick Links

https://nemetschekprime.atlassian.net/wiki/spaces/bimpluspublic/pages/1090127532/Bimplus+Web+SDK+Reference

How to build

Install nodejs

http://www.nodejs.org/

Install local npm modules

Open up a normal command line (admin is not needed) and go to the websdk folder

npm install

(whenever package.json has changed, you might to do this again)

Build websdk

Library building process is using UMD (Universal Module Definition) output format so it's compatible with both cjs and amd module formats. The same library can be use in the client or on the server. Build process is using babel so it's possible to use new ES2015 code in source codes.

Library can be build in several ways as a dev or prod version. To run a dev build with source maps run:

npm run build

To build a stage version that defaults to the stage API host run:

npm run build-stage

To build a prod version - uglified, minified run:

npm run build-prod

Pulish new release to npm (Hint: Before doing this npm login needs to be done and the package version adjusted) :

npm run npm-publish

Check content of npm package (result is bimplus-renderer@(version).tar.gz)

npm run npm-pack

Develop/Debug websdk

goto your websdk folder

npm link

goto your application folder which uses the websdk

npm link bimplus-websdk

Do you changes in the websdk and build

npm run build

or

npm run build-prod

Your app will automatically get the changes done in the renderer

After developing it might be wise to unlink: goto your websdk folder

npm unlink

goto your application folder which uses the websdk

npm unlink bimplus-websdk
npm install

Testing

The integration suite runs in Chromium through Vitest Browser Mode and Playwright. It calls the live Bimplus API.

Install the required browser binaries once after npm install:

npx playwright install chromium firefox

Set BIM_PASS before running against dev. Use BIM_PASS_STAGE or BIM_PASS_PROD for the matching environments.

npm test
npm run test-watch
npm run test-chrome
npm run test-chrome-headless
npm run test-firefox
npm run test-firefox-headless
npm run test-stage
npm run test-stage-headless
npm run test-prod
npm run test-prod-headless

You can also select the API environment through npm test, with coverage enabled:

npm test -- --environment=stage
npm test -- --environment=prod

The test runner translates these flags into BIMPLUS_ENV; they are API targets, not custom Vitest runtimes. Both --environment=stage and --environment stage are supported. Direct npx vitest calls must use BIMPLUS_ENV instead. Set BIMPLUS_API to override the API host. BIMPLUS_ENV selects dev, stage, or prod for npm test and direct Vitest runs; an explicit API environment flag takes precedence. The *-headless scripts run without a visible browser window; the corresponding scripts without that suffix launch a headed browser. Firefox scripts omit coverage because Vitest's V8 coverage provider supports Chromium browser runs only.

Jenkins

For a Windows batch build step, explicitly enable headless mode to run tests without a visible browser window:

@cd websdk
set BIMPLUS_HEADLESS=true
call npm run test
if %ERRORLEVEL% NEQ 0 exit /B %ERRORLEVEL%

Configure the matching password environment variable through Jenkins credentials and install the required Playwright browser binaries on the agent before running tests. Use call so control returns from npm.cmd to the batch script for the exit-code check.

Selecting Test Files

By default, npm test runs all files matching test/api_tests/**/*.js. Pass file filters after -- to run selected files without editing the configuration:

# One file
npm run test -- test/api_tests/ProjectTests.js

# Multiple files
npm run test -- ProjectTests.js ModelsTests.js

# One file against stage
npm run test -- --environment=stage ProjectTests.js

# Tests whose names match a pattern within one file
npm run test -- ProjectTests.js -t "test name"

# Watch one file
npm run test-watch -- ProjectTests.js

File filters match paths by substring; use the full relative path when filenames are ambiguous. The -t option matches test names using a regular expression. Run npm test without filters to return to all configured test files.

Alternatively, switch between all tests and selected files in the test.include array in vitest.config.mjs, as with Karma's file list:

include: [
    "test/api_tests/**/*.js", // All tests; comment out to use selected files below
    // "test/api_tests/ProjectTests.js",
    // "test/api_tests/ModelsTests.js",
],

To select files through configuration, comment out the all-tests pattern and uncomment the desired file entries. Restore the all-tests pattern to run the entire suite again. CLI file filters only narrow the files allowed by test.include; they do not override it. Keep the all-tests pattern enabled when selecting files from the command line.

Documentation

Bimplus WebSDK uses JSDoc for HTML documentation and a repository-owned renderer for API Markdown.

To create documentation in html format go to your websdk folder and run :

npm run build-doc

Documentation output will be in websdk/documentation folder

To create documentation in markdown format go to your websdk folder and run :

npm run build-docMd

Documentation output will be in websdk/documentation/Bimplus_WebSDK_doc.md file.

The JSDoc configuration is in jsdoc.json; the Markdown renderer validates generated API anchors and links.

To create a markdown suitable for Confluence run script:

npm run build-docConf

This script will convert generated markdown into Confluence format. See console output for converted file name.

Content of the confluence file can be inserted into Confluence page :

• start confluence page editation mode
• choose Insert more content / {} Markup option from toolbar
• in popup window choose to Insert Markdown format
• copy content of the converted confluence markdown file into the field in Confluence
• save it (Please note that page links doesn't work in page preview mode)

Typescript definitions

• typescript definition file is located in subfolder 'types'