استخدام مجموعة أدوات اختبار قالب ARM

مقالة
03/20/2024

تتحققمجموعة أدوات اختبار قالب إدارة الموارد Azure (قالب ARM) مما إذا كان القالب يستخدم الممارسات الموصى بها. عندما لا يتوافق القالب مع الممارسات الموصى بها، فإنه يقوم بإرجاع قائمة من التحذيرات مع التغييرات المقترحة. باستخدام مجموعة أدوات الاختبار، يمكنك تعلم كيفية تجنب المشاكل الشائعة في تطوير القالب. توضح هذه المقالة كيفية تشغيل مجموعة أدوات الاختبار وكيفية إضافة أو إزالة الاختبارات. لمزيدٍ من المعلومات حول كيفية إجراء الاختبارات أو كيفية إجراء اختبار معين، راجع Test parameters.

مجموعة الأدوات هي مجموعة من البرامج النصية PowerShell التي يمكن تشغيلها من أمر في PowerShell أو CLI. تُعد هذه الاختبارات توصيات، وليست متطلبات. يمكنك تحديد الاختبارات ذات الصلة بأهدافك وتخصيص الاختبارات التي يتم تشغيلها.

تحتوي مجموعة الأدوات على أربع مجموعات من الاختبارات:

ملاحظة

تتوفر مجموعة أدوات الاختبار فقط لقوالب ARM. للتحقق من صحة ملفات Bicep، استخدم Bicep linter.

موارد التدريب

لمعرفة المزيد حول مجموعة أدوات اختبار قالب ARM، وللإرشادات العملية، راجع التحقق من صحة موارد Azure باستخدام مجموعة أدوات اختبار قالب ARM.

التثبيت على Windows

إذا لم يكن لديك PowerShell بالفعل، فقم بتثبيت PowerShell على Windows.
تحميل أحدث ملف .zip لأدوات الاختبار واستخراجه.
بدء تشغيل PowerShell.
انتقل إلى المجلد حيث قمت باستخراج مجموعة أدوات الاختبار. داخل هذا المجلد، انتقل إلى مجلد arm-ttk.
إذا كان نهج التنفيذ يمنع البرامج النصية من الإنترنت، فستحتاج إلى إلغاء حظر ملفات البرنامج النصي. تأكد من أنك في مجلد arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
قم باستيراد الوحدة.
```
Import-Module .\arm-ttk.psd1
```
لتشغيل الاختبارات، استخدم الأمر التالي:
```
Test-AzTemplate -TemplatePath \path\to\template
```

التثبيت على Linux

إذا لم يكن لديك PowerShell بالفعل، فقم بتثبيت PowerShell على Linux.
تحميل أحدث ملف .zip لأدوات الاختبار واستخراجه.
بدء تشغيل PowerShell.
```
pwsh
```
انتقل إلى المجلد حيث قمت باستخراج مجموعة أدوات الاختبار. داخل هذا المجلد، انتقل إلى مجلد arm-ttk.
إذا كان نهج التنفيذ يمنع البرامج النصية من الإنترنت، فستحتاج إلى إلغاء حظر ملفات البرنامج النصي. تأكد من أنك في مجلد arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
قم باستيراد الوحدة.
```
Import-Module ./arm-ttk.psd1
```
لتشغيل الاختبارات، استخدم الأمر التالي:
```
Test-AzTemplate -TemplatePath /path/to/template
```

تثبيت على macOS

إذا لم يكن لديك PowerShell بالفعل، فقم بتثبيت PowerShell على macOS.
تثبيت coreutils :
```
brew install coreutils
```
تحميل أحدث ملف .zip لأدوات الاختبار واستخراجه.
بدء تشغيل PowerShell.
```
pwsh
```
انتقل إلى المجلد حيث قمت باستخراج مجموعة أدوات الاختبار. داخل هذا المجلد، انتقل إلى مجلد arm-ttk.
إذا كان نهج التنفيذ يمنع البرامج النصية من الإنترنت، فستحتاج إلى إلغاء حظر ملفات البرنامج النصي. تأكد من أنك في مجلد arm-ttk.
```
Get-ChildItem *.ps1, *.psd1, *.ps1xml, *.psm1 -Recurse | Unblock-File
```
قم باستيراد الوحدة.
```
Import-Module ./arm-ttk.psd1
```
لتشغيل الاختبارات، استخدم الأمر التالي:
```
Test-AzTemplate -TemplatePath /path/to/template
```

تنسيق النتيجة

تُعرض الاختبارات التي تمر باللون الأخضر وتتخذ في أول الأمر شكل [+] .

يتم عرض الاختبارات التي تفشل باللون الأحمر وتتخذ في أول الأمر شكل [-] .

يتم عرض الاختبارات مع تحذير باللون الأصفر وتتخذ في أول الأمر شكل[?] .

لقطة شاشة لنتائج الاختبار بألوان مختلفة للتمرير والفشل والتحذير.

نتائج النص هي:

deploymentTemplate
[+] adminUsername Should Not Be A Literal (6 ms)
[+] apiVersions Should Be Recent In Reference Functions (9 ms)
[-] apiVersions Should Be Recent (6 ms)
    Api versions must be the latest or under 2 years old (730 days) - API version 2019-06-01 of
    Microsoft.Storage/storageAccounts is 760 days old
    Valid Api Versions:
    2021-04-01
    2021-02-01
    2021-01-01
    2020-08-01-preview

[+] artifacts parameter (4 ms)
[+] CommandToExecute Must Use ProtectedSettings For Secrets (9 ms)
[+] DependsOn Best Practices (5 ms)
[+] Deployment Resources Must Not Be Debug (6 ms)
[+] DeploymentTemplate Must Not Contain Hardcoded Uri (4 ms)
[?] DeploymentTemplate Schema Is Correct (6 ms)
    Template is using schema version '2015-01-01' which has been deprecated and is no longer
    maintained.

اختبار المعلمات

عند توفير -TemplatePath المعلمة، تبحث مجموعة الأدوات في هذا المجلد عن قالب يُسمى azuredeploy.json أو maintemplate.json. يقوم باختبار هذا القالب أولاً ثم يختبر كافة القوالب الأخرى في المجلد والمجلدات الفرعية الخاصة به. يتم اختبار القوالب الأخرى باعتبارها قوالب مرتبطة. إذا كان المسار يتضمن ملفًا يُسمىcreateUiDefinition.json، فإنه يقوم بتشغيل الاختبارات ذات الصلة بتعريف UI يتم أيضًا تشغيل الاختبارات لملفات المعلمات وكافة ملفات JSON في المجلد.

Test-AzTemplate -TemplatePath $TemplateFolder

لاختبار ملف واحد في هذا المجلد، أضف -File المعلمة. ومع ذلك، يجب أن يكون المجلد لا يزال يضم قالبًا رئيسيًا يُسمى azuredeploy.json أو maintemplate.json.

Test-AzTemplate -TemplatePath $TemplateFolder -File cdn.json

افتراضيًا، يتم تشغيل كافة الاختبارات. لتحديد الاختبارات الفردية لتشغيل، استخدم -Test المعلمة وحدد اسم الاختبار. للحصول على أسماء الاختبار، راجع قوالب ARMوملفات المعلمات createUiDefinition.json والملفات كافة.

Test-AzTemplate -TemplatePath $TemplateFolder -Test "Resources Should Have Location"

تخصيص الاختبارات

يمكنك تخصيص الاختبارات الافتراضية أو إنشاء الاختبارات الخاصة بك. إذا كنت تريد إزالة اختبار بشكل دائم، فاحذف ملف .test.ps1 من المجلد.

تحتوي مجموعة الأدوات على أربعة مجلدات تحتوي على الاختبارات الافتراضية التي يتم تشغيلها لأنواع ملفات معينة:

قوالب ARM: \arm-ttk\testcases\deploymentTemplate
ملفات المعلمات: \arm-ttk\testcases\deploymentParameters
createUiDefinition.json: \arm-ttk\testcases\CreateUIDefinition
كافة الملفات: \arm-ttk\testcases\AllFiles

إضافة اختبار مخصص

لإضافة الاختبار الخاص بك، قم بإنشاء ملف مع اصطلاح التسمية: Your-Custom-Test-Name.test.ps1.

يمكن للاختبار الحصول على القالب كمعلمة كائن أو معلمة سلسلة. بشكل عام، يمكنك استخدام واحد أو الآخر، ولكن يمكنك استخدام كليهما.

استخدم معلمة الكائن عندما تحتاج إلى الحصول على مقطع من القالب ثم كرر ذلك من خلال خصائصه. اختبار يستخدم معلمة الكائن يحتوي على التنسيق التالي:

param(
  [Parameter(Mandatory=$true,Position=0)]
  [PSObject]
  $TemplateObject
)

# Implement test logic that evaluates parts of the template.
# Output error with: Write-Error -Message

كائن القالب يحتوي على الخصائص التالية:

$schema
contentVersion
parameters
variables
resources
outputs

على سبيل المثال، يمكنك الحصول على مجموعة المعلمات باستخدام $TemplateObject.parameters.

استخدم معلمة السلسلة عندما تحتاج إلى إجراء عملية سلسلة على القالب بأكمله. اختبار يستخدم معلمة السلسلة بالتنسيق التالي:

param(
  [Parameter(Mandatory)]
  [string]
  $TemplateText
)

# Implement test logic that performs string operations.
# Output error with: Write-Error -Message

على سبيل المثال، يمكنك تشغيل تعبير عادي من معلمة السلسلة لمعرفة ما إذا كان يتم استخدام بناء جملة معين.

لمعرفة المزيد حول تنفيذ الاختبار، انظر إلى الاختبارات الأخرى في هذا المجلد.

التحقق من صحة قوالب Azure Marketplace

لنشر عرض Azure Marketplace، استخدم مجموعة أدوات الاختبار للتحقق من صحة القوالب. عندما تجتاز القوالب اختبارات التحقق من الصحة، سيوافق Azure Marketplace على عرضك بسرعة أكبر. إذا فشلوا في الاختبارات، سيفشل العرض في المصادقة.

هام

تمت إضافة اختبارات Marketplace في يوليو 2022. تحديث الوحدة النمطية إذا كان لديك إصدار سابق.

تشغيل الاختبارات في بيئتك

بعد تثبيت مجموعة الأدوات واستيراد الوحدة النمطية، قم بتشغيل cmdlet التالي لاختبار الحزمة الخاصة بك:

Test-AzMarketplacePackage -TemplatePath "Path to the unzipped package folder"

تفسير النتائج

ترجع الاختبارات النتائج في قسمين. يتضمن القسم الأول الاختبارات الإلزامية. يتم عرض نتائج هذه الاختبارات في قسم الملخص.

هام

يجب إصلاح أي نتائج باللون الأحمر قبل قبول عرض Marketplace. نوصي بإصلاح أي نتائج ترجع باللون الأصفر.

نتائج النص هي:

Validating nestedtemplates\AzDashboard.json
    [+] adminUsername Should Not Be A Literal (210 ms)
    [+] artifacts parameter (3 ms)
    [+] CommandToExecute Must Use ProtectedSettings For Secrets (201 ms)
    [+] Deployment Resources Must Not Be Debug (160 ms)
    [+] DeploymentTemplate Must Not Contain Hardcoded Url (13 ms)
    [+] Location Should Not Be Hardcoded (31 ms)
    [+] Min and Max Value Are Numbers (4 ms)
    [+] Outputs Must Not Contain Secrets (9 ms)
    [+] Password params must be secure (3 ms)
    [+] Resources Should Have Location (2 ms)
    [+] Resources Should Not Be Ambiguous (2 ms)
    [+] Secure Params In Nested Deployments (205 ms)
    [+] Secure String Parameters Cannot Have Default (3 ms)
    [+] URIs Should Be Properly Constructed (190 ms)
    [+] Variables Must Be Referenced (9 ms)
    [+] Virtual Machines Should Not Be Preview (173 ms)
    [+] VM Size Should Be A Parameter (165 ms)
Pass : 99
Fail : 3
Total: 102
Validating StartStopV2mkpl_1.0.09302021\anothertemplate.json
    [?] Parameters Must Be Referenced (86 ms)
        Unreferenced parameter: resourceGroupName
        Unreferenced parameter: location
        Unreferenced parameter: azureFunctionAppName
        Unreferenced parameter: applicationInsightsName
        Unreferenced parameter: applicationInsightsRegion

يتضمن القسم الموجود أسفل قسم الملخص حالات فشل الاختبار التي يمكن تفسيرها على أنها تحذيرات. إصلاح حالات الفشل اختياري ولكن يوصى به بشدة. غالبا ما تشير حالات الفشل إلى مشكلات شائعة تتسبب في حدوث حالات فشل عندما يقوم العميل بتثبيت عرضك.

لإصلاح الاختبارات، اتبع حالة الاختبار التي تنطبق عليك:

إرسال العرض

بعد إجراء أي إصلاحات ضرورية، أعد تشغيل مجموعة أدوات الاختبار. قبل إرسال عرضك إلى Azure Marketplace، تأكد من عدم وجود حالات فشل.

التكامل مع Azure Pipelines

يمكنك إضافة مجموعة أدوات الاختبار إلى Azure Pipelines الخاص بك. باستخدام البنية الأساسية لبرنامج ربط العمليات التجارية، يمكنك تشغيل الاختبار في كل مرة يتم فيها تحديث القالب، أو تشغيله كجزء من عملية النشر.

أسهل طريقة لإضافة مجموعة أدوات الاختبار إلى البنية الأساسية لبرنامج ربط العمليات التجارية الخاص بك تكون مع ملحقات الجهات الخارجية. يتوفر الملحقان التاليان:

أو يمكنك تنفيذ المهام الخاصة بك. يوضح المثال التالي كيفية تنزيل مجموعة أدوات الاختبار.

بالنسبة إلى البنية الأساسية لبرنامج ربط العمليات التجارية للإصدار:

{
  "environment": {},
  "enabled": true,
  "continueOnError": false,
  "alwaysRun": false,
  "displayName": "Download TTK",
  "timeoutInMinutes": 0,
  "condition": "succeeded()",
  "task": {
    "id": "e213ff0f-5d5c-4791-802d-52ea3e7be1f1",
    "versionSpec": "2.*",
    "definitionType": "task"
  },
  "inputs": {
    "targetType": "inline",
    "filePath": "",
    "arguments": "",
    "script": "New-Item '$(ttk.folder)' -ItemType Directory\nInvoke-WebRequest -uri '$(ttk.uri)' -OutFile \"$(ttk.folder)/$(ttk.asset.filename)\" -Verbose\nGet-ChildItem '$(ttk.folder)' -Recurse\n\nWrite-Host \"Expanding files...\"\nExpand-Archive -Path '$(ttk.folder)/*.zip' -DestinationPath '$(ttk.folder)' -Verbose\n\nWrite-Host \"Expanded files found:\"\nGet-ChildItem '$(ttk.folder)' -Recurse",
    "errorActionPreference": "stop",
    "failOnStderr": "false",
    "ignoreLASTEXITCODE": "false",
    "pwsh": "true",
    "workingDirectory": ""
  }
}

لتعريف YAML للبنية الأساسية لبرنامج ربط العمليات التجارية:

- pwsh: |
   New-Item '$(ttk.folder)' -ItemType Directory
   Invoke-WebRequest -uri '$(ttk.uri)' -OutFile "$(ttk.folder)/$(ttk.asset.filename)" -Verbose
   Get-ChildItem '$(ttk.folder)' -Recurse
   
   Write-Host "Expanding files..."
   Expand-Archive -Path '$(ttk.folder)/*.zip' -DestinationPath '$(ttk.folder)' -Verbose
   
   Write-Host "Expanded files found:"
   Get-ChildItem '$(ttk.folder)' -Recurse
  displayName: 'Download TTK'

يوضح المثال التالي كيفية تشغيل الاختبارات.