Compilar y probar PowerShell

Introducción

Esta guía te muestra cómo utilizar PowerShell para la IC. Describimos cómo utilizar Pester, instalar dependencias, probar tu módulo y publicarlo en la galería de PowerShell.

Los ejecutores hospedados en GitHub tienen un caché de herramientas con software pre-instalado, lo cual incluye a PowerShell y a Pester.

Para obtener una lista completa de software actualizado y las versiones preinstaladas de PowerShell y Pester, vea "Especificaciones para ejecutores hospedados en GitHub".

Requisitos previos

Deberías estar familiarizado con YAML y la sintaxis para las GitHub Actions. Para más información, vea "Más información sobre GitHub Actions".

Te recomendamos tener un entendimiento básico de PowerShell y de Pester. Para más información, consulte:

• Introducción a PowerShell
• Pester

Utilizar ejecutores auto-hospedados en GitHub Enterprise Server

Cuando use acciones de configuración, (como actions/setup-LANGUAGE) en GitHub Enterprise Server con ejecutores autohospedados, es posible que necesite configurar la caché de herramientas en los ejecutores que no tienen acceso a Internet. Para más información, vea "Configuración de la caché de herramientas en ejecutores autohospedados sin acceso a Internet".

Agregar un flujo de trabajo para Pester

Para automatizar tus pruebas con PowerShell y con Pester, puedes agregar un flujo de trabajo que se ejecute cada que se sube un cambio en tu repositorio. En el ejemplo siguiente, se usa Test-Path para comprobar que existe un archivo con el nombre resultsfile.log.

Este archivo de flujo de trabajo de ejemplo se debe agregar al directorio .github/workflows/ del repositorio:

name: Test PowerShell on Ubuntu
on: push

jobs:
  pester-test:
    name: Pester test
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v2
      - name: Perform a Pester test from the command-line
        shell: pwsh
        run: Test-Path resultsfile.log | Should -Be $true
      - name: Perform a Pester test from the Tests.ps1 file
        shell: pwsh
        run: |
          Invoke-Pester Unit.Tests.ps1 -Passthru

• shell: pwsh: configura el trabajo para que use PowerShell al ejecutar los comandos run.

• run: Test-Path resultsfile.log: comprueba si existe un archivo con el nombre resultsfile.log en el directorio raíz del repositorio.

• Should -Be $true: usa Pester para definir un resultado esperado. Si el resultado es inesperado, entonces GitHub Actions lo marca como una prueba fallida. Por ejemplo:

  

• Invoke-Pester Unit.Tests.ps1 -Passthru: usa Pester para ejecutar pruebas definidas en un archivo denominado Unit.Tests.ps1. Por ejemplo, para realizar la misma prueba que se ha descrito antes, Unit.Tests.ps1 contendrá lo siguiente:

  Describe "Check results file is present" {
      It "Check results file is present" {
          Test-Path resultsfile.log | Should -Be $true
      }
  }
  

Ubicaciones de los módulos de PowerShell

En la siguiente tabla se describen las ubicaciones para varios módulos de PowerShell en cada ejecutor hospedado en GitHub.

	Ubuntu	macOS	Windows
Módulos de sistema de PowerShell	/opt/microsoft/powershell/7/Modules/*	/usr/local/microsoft/powershell/7/Modules/*	C:\program files\powershell\7\Modules\*
Módulos de complementos de PowerShell	/usr/local/share/powershell/Modules/*	/usr/local/share/powershell/Modules/*	C:\Modules\*
Módulos instalados por el usuario	/home/runner/.local/share/powershell/Modules/*	/Users/runner/.local/share/powershell/Modules/*	C:\Users\runneradmin\Documents\PowerShell\Modules\*

Instalación de dependencias

Los ejecutores hospedados en GitHub tienen PowerShell 7 y Pester instalados. Puede usar Install-Module para instalar dependencias adicionales desde la Galería de PowerShell antes de compilar y probar el código.

Por ejemplo, el siguiente trabajo instala los módulos SqlServery PSScriptAnalyzer:

jobs:
  install-dependencies:
    name: Install dependencies
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install from PSGallery
        shell: pwsh
        run: |
          Set-PSRepository PSGallery -InstallationPolicy Trusted
          Install-Module SqlServer, PSScriptAnalyzer

Probar el código

Puedes usar los mismos comandos que usas de forma local para construir y probar tu código.

Utilizar PSScriptAnalyzer para limpiar el código

En el ejemplo siguiente se instala PSScriptAnalyzer y se usa para el lint de todos los archivos ps1 del repositorio. Para más información, vea PSScriptAnalyzer en GitHub.

  lint-with-PSScriptAnalyzer:
    name: Install and run PSScriptAnalyzer
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install PSScriptAnalyzer module
        shell: pwsh
        run: |
          Set-PSRepository PSGallery -InstallationPolicy Trusted
          Install-Module PSScriptAnalyzer -ErrorAction Stop
      - name: Lint with PSScriptAnalyzer
        shell: pwsh
        run: |
          Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues
          $errors   = $issues.Where({$_.Severity -eq 'Error'})
          $warnings = $issues.Where({$_.Severity -eq 'Warning'})
          if ($errors) {
              Write-Error "There were $($errors.Count) errors and $($warnings.Count) warnings total." -ErrorAction Stop
          } else {
              Write-Output "There were $($errors.Count) errors and $($warnings.Count) warnings total."
          }

Empaquetar datos de flujo de trabajo como artefactos

Puedes cargar artefactos para ver después de que se complete un flujo de trabajo. Por ejemplo, es posible que debas guardar los archivos de registro, los vaciados de memoria, los resultados de las pruebas o las capturas de pantalla. Para más información, vea "Conservación de datos de flujo de trabajo mediante artefactos".

En el ejemplo siguiente se muestra cómo puede usar la upload-artifact acción para archivar los resultados de la prueba recibidos de Invoke-Pester. Para más información, vea la acción upload-artifact.

name: Upload artifact from Ubuntu

on: [push]

jobs:
  upload-pester-results:
    name: Run Pester and upload results
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Test with Pester
        shell: pwsh
        run: Invoke-Pester Unit.Tests.ps1 -Passthru | Export-CliXml -Path Unit.Tests.xml
      - name: Upload test results
        uses: actions/upload-artifact@v2
        with:
          name: ubuntu-Unit-Tests
          path: Unit.Tests.xml
    if: ${{ always() }}

La función always() configura el trabajo para que el procesamiento continúe aunque se produzcan fallos en las pruebas. Para más información, vea "always".

Publicar en la galería de PowerShell

Puedes configurar tu flujo de trabajo para que publique tu módulo de PowerShell en la galería de PowerShell cuando pasen tus pruebas de IC. Puedes utilizar los secretos para almacenar cualquier token o credencial que se necesiten para publicar tu paquete. Para más información, vea "Creación y uso de secretos cifrados".

En el ejemplo siguiente se crea un paquete y se usa Publish-Module para publicarlo en la Galería de PowerShell:

name: Publish PowerShell Module

on:
  release:
    types: [created]

jobs:
  publish-to-gallery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build and publish
        env:
          NUGET_KEY: ${{ secrets.NUGET_KEY }}
        shell: pwsh
        run: |
          ./build.ps1 -Path /tmp/samplemodule
          Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose