npm package: @sap-ux/ui5-middleware-fe-mockserver
Description: SAP Fiori tools - UI5 middleware for the Fiori elements mock server
Author: @SAP/ux-odata-team
Latest version: 2.4.11

# @sap-ux/ui5-middleware-fe-mockserver

## Features

The **SAP Fiori - UI5 middleware for the Fiori elements mock server** is a middleware extension for the [UI5 Tooling](https://github.com/SAP/ui5-tooling). As an alternative to proxying OData requests to a live backend, it supports loading mock data for OData v2/v4 requests for supported Fiori elements templates. As the mock server runs locally without requiring a network connection to a backend system, it is useful for development and test scenarios.

## Installation
npm
`npm install --save-dev @sap-ux/ui5-middleware-fe-mockserver`

yarn
`yarn add @sap-ux/ui5-middleware-fe-mockserver --dev`

pnpm
`pnpm add @sap-ux/ui5-middleware-fe-mockserver --dev`

## Usage

In order to use the mock server, the npm module `@sap-ux/ui5-middleware-fe-mockserver` needs to be added as devDependency to `package.json`, and a valid `ui5.yaml` configuration needs to be provided.
**Entries in package.json**

```
[..]

"devDependencies": {
    "@sap-ux/ui5-middleware-fe-mockserver": "^2"
}

[..]
```

**Example for a yaml configuration file**

```

specVersion: '3.0'
metadata:
  name: <NAME>
type: application
server:
  customMiddleware:
    - name: sap-fe-mockserver
      mountPath: /
      afterMiddleware: compression
      configuration:
        annotations:
          - localPath: './webapp/localService/myServiceAnnotation.xml'
            urlPath: '/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/Annotations*'
        services:
          - urlPath: '/sap/opu/odata/sap/<SERVICE_NAME>'
            metadataPath: './webapp/localService/metadata.xml'
            mockdataPath: './webapp/localService/data'
          - urlPath: '/sap/opu/odata/sap/<OTHER_SERVICE_NAME>'
            metadataPath: './webapp/localService/other_metadata.xml'
            mockdataPath: './webapp/localService/data'

```

### Special case within karma

If you are running the mockserver embedded in karma you need to change the configuration to use

`beforeMiddleware: csp` instead of `afterMiddleware: compression`


## Service Configuration

Each service must provide at least two things

- urlPath : where will your service be accessible from
- metadataPath : local path to your metadata file

On top of that you can specify one of the following option

- mockdataPath : the path to the folder containing the mockdata files
- generateMockData : whether or not you want to use automatically generated mockdata
- resolveExternalServiceReferences : whether or not to try to resolve all services referenced in `Common.ValueListReferences` annotations or CodeList annotations and serve their metadata from `localServices` directory.
- forceNullableValuesToNull : determine if nullable properties should be generated as null or with a default value (defaults to false)

Additional option are available either per service of for all services if defined globally

- debug : toggle the debug mode
- logRequests: toggle the request logging (can also be enabled via query parameter `?logs=true`)
- logResponses: toggle the response logging (can also be enabled via query parameter `?logs=true`)
- logger: specify the logger to use, by default it will use the @ui5/logger
- watch : toggle the watch mode, the mockserver will restart the service where data or metadata have changed
- noETag : disable ETag support on metadata
- strictKeyMode : disable the default "loose" mode for the key matching.
By default the mockserver will try many ways to match an entityset with its navigation property, which can result in some rather loose join of data. In case you have a very well defined mockdata and you feel the mockserver is returning too much data, you can enable this feature.

- contextBasedIsolation : enable the support of "tenants" at the URL level.
Tenants allow you to work on the same app with dedicated, isolated tenant data.
Tenants are always available by using ?sap-client in your application url, however by enabling this setting you can also enable a specific path based tenant by prepending /tenant-xxx at the very start of your service call.
On top of the standard json file loading, when using tenants we will automatically try to fetch a specific json data from a file including the tenant ID in the name. 
For instance if you have an entity called `Product` you can have a `Product.json` file containing the standard data and a `Product-testErrorXXX.json` file for a specific tenant called testErrorXXX.
If you don't have a tenant specific file, the mockserver will fallback to the standard file.

You can also define static annotation file using the `annotations` entry, each annotation must provide

- urlPath : where will your annotation be accessible from
- localPath : local path to your annotation file


## Typescript support

If your application embed ts-node, the mockserver will use that automatically to load the mockdata files.
You can also specify a custom tsconfig file to use by adding the `tsConfigPath` entry globally.

```
        configuration:
          tsConfigPath: './tsconfig-mockserver.json'
          services:
            - urlPath: '/sap/opu/odata/sap/<SERVICE_NAME>'
              metadataPath: './webapp/localService/metadata.xml'
              mockdataPath: './webapp/localService/data'
```
This is useful if you want to have a different configuration for the mockserver than the one used for your application.

**Documentation**

You can find more details on how to influence the mockserver behavior for mockdata by checking the documentation under [Defining Mockdata](https://github.com/SAP/open-ux-odata/blob/main/docs/DefiningMockdata.md)

We also have samples available in the [samples folder](https://github.com/SAP/open-ux-odata/tree/main/samples)


**Sample application**

See the usage in demo apps [SAP Fiori sample apps](https://github.com/SAP-samples/fiori-tools-samples)


## Support

Join the [SAP Fiori tools Community](https://community.sap.com/t5/c-khhcw49343/SAP+Fiori+tools/pd-p/73555000100800002345). Ask Questions, Read the Latest Blogs, Explore Content.
Please assign tag: _SAP Fiori tools_

To log an issue with SAP Fiori tools, please see [Contact SAP Support](https://help.sap.com/viewer/1bb01966b27a429ebf62fa2e45354fea/Latest/en-US).

## Keywords
Mockserver, Middleware