sasjs/adapter
1
0
Fork 0
mirror of https://github.com/sasjs/adapter.git synced 2025-12-10 17:04:36 +00:00
Code Issues Projects Releases Wiki Activity

docs: update README.md

Browse Source
This commit is contained in:
mulahasanovic
2025-11-18 12:10:37 +01:00
parent 59198ed6ab
commit ad4c9b2164
2 changed files with 38 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
sasjs-tests/README.md
View File

@@ -26,56 +26,6 @@ There are three prerequisites to be able to run the tests:
There is a `config.json` file in the `/public` folder which specifies the configuration for the SASjs adapter. You can set the values within the `sasjsConfig` property in this file to match your SAS server configuration.
#### Installation
```bash
npm install
```
#### Configuration
Edit `public/config.json`:
```json
{
"userName": "your-username",
"password": "your-password",
"sasJsConfig": {
"serverUrl": "https://your-sas-server.com",
"appLoc": "/Public/app/adapter-tests/services",
"serverType": "SASJS",
"debug": false,
"contextName": "sasjs adapter compute context",
"useComputeApi": true
}
}
```
**Server Types:**
- `SASJS` - SASjs Server
- `SASVIYA` - SAS Viya
- `SAS9` - SAS 9.4
## Getting Started
### Development
```bash
# Build for production
npm run build
# Watch mode (rebuild on changes)
npm run dev
```
The built files are in `build/`:
- `index.html` - App entry point
- `index.js` - Bundled JavaScript
- `index.css` - Global styles
- `config.json` - Configuration
## Test Suites
Tests are defined in `src/testSuites/`:
@@ -133,10 +83,45 @@ The `shadow()` command is defined in `cypress/support/commands.js`.
npm run build
```
This creates a `build/` folder ready for deployment.
This creates a `dist/` folder ready for deployment.
### Deploy to SAS Server
There is a `deploy` NPM script provided in the `sasjs-tests` project's `package.json`.
It updates `sasjs-tests` to use the latest version of the adapter, and deploys to a specified server via SSH using the `rsync` command.
To be able to run the `deploy` script, two environment variables need to be set:
- `SSH_ACCOUNT` - your SSH account, this is of the form username@domain.com
- `DEPLOY_PATH` - the path on the server where `sasjs-tests` will be deployed to, typically `/var/www/html/<some-subfolder>`.
So you can run the script like so:
```bash
SSH_ACCOUNT=me@my-sas-server.com DEPLOY_PATH=/var/www/html/my-folder/sasjs-tests npm run deploy
```
If you are on `WINDOWS`, you will first need to install one dependency:
```bash
npm i -g copyfiles
```
and then run to build:
```bash
npm run update:adapter && npm run build
```
when it finishes run to deploy:
```bash
scp -rp ./build/* me@my-sas-server.com:/var/www/html/my-folder/sasjs-tests
```
If you'd like to deploy just `sasjs-tests` without changing the adapter version, you can use the `deploy:tests` script, while also setting the same environment variables as above.
#### Creating the required SAS services
The below services need to be created on your SAS server, at the location specified as the `appLoc` in the SASjs configuration.
@@ -239,39 +224,7 @@ Services expected:
Deploy these services using [SASjs CLI](https://cli.sasjs.io) or manually.
## Troubleshooting
### Build Errors
- Ensure Node.js >= 18
- Clear `node_modules` and reinstall: `rm -rf node_modules package-lock.json && npm install`
### Cypress Shadow DOM Issues
If Cypress can't access Shadow DOM elements:
1. Verify custom `shadow()` command in `cypress/support/commands.js`
2. Check element selectors match actual DOM structure
### Test Failures
- Check `config.json` credentials and server URL
- Verify SAS services are deployed
- Check browser console for errors
- Enable `debug: true` in sasJsConfig for verbose logging
## Development
- **Pure Vanilla TS** - No React, no frameworks
- **Custom Elements** - Web Components with Shadow DOM
- **Zero Dependencies** - Only @sasjs/adapter + build tools
- **Minimal Bundle** - 40KB (8KB gzipped)
### Build Stack
- **tsdown** - TypeScript bundler (replaces CRA/react-scripts)
### UI Components (Custom Elements)
## UI Components (Custom Elements)
- `<login-form>` - SAS authentication
- `<tests-view>` - Test orchestrator with run controls
@@ -292,13 +245,9 @@ All components use Shadow DOM for style encapsulation and expose custom events f
Components are in `src/components/`:
- Edit `.ts` file
- Styles are in Shadow DOM `<style>` tags
- Styles are in corresponding `.css` file
- Rebuild with `npm run build`
## License
MIT
## Links
- [@sasjs/adapter](https://adapter.sasjs.io)

148
sasjs-tests/test.md
View File

@@ -1,148 +0,0 @@
`sasjs-tests` is a test suite for the SASjs adapter.
It is a React app bootstrapped using [Create React App](https://github.com/facebook/create-react-app) and [@sasjs/test-framework](https://github.com/sasjs/test-framework).
When developing on `@sasjs/adapter`, it's good practice to run the test suite against your changed version of the adapter to ensure that existing functionality has not been impacted.
You can use the provided `update:adapter` NPM script for this.
```bash
npm run update:adapter
```
This scripts builds a new version of the adapter and installs it in the `sasjs-tests` project.
## Running tests
There are three prerequisites to be able to run the tests:
1. Correct server configuration for the SASjs adapter.
2. `sasjs-tests` deployed to your SAS server.
3. The required SAS services created on the same server.
### 1. Configuring the SASjs adapter
There is a `config.json` file in the `/public` folder which specifies the configuration for the SASjs adapter. You can set the values within the `sasjsConfig` property in this file to match your SAS server configuration.
### 2. Deploying to your SAS server
There is a `deploy` NPM script provided in the `sasjs-tests` project's `package.json`.
It updates `sasjs-tests` to use the latest version of the adapter, and deploys to a specified server via SSH using the `rsync` command.
To be able to run the `deploy` script, two environment variables need to be set:
- `SSH_ACCOUNT` - your SSH account, this is of the form username@domain.com
- `DEPLOY_PATH` - the path on the server where `sasjs-tests` will be deployed to, typically `/var/www/html/<some-subfolder>`.
So you can run the script like so:
```bash
SSH_ACCOUNT=me@my-sas-server.com DEPLOY_PATH=/var/www/html/my-folder/sasjs-tests npm run deploy
```
If you are on `WINDOWS`, you will first need to install one dependency:
```bash
npm i -g copyfiles
```
and then run to build:
```bash
npm run update:adapter && npm run build
```
when it finishes run to deploy:
```bash
scp -rp ./build/* me@my-sas-server.com:/var/www/html/my-folder/sasjs-tests
```
If you'd like to deploy just `sasjs-tests` without changing the adapter version, you can use the `deploy:tests` script, while also setting the same environment variables as above.
## 3. Creating the required SAS services
The below services need to be created on your SAS server, at the location specified as the `appLoc` in the SASjs configuration.
The code below will work on ALL SAS platforms (Viya, SAS 9 EBI, SASjs Server).
```sas
filename mc url "https://raw.githubusercontent.com/sasjs/core/main/all.sas";
%inc mc;
%let apploc=/Public/app/adapter-tests;
filename ft15f001 temp lrecl=1000;
parmcards4;
%webout(FETCH)
%webout(OPEN)
%macro x();
%if %symexist(sasjs_tables) %then %do i=1 %to %sysfunc(countw(&sasjs_tables));
%let table=%scan(&sasjs_tables,&i);
%webout(OBJ,&table,missing=STRING,showmeta=YES)
%end;
%else %do i=1 %to &_webin_file_count;
%webout(OBJ,&&_webin_name&i,missing=STRING,showmeta=YES)
%end;
%mend; %x()
%webout(CLOSE)
;;;;
%mx_createwebservice(path=&apploc/services/common,name=sendObj)
parmcards4;
%webout(FETCH)
%webout(OPEN)
%macro x();
%if %symexist(sasjs_tables) %then %do i=1 %to %sysfunc(countw(&sasjs_tables));
%let table=%scan(&sasjs_tables,&i);
%webout(ARR,&table,missing=STRING,showmeta=YES)
%end;
%else %do i=1 %to &_webin_file_count;
%webout(ARR,&&_webin_name&i,missing=STRING,showmeta=YES)
%end;
%mend; %x()
%webout(CLOSE)
;;;;
%mx_createwebservice(path=&apploc/services/common,name=sendArr)
parmcards4;
data work.macvars;
set sashelp.vmacro;
run;
%webout(OPEN)
%webout(OBJ,macvars)
%webout(CLOSE)
;;;;
%mx_createwebservice(path=&apploc/services/common,name=sendMacVars)
parmcards4;
If you can keep your head when all about you
Are losing theirs and blaming it on you,
If you can trust yourself when all men doubt you,
But make allowance for their doubting too;
;;;;
%mx_createwebservice(path=&apploc/services/common,name=makeErr)
parmcards4;
%webout(OPEN)
data _null_;
file _webout;
put ' the discovery channel ';
run;
%webout(CLOSE)
;;;;
%mx_createwebservice(path=&apploc/services/common,name=invalidJSON)
```
You should now be able to access the tests in your browser at the deployed path on your server.
## Creating new tests
The `src/testSuites` folder contains all the test suites currently available.
Each suite contains a set of specs, each of which looks like this:
```javascript
{
title: "Your test title",
description: "A slightly more detailed description",
test: async () => {
// typically makes a request using the adapter and returns a promise
},
assertion: (response: any) =>
// receives the response when the test promise resolves, runs an assertion and returns a boolean
}
```
A test suite is an array of such objects, along with a `name` property.
You can add your test to one of the existing suites if suitable, or create a new file that specifies a new test suite.