Skip to content
Visory LLC

Testing Guide

This generalizes apps/mx_fuels_reporting_app/TESTING.md (originally written to verify one specific credential fix) into a repeatable local verification checklist.

Prerequisites

Section titled “Prerequisites”
Terminal window
az login
az account show   # confirm the correct subscription
cd apps/mx_fuels_reporting_app
direnv allow      # (re)load .envrc with the azure/dashboard hooks

Verify the non-secret vault URLs loaded:

Terminal window
echo "WEB_KEY_VAULT_URL: ${WEB_KEY_VAULT_URL}"
echo "CNE_CREDENTIALS_KEY_VAULT_URL: ${CNE_CREDENTIALS_KEY_VAULT_URL}"

If either value is empty, run direnv allow from apps/mx_fuels_reporting_app.

Clean build and start

Section titled “Clean build and start”
Terminal window
make down
make js   # build-web + docker compose up

Watch for a clean Next.js startup (✓ Ready in ...ms) and absence of:

⨯ Error [AggregateAuthenticationError]: ChainedTokenCredential authentication failed.

For local development, the first Key Vault access should show:

[KeyVault:Dashboard] AZURE_CLIENT_ID not set, using AzureCliCredential (developer's `az login` session).

Key Vault access check

Section titled “Key Vault access check”
Terminal window
docker compose -f compose.js.yaml logs -f web | grep -E "\[KeyVault\]|ChainedTokenCredential"

In production, the log should identify ManagedIdentityCredential. A local failure usually means the mounted Azure CLI session is missing or az login is expired.

API route smoke test

Section titled “API route smoke test”
Terminal window
echo '<?xml version="1.0"?><test/>' > /tmp/test.xml
curl -X POST http://localhost:3000/api/azure/assembleReporteVolumenes \
  -F "purchasesFile=@/tmp/test.xml" -F "fileType=xml"

Expect a download URL or an auth redirect — not a 500 with ChainedTokenCredential authentication failed.

CNE submission verification

Section titled “CNE submission verification”

The CNE submission task is implemented but is not verified. Do not send a live CNE request from this checklist. Keep JSON jobs in generation-only mode until the separate submission-test pull request passes.

That pull request must add mocked coverage for these cases:

  • Generation-only and XML jobs skip the CNE request.
  • The JSON request includes the API key header and multipart credential fields.
  • The task stores receipt data without logging secrets or acknowledgment content.
  • Credential, HTTP, rejection, and invalid-response errors set the correct job state and error code.
  • A pre-existing SUBMITTED job does not send a second CNE request.

Run one controlled CNE QA smoke test only after the mocked tests pass. Record the result in the pull request. Do not include credential values or CNE acknowledgment content in test output.

Troubleshooting

Section titled “Troubleshooting”

Vault URLs not reaching the container:

Terminal window
env | grep -E "(WEB_KEY_VAULT_URL|CNE_CREDENTIALS_KEY_VAULT_URL)" | sort
direnv allow                                # reload if missing
make down && make js                        # rebuild

dotenv injecting env (0) in logs — this is normal; .env.local is excluded by .dockerignore, credentials come from Docker Compose env vars instead.

Validation checklist

Section titled “Validation checklist”
  • Build completes without errors
  • Container starts, shows “Ready in XXms”
  • No ChainedTokenCredential authentication failed errors
  • First local Key Vault access logs AzureCliCredential
  • http://localhost:3000 loads (redirects to login if needed)
  • API routes respond without 500s

For PostgreSQL-specific connection testing, see Postgres Setup.