Skip to content

Commit 2dfd346

Browse files
EMaherEMaher
committed
updating README to be more descriptive
1 parent cc65540 commit 2dfd346

2 files changed

Lines changed: 165 additions & 18 deletions

File tree

‎tests/integration/all-resource-types/README.md‎

Lines changed: 162 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# All types APIM Test Assets
22

3-
Infrastructure and scripts for APIOps integration tests against a source and target APIM.
3+
The goal of all-resource-types integration test is to cover all resource types in the [`ResourceType`](src/models/resource-types.ts) enum.
4+
5+
The round trip test first deploys a source API Management instance with all features described in the [what is deployed](#what-is-deployed) section. The test then extracts everything from the source instance and publishes the artifacts to a black target API management instance. See [round trip phases](#round-trip-phases) for more details.
46

57
## Prerequisites
68

@@ -10,39 +12,183 @@ Infrastructure and scripts for APIOps integration tests against a source and tar
1012

1113
## Quick Commands
1214

13-
Run full round trip:
15+
### Run full round trip
1416

1517
```powershell
1618
cd tests/integration/all-resource-types
1719
./run-roundtrip-test.ps1 -PublisherEmail admin@contoso.com
1820
```
1921

20-
Run full round trip with log:
22+
### Run full round trip with log:
2123

22-
Bash:
24+
#### Bash
2325
```bash
2426
set -o pipefail && log_file="tests/integration/all-resource-types/phases/logs/roundtrip-premium-$(date +%Y%m%d-%H%M%S).log" && echo "Logging to $log_file" && pwsh -NoLogo -NoProfile -File ./tests/integration/all-resource-types/run-roundtrip-test.ps1 -SkuName Premium 2>&1 | tee "$log_file"
2527
```
2628

27-
Powershell:
29+
#### Powershell
2830
```powershell
2931
$logFile = "tests/integration/all-resource-types/phases/logs/roundtrip-premium-$((Get-Date).ToString('yyyyMMdd-HHmmss')).log"
3032
Write-Host "Logging to $logFile"
3133
.\tests\integration\all-resource-types\run-roundtrip-test.ps1 -SkuName Premium 2>&1 | Tee-Object -FilePath $logFile
3234
if ($LASTEXITCODE -ne 0) { throw "Round-trip failed with exit code $LASTEXITCODE. See $logFile" }
3335
```
3436

37+
## What is Deployed?
38+
39+
### APIs
40+
An apim instance with the following apis
41+
| API | Type | Spec Format |
42+
|-----|------|-------------|
43+
| `src-rest-openapi` | REST | OpenAPI 3.0 YAML |
44+
| `src-soap-passthrough` | SOAP | WSDL |
45+
| `src-graphql-synthetic` | GraphQL | SDL (inline) |
46+
| `src-graphql-passthrough` | GraphQL | SDL (pass-through) |
47+
| `src-websocket` | WebSocket | None |
48+
| `src-rest-versioned-v1` | REST (versioned) | OpenAPI |
49+
| `src-rest-revisioned` | REST (revisioned) | OpenAPI |
50+
| `src-mcp-from-api` | MCP (from existing API) | None |
51+
| `src-mcp-existing-server` | MCP (working existing-server demo via Learn) | None |
52+
| `src-a2a-weather-agent` | A2A (JSON-RPC + agent card) | None |
53+
54+
### Backend Variations
55+
| Backend | Type |
56+
|---------|------|
57+
| `src-backend-http` | Simple HTTP URL |
58+
| `src-backend-function` | Azure Function stub |
59+
| `src-backend-logicapp` | Logic App stub |
60+
| `src-backend-pool` | Pool (multi-backend) |
61+
| `src-backend-circuit-breaker` | Circuit breaker |
62+
63+
### Other Resources
64+
- **Named Values**: Plain text, secret, Key Vault reference
65+
- **Tags**: 2 tags applied to APIs and products
66+
- **Gateway**: Self-hosted gateway with API association
67+
- **Version Set**: URL-path versioning scheme
68+
- **Loggers**: Application Insights + Event Hub
69+
- **Groups**: Custom group
70+
- **Policy Fragments**: CORS + rate limit
71+
- **Global Schema**: JSON schema
72+
- **Policy Restriction**: Scope-based restriction
73+
- **Documentation**: Getting started doc
74+
- **Diagnostics**: App Insights diagnostic at service and API level
75+
- **Service Policy**: Global CORS policy
76+
- **Products**: Starter + Premium with policies, API/group associations, tags, wikis
77+
- **Subscriptions**: All-APIs + product-scoped
78+
- **Workspace** (Developer v2 only): Workspace with backend, named value, tag, product, API
79+
3580
## Round-Trip Phases
3681

37-
| Phase | Script |
38-
|---|---|
39-
| Deploy source + target | `phases/run-phase1-deploy.ps1` |
40-
| Extract | `phases/run-phase2-extract.ps1` |
41-
| Validate extract | `phases/run-phase3-validate-extract.ps1` |
42-
| Create target overrides | `phases/run-phase4-create-overrides.ps1` |
43-
| Publish | `phases/run-phase5-publish.ps1` |
44-
| Compare | `phases/run-phase6-compare.ps1` |
45-
| Teardown | `phases/run-phase7-teardown.ps1` |
82+
**Phase 1: Deploy source + target** (`phases/run-phase1-deploy.ps1`).
83+
84+
Deploys source and target APIM environments in parallel.
85+
86+
```powershell
87+
# Minimum parameters
88+
./phases/run-phase1-deploy.ps1 -SourceResourceGroup rg-src -TargetResourceGroup rg-tgt -PublisherEmail admin@contoso.com
89+
90+
# All parameters
91+
./phases/run-phase1-deploy.ps1 -SourceResourceGroup rg-src -TargetResourceGroup rg-tgt -PublisherEmail admin@contoso.com -SkuName StandardV2 -Location eastus2 -LogLevel Verbose -SourceApimName src-apim -TargetApimName tgt-apim -SourceSubscriptionId 11111111-1111-1111-1111-111111111111 -TargetSubscriptionId 22222222-2222-2222-2222-222222222222
92+
```
93+
94+
Script returns resolved names, which can be for later phases, especially in the case minimal parameters are passed to the script. Example return value:
95+
96+
```powershell
97+
@{
98+
sourceSubscriptionId = "11111111-1111-1111-1111-111111111111"
99+
sourceResourceGroup = "rg-src"
100+
sourceApimName = "src-apim"
101+
targetSubscriptionId = "22222222-2222-2222-2222-222222222222"
102+
targetResourceGroup = "rg-tgt"
103+
targetApimName = "tgt-apim"
104+
skuName = "StandardV2"
105+
location = "eastus2"
106+
}
107+
```
108+
109+
**Phase 2: Extract** (`phases/run-phase2-extract.ps1`).
110+
111+
Runs `apiops extract` against the source APIM instance and writes artifacts to the extract directory.
112+
113+
```powershell
114+
# Minimum parameters
115+
./phases/run-phase2-extract.ps1 -SourceResourceGroup rg-src -SourceApimName src-apim
116+
117+
# All parameters
118+
./phases/run-phase2-extract.ps1 -SourceSubscriptionId 11111111-1111-1111-1111-111111111111 -SourceResourceGroup rg-src -SourceApimName src-apim -LogLevel Debug -ExtractOutputDir ./phases/extracted-artifacts
119+
```
120+
121+
Script returns the path to the extracted files. Example return value:
122+
123+
```powershell
124+
/workspaces/apiops-cli/tests/integration/all-resource-types/phases/extracted-artifacts
125+
```
126+
127+
**Phase 3: Validate extract** (`phases/run-phase3-validate-extract.ps1`)
128+
129+
Validates extracted artifacts against the expected manifest before publish.
130+
131+
```powershell
132+
# Minimum parameters
133+
./phases/run-phase3-validate-extract.ps1
134+
135+
# All parameters
136+
./phases/run-phase3-validate-extract.ps1 -SkuName PremiumV2 -LogLevel Verbose -ExtractOutputDir ./phases/extracted-artifacts
137+
```
138+
139+
**Phase 4: Create target overrides** (`phases/run-phase4-create-overrides.ps1`).
140+
141+
Generates the target-specific `.overrides.yaml` file used by the publish phase. Script returns the value of the created configuration overrides file.
142+
143+
```powershell
144+
# Minimum parameters
145+
./phases/run-phase4-create-overrides.ps1 -TargetResourceGroup rg-tgt
146+
147+
# All parameters
148+
./phases/run-phase4-create-overrides.ps1 -TargetSubscriptionId 22222222-2222-2222-2222-222222222222 -TargetResourceGroup rg-tgt -LogLevel Info -ExtractOutputDir ./phases/extracted-artifacts
149+
```
150+
151+
Script returns path to created configuration overrides file. Example return value:
152+
153+
```powershell
154+
/workspaces/apiops-cli/tests/integration/all-resource-types/phases/extracted-artifacts/.overrides.yaml
155+
```
156+
157+
**Phase 5: Publish** (`phases/run-phase5-publish.ps1`).
158+
159+
Publishes extracted artifacts to the target APIM instance using the generated overrides file.
160+
161+
```powershell
162+
# Minimum parameters
163+
./phases/run-phase5-publish.ps1 -TargetResourceGroup rg-tgt -TargetApimName tgt-apim -OverrideFile ./phases/extracted-artifacts/.overrides.yaml
164+
165+
# All parameters
166+
./phases/run-phase5-publish.ps1 -TargetSubscriptionId 22222222-2222-2222-2222-222222222222 -TargetResourceGroup rg-tgt -TargetApimName tgt-apim -LogLevel Debug -OverrideFile ./phases/extracted-artifacts/.overrides.yaml -ExtractOutputDir ./phases/extracted-artifacts
167+
```
168+
169+
**Phase 6: Compare source and target API Management instances** (`phases/run-phase6-compare.ps1`).
170+
171+
Compares source and target APIM resources and reports differences or parity.
172+
173+
```powershell
174+
# Minimum parameters
175+
./phases/run-phase6-compare.ps1 -SourceResourceGroup rg-src -SourceApimName src-apim -TargetResourceGroup rg-tgt -TargetApimName tgt-apim
176+
177+
# All parameters
178+
./phases/run-phase6-compare.ps1 -SourceSubscriptionId 11111111-1111-1111-1111-111111111111 -SourceResourceGroup rg-src -SourceApimName src-apim -TargetSubscriptionId 22222222-2222-2222-2222-222222222222 -TargetResourceGroup rg-tgt -TargetApimName tgt-apim -LogLevel Verbose
179+
```
180+
181+
**Phase 7: Teardown** (`phases/run-phase7-teardown.ps1`).
182+
183+
Deletes source and target resource groups and purges soft-deleted APIM services. This phase always run, regardless of the success of previous phases, unles `-SkipTeardown` switch is specified.
184+
185+
```powershell
186+
# Minimum parameters
187+
./phases/run-phase7-teardown.ps1 -SourceResourceGroup rg-src -TargetResourceGroup rg-tgt
188+
189+
# All parameters
190+
./phases/run-phase7-teardown.ps1 -SourceResourceGroup rg-src -TargetResourceGroup rg-tgt -Location eastus2 -SkipTeardown
191+
```
46192

47193
## CI
48194

@@ -55,7 +201,7 @@ Required environment secrets:
55201
- `AZURE_SUBSCRIPTION_ID`
56202
- `APIM_PUBLISHER_EMAIL`
57203

58-
## Layout
204+
## File Layout
59205

60206
- `bicep/` source and target templates
61207
- `modules/` shared PowerShell helpers
@@ -64,5 +210,5 @@ Required environment secrets:
64210

65211
## Notes
66212

67-
- APIM provisioning is slow (typically 30-45 minutes).
213+
- APIM provisioning takes time (typically 30-45 minutes).
68214
- Exit codes used by compare/validation phases: `0` success, `1` diff/validation failure, `2` execution error.

‎tests/integration/all-resource-types/phases/run-phase2-extract.ps1‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,11 +104,12 @@ if (-not $extractedFiles -or $extractedFiles.Count -eq 0) {
104104
exit 2
105105
}
106106

107+
$resolvedExtractOutputDir = [System.IO.Path]::GetFullPath($ExtractOutputDir)
108+
107109
if ($env:GITHUB_OUTPUT) {
108-
$resolvedExtractOutputDir = [System.IO.Path]::GetFullPath($ExtractOutputDir)
109110
"ExtractOutputDir=$resolvedExtractOutputDir" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
110111
"extractOutputDir=$resolvedExtractOutputDir" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
111112
Write-Host "📋 Phase 2 output written to GITHUB_OUTPUT (ExtractOutputDir)"
112113
}
113114

114-
exit 0
115+
return $resolvedExtractOutputDir

0 commit comments

Comments
 (0)