TestAPI

This is a React + Node proxy app for browsing and managing Test Suites, Test Cases, and Test Runs through the Oracle Intelligent Advisor test APIs.

The UI supports:
- Viewing test suites, test cases, and test runs
- Creating, editing, and deleting test cases
- Importing OPM Excel test cases into batchAssess suites
- Generating standalone OPM Excel test case workbooks from OPM project ZIP exports
- Creating and monitoring test runs
- Viewing test case and test run payloads in a tree view
- Comparing expected and actual outputs for completed test runs
- Filtering test run results by comparison outcome

Additional documentation:
- `README-OPM-Excel-Test-Case-Generator.md` covers the standalone OPM Excel generator workflow in detail

Installation

Prerequisites:
- Node.js 18+ and npm
- Git
- Access to the GitHub repository

Steps:
1. Clone the repository:
   `git clone https://github.com/Intelligent-Advisor/TestAPI C:\TestAPI`
2. Install root dependencies:
   `cd C:\TestAPI`
   `npm install`
3. Install server dependencies:
   `cd C:\TestAPI\server`
   `npm install`
4. Install web dependencies:
   `cd C:\TestAPI\web`
   `npm install`
5. Create your local frontend env file:
   `cd C:\TestAPI\web`
   `Copy-Item .env.local.example .env.local`
   Fill in the local values in `.env.local`.

Running In Development

Open two terminals.

Backend:
`cd C:\TestAPI\server`
`node index.js`

Frontend:
`cd C:\TestAPI\web`
`npm run dev`

Open the frontend URL shown by webpack dev server. The backend runs on `http://localhost:4000`.

Frontend local environment

The frontend now reads local-only config values from `web\.env.local`.

Setup:
`cd C:\TestAPI\web`
`Copy-Item .env.local.example .env.local`

Populate these values in `web\.env.local` as needed:
- `DEBUG_URL`
- `AUTH_API_VERSION`
- `TEST_AUTOMATION_API_VERSION`
- `DEFAULT_HUB_URL`
- `DEFAULT_USER`
- `DEFAULT_PW`
- `HIDE_EMPTY_TARGET_SUITES`

Notes:
- `web\.env.local` is ignored by Git and should hold local credentials or hub defaults.
- `web\.env.local.example` is safe to commit and documents the required keys.

TLS Certificate Workaround

If login fails on a specific Windows machine, but the same hub URL and credentials work on another machine, the local Node process may be failing certificate validation for the upstream hub.

For the small number of affected users, the supported workaround is to start the backend with `NODE_TLS_REJECT_UNAUTHORIZED=0`.

Development mode

PowerShell:
`cd C:\TestAPI\server`
`$env:NODE_TLS_REJECT_UNAUTHORIZED="0"; node index.js`

Command Prompt:
`cd C:\TestAPI\server`
`set NODE_TLS_REJECT_UNAUTHORIZED=0 && node index.js`

Production mode

PowerShell:
`cd C:\TestAPI\server`
`$env:NODE_TLS_REJECT_UNAUTHORIZED="0"; npm run prod`

Command Prompt:
`cd C:\TestAPI\server`
`set NODE_TLS_REJECT_UNAUTHORIZED=0 && npm run prod`

Notes:
- This disables TLS certificate verification for that Node process.
- Use it only when needed for affected users.
- If this workaround is required, the underlying issue is likely local certificate trust, proxy interception, or endpoint security software on that machine.

TLS Certificate Fix

If the workaround above is required, the preferred long-term fix is to make the affected Windows machine trust the certificate chain that Node sees when it connects to the hub.

Typical causes:
- The machine is missing the required root or intermediate CA certificate.
- A corporate proxy or security product is intercepting HTTPS traffic and re-signing it with a company certificate.
- The browser trusts the certificate chain, but Node does not.

Recommended fix path

1. Identify the CA certificate that issued the certificate presented to the affected machine.
2. Export that certificate as a Base-64 encoded `.cer` or `.pem` file.
3. Install the certificate into the Windows trusted certificate store if your organisation expects the machine to trust it system-wide.
4. If Node still does not trust it, point Node at the CA bundle explicitly with `NODE_EXTRA_CA_CERTS`.

Run with an explicit CA bundle

PowerShell:
`cd C:\TestAPI\server`
`$env:NODE_EXTRA_CA_CERTS="C:\path\to\company-root-ca.pem"; node index.js`

Command Prompt:
`cd C:\TestAPI\server`
`set NODE_EXTRA_CA_CERTS=C:\path\to\company-root-ca.pem && node index.js`

Production mode with explicit CA bundle

PowerShell:
`cd C:\TestAPI\server`
`$env:NODE_EXTRA_CA_CERTS="C:\path\to\company-root-ca.pem"; npm run prod`

Command Prompt:
`cd C:\TestAPI\server`
`set NODE_EXTRA_CA_CERTS=C:\path\to\company-root-ca.pem && npm run prod`

Notes:
- The certificate file should contain the issuing CA certificate, not the application URL.
- PEM format is the safest option for `NODE_EXTRA_CA_CERTS`.
- If your organisation uses a proxy that re-signs HTTPS traffic, use the proxy root CA certificate.
- `NODE_EXTRA_CA_CERTS` is preferred over `NODE_TLS_REJECT_UNAUTHORIZED=0` because it preserves certificate validation.

Run Results Encoding Note

Oracle batch assess run results may occasionally return replacement characters in `actualOutput` text even when the stored test case `expectedOutput` is correct in the Hub.

Current behaviour in this app:
- The proxy repairs common mojibake patterns on inbound and outbound text values.
- The app does not overwrite `actualOutput` run-result values using `expectedOutput`.
- If Oracle returns corrupted accented characters in the run result payload, the UI shows that payload as returned so the failure remains visible.

Important limitations:
- This app does not attempt to mask Oracle comparison failures caused by corrupted `actualOutput` text.
- If the Hub records the run as failed, the UI will continue to show that failed result even when the corruption is limited to character encoding.
- Oracle should still be treated as the source system to fix for the underlying encoding issue.

Running In Production

1. Build the frontend:
   `cd C:\TestAPI\web`
   `npm run build`
2. Start the backend:
   `cd C:\TestAPI\server`
   `npm run prod`
3. Open `http://localhost:4000`

Test Case Workflows

Test case creation now happens in the dedicated form page opened from the test case list.

Standard workflow:
1. Open a suite from the Test Cases screen.
2. Select `Create Test Case`.
3. Enter the top-level fields:
   `Name`, `Description`, `Enabled`, and `Tags`
4. Choose one of the editor modes:
   `Guided`
   `JSON Editor`
   `Excel Import`
5. Save the test case.

Guided workflow for `batchAssess` suites:
1. Open `Create Test Case`.
2. Leave the form in `Guided` mode.
3. Paste a Determinations Server example URL.
4. Select `Load Example`.
5. Review and edit:
   input case fields
   selected outcomes
   expected output rows
6. Save the test case.

Notes:
- Guided mode is intended for `batchAssess` suites.
- The form derives starter input structure from the example payload.
- If the payload includes `input.case` and `input.outcomes`, those values are also loaded when editing an existing compatible test case.

Excel Import workflow for `batchAssess` suites:
1. Open `Create Test Case`.
2. Switch to `Excel Import`.
3. Paste a Determinations Server example URL.
4. Select `Load Example`.
5. Choose the OPM Excel workbook.
6. Choose the matching `projectDataModel.xml` from the same policy model.
7. Select `Preview Import`.
8. Review:
   detected column roles
   resolved public names
   relationship mappings
   confidence and warnings
   generated test case payloads
   row-level warnings
9. Choose a batch size.
10. Select `Create Imported Test Cases`.

Notes:
- The importer now uses three sources together:
  the OPM workbook
  `projectDataModel.xml`
  the loaded example payload
- `projectDataModel.xml` is used to resolve base text such as `the destination` or `the results` to the REST public names used by the Hub APIs.
- If a required input or expected-output column cannot be resolved to a public name, creation is blocked until the mapping is corrected.
- OPM styles are treated as the primary signal for column purpose:
  `OPM - Input`
  `OPM - Expected`
  `OPM - Actual`
- The preview table is intended to be reviewed before creation. Users can still override the detected role for each column.
- The workbook preview now uses tabs so each Excel worksheet can be reviewed with its own column roles, mappings, and sample rows.
- The `Test Cases` sheet remains the parent sheet.
- Additional sheets are treated as child-entity sheets and are linked back to the parent by the `Test Case` or `Test Cases` column on the child sheet.
- Child sheet column A is treated as a foreign key to the parent test case and is not written into the generated JSON payload.
- Child-sheet roles are driven by OPM styling by default:
  `OPM - Input` -> `Input`
  `OPM - Expected` -> `Expected Output`
  `OPM - Actual` -> `Actual`
- Child-sheet columns can be switched to `Input`, `Actual`, `Expected Output`, `Both`, or `Ignored` during preview review.
- Each imported column also has an `(unknown)` handling option: `Remove`, `Set to {}`, or `Null`. The default is `Set to {}`.
- Child-sheet JSON is written under the containment relationship public name for that entity.
- When a header matches multiple model targets, the preview exposes the resolved-name choices so the user can choose the correct public name. This is used for cases such as a base text matching both an entity attribute and a containment relationship.
- Truncated child-sheet names are matched back to the entity names from `projectDataModel.xml` where possible.
- If a column has no usable REST public name, it is forced to `Ignored`.
- Warnings tied only to ignored columns are removed from the preview warning list.
- If an expected-output column on the `Test Cases` sheet resolves to a containment relationship, the importer converts it into a child array using the child entity identifying attribute public name from `projectDataModel.xml`.
- Delimited expected child lists currently recognize both `,` and `;`.
- When an expected relationship array is generated, the relationship public name is automatically added to `input.outcomes` for that imported test case so the run requests the corresponding actual results.
- The `Results` column is ignored.
- Test case names are generated from the suite name and Excel test case number.
- Imported cases are created sequentially in batches to reduce risk for large imports.
- Current boundary:
  grandchild relationship generation inside child sheets is still not implemented.

JSON Editor workflow:
1. Open `Create Test Case` or edit an existing test case.
2. Switch to `JSON Editor`.
3. Edit the full test case payload in one JSON document.
4. Save the test case.

Notes:
- `JSON Editor` replaces the old `Raw JSON` label.
- The JSON editor contains the full top-level test case payload, including `name`, `description`, `enabled`, `tags`, `input`, and `expectedOutput`.
- For edits, changing the test case name is not allowed.

Test case details workflow:
1. Open a test case from the Test Cases screen.
2. Review the input and expected output trees.
3. Select `Edit JSON` to open the raw JSON editor.
4. Update the payload.
5. Select `Save Changes`.

Test Run Workflows

Run list workflow:
1. Open a suite from the Test Runs screen.
2. Select `Create Run`.
3. Refresh manually or wait while active runs poll automatically.
4. Open any run with `View`.

Run details workflow:
1. Open a run from the Test Run list.
2. The page immediately loads the run status.
3. If the run is complete, results load immediately.
4. If the run is still `pending` or `running`, the page polls until completion and then loads results.
5. Review:
   summary counts
   pass rate chart
   filtered case list by result or comparison outcome
   input payload
   expected output
   actual output
   per-field differences for failures

Production Checklist

1. Stop any running dev servers.
2. Build the frontend:
   `cd C:\TestAPI\web`
   `npm run build`
3. Start the backend in production:
   `cd C:\TestAPI\server`
   `npm run prod`
4. Confirm the server is serving the built frontend from `web\dist`.
5. Open `http://localhost:4000`.
6. Check:
   suite list loads
   test case creation opens the dedicated form
   guided creation works for `batchAssess`
   Excel Import preview works for OPM workbooks
   Excel Import batch creation works
   JSON Editor mode saves valid payloads
   test case details JSON edit saves changes
   test run result filters work
   test run details load for both completed and in-progress runs