Navodilo: Preizkušanje aplikacije

Aplikacijo Access lahko preverjate s preizkusi, napisanimi v VBA, in jih zaženete iz ukazne vrstice ali na strežniku CI. Med izvajanjem nikomur ni treba ničesar tipkati ali klikati na namizju.

• Projektna datoteka navede preizkusno funkcijo (<Test>), ki vrne imena preizkusnih postopkov.
• Preizkusni postopek je javni Sub brez argumentov v standardnem modulu izvornih datotek. Aplikacijo upravlja iz kode: odpira obrazce z DoCmd.OpenForm, kliče ukaze aplikacije, bere kontrolnike in podatke ter rezultate preverja z WklTest.Check.
• Na pogovorna okna aplikacije odgovarjajo preizkusi. Aplikacija pred vsakim MsgBox, InputBox ali pogovornim oknom za izbiro datoteke vpraša WklTest.Answer. Zunaj preizkusa je odgovor Empty in okno se prikaže kot doslej.
• wkl-office test zgradi projekt in nato vsak preizkusni postopek izvede posebej v skritem programu Access na kopiji podatkovne zbirke. Za vsako preverjanje izpiše vrstico, konča se z izhodno kodo, v delovni mapi pa pusti poročilo JUnit.
• PowerShell zažene in oceni, VBA upravlja. Skript ali strežnik CI pokliče wkl-office test in wkl-office call ter prebere izhodno kodo, izhod JSON in poročila. Vmesnika, s katerim bi skript prek COM upravljal Access, ki že teče (odpiral obrazce, sprožal ukaze, bral kontrolnike), ni; to v VBA počnejo preizkusni postopki.

SDK modul WklTest vstavi v vsako gradnjo projekta, ki navaja preizkusno funkcijo. Aplikacija zato ne potrebuje dodatnega sklica.

1. V projektni datoteki navedite preizkusno funkcijo.

<Project>
  <PropertyGroup>
    <SchemaVersion>2</SchemaVersion>
    <AssemblyName>Orders</AssemblyName>
    <Test>AllTests</Test>
  </PropertyGroup>
</Project>

2. Aplikacija naj pred pogovornim oknom vpraša WklTest.Answer. Zadošča ena funkcija za vsako vrsto pogovornega okna, ki jo preostala aplikacija kliče namesto MsgBox:

' A question to the user; in a test run the answer the test expects instead of the message box.
Public Function AskUser(ByVal Prompt As String, ByVal Buttons As VbMsgBoxStyle) As VbMsgBoxResult
    Dim reply As Variant
 
    reply = WklTest.Answer(WklTest.KindMessage, Prompt)
    If IsEmpty(reply) Then
        AskUser = MsgBox(Prompt, Buttons)
    ElseIf IsNumeric(reply) Then
        AskUser = CLng(reply)
    Else
        AskUser = vbCancel
    End If
End Function

3. Napišite preizkusne postopke v standardnem modulu izvornih datotek, na primer source\modules\basTests.bas:

Option Compare Database
Option Explicit
 
' The test procedures wkl-office test runs, in this order.
Public Function AllTests() As Variant
    AllTests = Array("Orders_Total", "Orders_DeleteAsks")
End Function
 
Public Sub Orders_Total()
    WklTest.Check "total of two lines", OrderTotal(Array(10, 5)) = 15, "total was " & OrderTotal(Array(10, 5))
End Sub
 
Public Sub Orders_DeleteAsks()
    WklTest.Expect WklTest.KindMessage, "Delete order *", vbNo
    DeleteOrder 42
    WklTest.Check "order 42 kept after No", DCount("*", "tblOrder", "OrderId = 42") = 1, "order 42 was deleted"
End Sub

Preizkusni postopek ne potrebuje lastne obravnave napak. Napaka med izvajanjem, ki je postopek ne obravnava, se sporoči kot neuspešna vrstica z besedilom napake, nato se izvede naslednji postopek.

4. Zaženite preizkuse.

wkl-office test Orders.acproj
wkl-office test Orders.acproj --only Orders_DeleteAsks
wkl-office test Orders.acproj -c Release -t accde --json

OK   Orders_Total: total of two lines
FAIL Orders_DeleteAsks: order 42 kept after No :: order 42 was deleted
1 OK, 1 FAIL (preizkusni postopki: 2)

Izhodna koda 0 pomeni, da so vsa preverjanja uspela, 15 pa, da vsaj eno ni uspelo. Druge izhodne kode in izhod JSON so opisani v referenčnem priročniku ukazne vrstice.

Če je podatkovna zbirka odprta v programu Access, je gradnja ne more zamenjati; z --no-build se preizkusi izvedejo na nazadnje zgrajeni podatkovni zbirki, tukaj v terminalu dodatka:

Preizkus z dvema preizkusnima postopkoma: vrstica za vsako preverjanje, nato povzetek.

V urejevalniku VBA meni Preizkusi dodatka izvede iste preizkusne postopke na podatkovni zbirki, odprti v Accessu, ne da bi zapustili urejevalnik; neuspelo preverjanje v Težavah odpre svoj preizkusni postopek (glejte Uporaba dodatka za Access).

Z --json wkl-office test rezultat izpiše kot en objekt JSON (polja: Izhod JSON), izhodna koda pa pove, kako se je izvajanje končalo. Naslednji skript je korak CI v mapi projekta: preizkusi ACCDB in ACCDE, pred vsakim izvajanjem v delovno mapo kopira vhodne datoteke iz mape fixtures, izpiše neuspela preverjanja in se konča s prvo izhodno kodo, ki ni 0.

# Runs the tests of a project as a CI step: ACCDB and ACCDE, input files in the work folder, failed checks listed.
param([string] $Project = 'Orders.acproj', [string] $Results = 'test-results')
 
$worst = 0
foreach ($target in 'accdb', 'accde') {
    $work = Join-Path $Results $target
    New-Item -ItemType Directory $work -Force | Out-Null
    Copy-Item fixtures\* $work -Recurse -Force    # the tests read them from CurrentProject.Path
 
    $run = wkl-office test $Project -t $target --work $work --json | ConvertFrom-Json
    $code = $LASTEXITCODE
    switch ($code) {
        0       { "${target}: $($run.passed) checks passed" }
        15      { "${target}: $($run.failed) checks failed"
                  $run.checks | Where-Object { -not $_.ok } | ForEach-Object { "  FAIL $($_.test): $($_.name) :: $($_.message)" } }
        13      { "${target}: time limit: $($run.problem)" }
        16      { "${target}: Access ended: $($run.problem)" }
        default { "${target}: no test run (exit $code): $($run.problem)" }
    }
    if ($code -ne 0 -and $worst -eq 0) { $worst = $code }
}
exit $worst

Nato je v vsaki delovni mapi kopija podatkovne zbirke, wkl-test-run.jsonl in poročilo JUnit wkl-test-report.xml; strežnik CI arhivira mapo test-results. Če se je izvajanje ustavilo (izhodna koda 13 ali 16), so preverjanja, zapisana do takrat, v wkl-test-run.jsonl, po ena vrstica JSON za vsak vnos; preverjanja imajo kind enak check:

Get-Content test-results\accdb\wkl-test-run.jsonl | ForEach-Object { $_ | ConvertFrom-Json } |
    Where-Object { $_.kind -eq 'check' -and -not $_.ok } | Format-Table test, name, message

Delovanje, ki velja samo zunaj preizkusnega izvajanja (WklTest.InRun() je False), skript preveri z ukazom call v isti delovni mapi. call tam kopijo podatkovne zbirke zamenja z novo kopijo rezultata gradnje, druge datoteke ostanejo, {work} v argumentu pa pomeni delovno mapo:

$text = wkl-office call Orders.acproj OrderNumberText 42 --work test-results\accdb
if ($LASTEXITCODE -ne 0 -or $text -ne 'A-00042') { throw "OrderNumberText returned '$text' (exit $LASTEXITCODE)" }

Modul pripada SDK. Vsaka gradnja modul WklTest iz izvornih datotek nadomesti s svojim, naslednji izvoz pa ga zapiše v izvorne datoteke. Spreminja se le z novo različico SDK. Aplikacija, ki se mora prevesti tudi brez gradnje z SDK, lahko ima nadomestni modul WklTest s funkcijama Answer (vrne Empty) in InRun (vrne False), s konstantami od KindMessage do KindFolder z vrednostmi iz tabele ter s funkcijo Cancel (vrne Null), če jo koda uporablja.

• Imena modula. Modul WklTest v projekt doda javne elemente InRun, Cancel, Answer, Expect, Check, Progress in konstante od KindMessage do KindFolder. Če ima standardni modul aplikacije javni element z enakim imenom in ga koda uporablja brez imena modula, VBA javi „Ambiguous name detected“ (dvoumno ime) in projekta ni več mogoče prevesti. Ime modula zato navedite: WklTest.KindOpen za element SDK, <modul>.KindOpen za lastnega. Primeri na tej strani vedno pišejo WklTest..
• Nič se ne zažene samo od sebe. Kopija se odpre tako kot pri call: brez zagonskega obrazca, povratnih klicev traku in makra AutoExec. Podatkovno zbirko z makrom AutoExec ukaz zavrne. Preizkus, ki potrebuje pripravo, ki jo sicer opravi zagonski obrazec, mora to kodo poklicati sam.
• Postopki tečejo drug za drugim. Spremenljivke modulov ohranijo vrednosti od enega postopka do naslednjega, napaka med izvajanjem pa jih ponastavi. Preizkus zato ne sme biti odvisen od prejšnjega.
• Pogovorna okna, ki ne vprašajo WklTest.Answer, ukaz zapre z gumbom Prekliči, Ne ali V redu, postopek pa ne uspe. Obrazec, odprt z acDialog, čaka do časovne omejitve; v preizkusu takšne obrazce odprite brez acDialog in jih preverite neposredno. Pogovorno okno VBA za napako med izvajanjem se na namizju prikaže za približno sekundo, tudi ko Access teče skrito.
• Časovna omejitev in sesutja. Če postopek preseže --timeout (privzeto 120 sekund), se njegov Access konča, izvajanje pa se ustavi z izhodno kodo 13. Če se Access med postopkom konča, se izvajanje ustavi z izhodno kodo 16 in navede zadnjo zapisano vrstico; vse vrstice pred tem so v datoteki wkl-test-run.jsonl v delovni mapi.
• Preizkusi, ki se ne izvajajo več, ne ostanejo neopaženi: če ima izvajanje vseh postopkov manj preverjanj kot zadnje uspešno, ne uspe z vrstico check count.
• Preizkusi za vsak jezik. --language sl izvede postopke z besedili aplikacije in komponentami WKL v slovenščini, ne glede na jezik Officea, zato en računalnik preveri vse jezike aplikacije (besedila aplikacije). Število preverjanj se vodi za vsak jezik posebej. Zahteva WKL Forms Object Library 1.65 ali novejšo različico.
• Strežniki CI berejo build\<configuration>\test\wkl-test-report.xml (JUnit XML). Preizkusi tečejo v programu Access računalnika za gradnjo, v njegovi 32- ali 64-bitni različici.
• Delovna mapa (privzeto build\<configuration>\test, sicer --work) se ustvari, če je ni, vendar se ne izprazni: test v njej zamenja samo kopijo podatkovne zbirke in wkl-test-run.jsonl. Datoteke, ki jih skript shrani vanjo prej, preizkusi najdejo pod CurrentProject.Path.
• Vrednosti za preizkuse. test preizkusnim postopkom ne posreduje parametrov; vhodne podatke shranite kot datoteke v delovno mapo. V sistemu Windows 11 skriti Access sicer vidi spremenljivke okolja procesa, ki ga je zagnal, vendar SDK tega ne zagotavlja. V delovno mapo ne zapisujte gesel, ker njene datoteke po izvajanju ostanejo.
• Access Runtime in ročno upravljanje. Preizkusi tečejo v polni različici programa Access, tudi z -t accde; izvajanje v okolju Access Runtime (/runtime) ni podprto. Upravljanja s pravimi tipkami in miško v vidnem programu Access (vrstni red tabulatorja, fokus, bližnjične tipke, vlečenje in spuščanje) test ne preverja.
• Preizkusi v izdani aplikaciji. Preizkusni postopki so izvorne datoteke kot vsak drug modul in se zgradijo v vsako podatkovno zbirko projekta, tudi v tisto za izdajo. Če jih v izdaji ne želite, jih premaknite v ločen preizkusni projekt, ki glavni projekt navaja kot predlogo (projektna mapa).

• Referenčni priročnik ukazne vrstice: test in call
• Projektna datoteka: preizkusna funkcija
• Projektna mapa