Praktik terbaik untuk menguji paket Julia Anda – Beragampengetahuan

Oleh: Konsultasi Great Lakes

Diposting ulang dari:

Artikel ini ditulis oleh Steven Whitaker.

Bahasa pemrograman Julia adalah bahasa tingkat tinggi yang dikenal, setidaknya sebagian, karena manajer paketnya yang sangat baik dan kemampuan komposisinya yang luar biasa. (Lihat postingan blog lain yang mengilustrasikan kombinasi kemungkinan ini.)

Julia memudahkan siapa saja untuk membuat paketnya sendiri. Manajer paket Julia memungkinkan pengembangan dan pengujian paket dengan mudah. Kemudahan pengembangan paket mendorong pengembang untuk membagi segmen kode yang dapat digunakan kembali menjadi paket individual, sehingga semakin meningkatkan kemampuan komposisi Julia.

Di artikel kami sebelumnya, kami membahas cara membuat dan mendaftar paket Anda sendiri. Namun, untuk mendorong orang agar benar-benar menggunakan rencana Anda, penting untuk memastikan rencana tersebut berhasil. Inilah sebabnya mengapa pengujian itu penting. (Selain itu, Anda juga ingin tahu paket Anda berfungsi, bukan?)

Dalam postingan ini, kita akan mempelajari beberapa alat yang ditawarkan Julia untuk paket pengujian. Kita juga akan mempelajari cara menggunakan GitHub Actions untuk menjalankan pengujian paket terhadap penerapan dan/atau permintaan penarikan untuk memeriksa apakah perubahan kode merusak fungsionalitas paket.

Posting ini mengasumsikan bahwa Anda merasa nyaman menavigasi REPL Julia. Jika Anda memerlukan penyegaran, lihat postingan kami di REPL Julia.

Kami akan menggunakan paket khusus bernama Averages.jl untuk mendemonstrasikan cara mengimplementasikan pengujian di Julia.

itu Project.toml terlihat seperti:

name = "Averages"uuid = "1fc6e63b-fe0f-463a-8652-42f2a29b8cc6"version = "0.1.0"[deps]Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"[extras]Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"[targets]test = ["Test"]

Perhatikan bahwa ini Project.toml Ada juga dua bagian lagi [deps]:

• [extras] digunakan untuk menunjukkan paket tambahan yang tidak bergantung langsung pada paket tersebut. Dalam contoh ini, Check tidak digunakan di Averages.jl itu sendiri; Tes hanya digunakan saat menjalankan tes.
• [targets] digunakan untuk menentukan paket mana yang digunakan di mana. Dalam contoh ini,test = ["Test"] menunjukkan bahwa paket Test harus digunakan saat menguji Averages.jl.

Kode paket sebenarnya di src/Averages.jl terlihat seperti:

module Averagesusing Statisticsexport compute_averagecompute_average(x) = (check_real(x); mean(x))function compute_average(a, b...)    check_real(a)    N = length(a)    for (i, x) in enumerate(b)        check_real(x)        check_length(i + 1, x, N)    end    T = float(promote_type(eltype(a), eltype.(b)...))    average = VectorT(undef, N)    average .= a    for x in b        average .+= x    end    average ./= length(b) + 1    return a isa Real ? average[1] : averageendfunction check_real(x)    T = eltype(x)    T <: Real || throw(ArgumentError("only real numbers are supported; unsupported type $T"))endfunction check_length(i, x, expected)    N = length(x)    N == expected || throw(DimensionMismatch("the length of input $i does not match the length of the first input: $N != $expected"))endend

Tes untuk paket langsung test/runtests.jl.(Nama file penting!) Di dalam file ini dua utilitas pengujian utama digunakan:@testset Dan @test.Di samping itu,@test_throws Bisa juga berguna untuk pengujian. Paket perpustakaan standar eksperimental menyediakan semua makro ini.

• @testset digunakan untuk mengatur tes ke dalam blok kohesif.
• @test digunakan untuk benar-benar menguji fungsionalitas paket.
• @test_throws digunakan untuk memastikan paket akan menghapus kesalahan yang diperlukan.

Begini caranya test/runtests.jl dapat mencari Rata-rata.jl:

using Averagesusing Test@testset "Averages.jl" begin    a = [1, 2, 3]    b = [4.0, 5.0, 6.0]    c = (BigInt(7), 8f0, Int32(9))    d = 10    e = 11.0    bad = ["hi", "hello", "hey"]    @testset "`compute_average(x)`" begin        @test compute_average(a) == 2        @test compute_average(a) isa Float64        @test compute_average(c) == 8        @test compute_average(c) isa BigFloat        @test compute_average(d) == 10    end    @testset "`compute_average(a, b...)`" begin        @test compute_average(a, a) == a        @test compute_average(a, b) == [2.5, 3.5, 4.5]        @test compute_average(a, b, c) == b        @test compute_average(a, b, c) isa VectorFloat64        @test compute_average(b, b, b) == b        @test compute_average(d, e) == 10.5    end    @testset "Error Handling" begin        @test_throws ArgumentError compute_average(im)        @test_throws ArgumentError compute_average(a, bad)        @test_throws ArgumentError compute_average(bad, c)        @test_throws DimensionMismatch compute_average(a, b[1:2])        @test_throws DimensionMismatch compute_average(a[1:2], b)    endend

Sekarang mari kita lihat lebih dekat makro yang digunakan:

• @testset dapat diberi label untuk membantu mengatur laporan yang dihasilkan Julia di akhir ujian. Di samping itu,@testset mengelilingi serangkaian tes (termasuk tes lainnya @testsetS).
• @test diberikan ekspresi yang bernilai boolean. Jika boolean adalah trueLulus tes; jika tidak, gagal.
• @test_throws membutuhkan dua input: tipe kesalahan dan kemudian ekspresi. Pengujian lolos jika ekspresi yang memunculkan kesalahan bertipe tertentu.

Lihat paket lainnya

Dalam beberapa kasus, Anda mungkin ingin memastikan paket Anda kompatibel dengan tipe yang ditentukan dalam paket lain. Sebagai contoh, mari kita lihat StaticArrays.jl. Paket kami tidak bergantung pada StaticArrays.jl, jadi kami perlu menambahkannya sebagai pengujian – dependensi hanya dengan mengedit [extras] Dan [targets] bagian dalam Project.toml:

[extras]StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"[targets]test = ["StaticArrays", "Test"]

(Perhatikan bahwa saya mendapatkan UUID untuk StaticArrays.jl darinya Project.toml di GitHub.)

Kami kemudian dapat menambahkan beberapa tes untuk memastikannya compute_average Cukup umum untuk digunakan StaticArrayS:

using Averagesusing Testusing StaticArrays@testset "Averages.jl" begin        @testset "StaticArrays.jl" begin        s = SA[12, 13, 14]        @test compute_average(s) == 13        @test compute_average(s, s) == [12, 13, 14]        @test compute_average(a, b, s) == [17/3, 20/3, 23/3]        @test compute_average(s, a, c) == [20/3, 23/3, 26/3]    endend

Sekarang Rata-rata.jl siap untuk pengujian. Untuk menjalankan pengujian paket di komputer Anda sendiri, mulai Julia, aktifkan lingkungan paket, lalu jalankan test dari paket prompt:

(@v1.X) pkg> activate /path/to/Averages(Averages) pkg> test

Hal pertama test tidak menyiapkan lingkungan paket sementara untuk pengujian yang menyertakan paket yang ditentukan di dalamnya test menargetkan Project.toml.Ini kemudian menjalankan tes dan menampilkan hasilnya:

     Testing Running tests...Test Summary: | Pass  Total  TimeAverages.jl   |   20     20  0.7s     Testing Averages tests passed

Jika pengujian gagal, hasilnya adalah sebagai berikut:

     Testing Running tests...`compute_average(a, b...)`: Test Failed at /path/to/Averages/test/runtests.jl:27  Expression: compute_average(a, b) == [2.0, 3.5, 4.5]   Evaluated: [2.5, 3.5, 4.5] == [2.0, 3.5, 4.5]Stacktrace: [1] macro expansion   @ /path/to/julia-1.X.Y/share/julia/stdlib/v1.X/Test/src/Test.jl:672 [inlined] [2] macro expansion   @ /path/to/Averages/test/runtests.jl:27 [inlined] [3] macro expansion   @ /path/to/julia-1.X.Y/share/julia/stdlib/v1.X/Test/src/Test.jl:1577 [inlined] [4] macro expansion   @ /path/to/Averages/test/runtests.jl:26 [inlined] [5] macro expansion   @ /path/to/julia-1.X.Y/share/julia/stdlib/v1.X/Test/src/Test.jl:1577 [inlined] [6] top-level scope   @ /path/to/Averages/test/runtests.jl:7Test Summary:                | Pass  Fail  Total  TimeAverages.jl                  |   19     1     20  0.9s  `compute_average(x)`       |    5            5  0.1s  `compute_average(a, b...)` |    5     1      6  0.6s  Error Handling             |    5            5  0.0s  StaticArrays.jl            |    4            4  0.2sERROR: LoadError: Some tests did not pass: 19 passed, 1 failed, 0 errored, 0 broken.in expression starting at /path/to/Averages/test/runtests.jl:5ERROR: Package Averages errored during testing

Beberapa hal yang perlu diperhatikan:

Sekarang, saat mengembangkan Averages.jl, kita dapat menjalankan pengujian secara lokal untuk memastikan kita tidak merusak fungsionalitas apa pun!

Selain menjalankan pengujian secara lokal, seseorang dapat menggunakan Tindakan GitHub untuk menjalankan pengujian di salah satu server GitHub. Salah satu keuntungannya adalah memungkinkan pengujian otomatis pada banyak mesin/sistem operasi berbeda dan pada banyak versi Julia yang berbeda. Mengotomatiskan pengujian dengan cara ini adalah bagian penting dari integrasi berkelanjutan (CI) (sedemikian rupa sehingga frasa “jalankan CI” setara dengan “jalankan pengujian melalui GitHub Actions,” meskipun secara teknis CI tidak hanya terkait dengan pengujian).

Untuk mengaktifkan pengujian melalui GitHub Actions, kita hanya perlu menambahkan opsi yang sesuai .yml mengajukan lamaran .github/workflows folder paket kami. Seperti disebutkan dalam artikel kami sebelumnya, PkgTemplates.jl dapat secara otomatis menghasilkan apa yang diperlukan .yml file. Ini adalah alur kerja CI default yang dihasilkan oleh PkgTemplates.jl:

name: CIon:  push:    branches:      - main    tags: ['*']  pull_request:  workflow_dispatch:concurrency:      group: $ github.workflow -$ github.ref   cancel-in-progress: $ startsWith(github.ref, 'refs/pull/') jobs:  test:    name: Julia $ matrix.version  - $ matrix.os  - $ matrix.arch  - $ github.event_name     runs-on: $ matrix.os     timeout-minutes: 60    permissions:       actions: write      contents: read    strategy:      fail-fast: false      matrix:        version:          - '1.10'          - '1.6'          - 'pre'        os:          - ubuntu-latest        arch:          - x64    steps:      - uses: actions/checkout@v4      - uses: julia-actions/setup-julia@v2        with:          version: $ matrix.version           arch: $ matrix.arch       - uses: julia-actions/cache@v2      - uses: julia-actions/julia-buildpkg@v1      - uses: julia-actions/julia-runtest@v1

Bagi sebagian besar pengguna, bidang yang paling cocok untuk disesuaikan adalah version Dan os(di bawah jobs: test: strategy: matrix).Di bawah osTentukan sistem operasi untuk menjalankan pengujian (misalnya: ubuntu-latest, windows-latest, macOS-latest).Di bawah versionTentukan versi Julia yang akan digunakan saat pengujian:

• '1.X' artinya berjalan di Julia 1.XY, dimana Y merupakan patch terbesar Julia 1.X yang pernah dirilis. Misalnya:'1.9' berarti berjalan di Julia 1.9.4.
• '1' berarti berjalan pada Julia versi stabil terbaru.
• 'pre' berarti menjalankan Julia versi pra-rilis terbaru.
• 'lts' berarti menjalankan Julia versi dukungan jangka panjang (LTS).

Biasanya, memeriksa saja sudah masuk akal '1' Dan 'pre'untuk memastikan kompatibilitas dengan versi Julia saat ini dan yang akan datang.

Seseorang juga dapat menyempurnakannya version Dan os bidang, serta bidang lainnya, saat membuat paket dengan PkgTemplates.jl. Misalnya saja untuk membuat .yml file untuk menjalankan pengujian pada Windows hanya dengan Julia 1.8 dan Julia versi pra-rilis terbaru:

using PkgTemplatesgha = GitHubActions(; linux = false, windows = true, extra_versions = ["1.8", "pre"])t = Template(; dir = ".", plugins = [gha])t("MyPackage")

Perhatikan itu .yml File yang dihasilkan juga akan mencakup pengujian pada Julia 1.6.The Template Konstruktor memiliki argumen kata kunci juliaatur versi minimum Julia yang Anda ingin paket Anda dukung dan versi ini disertakan dalam pengujian. Saat tulisan ini dibuat, secara default versi minimumnya adalah Julia 1.6.

Lihat dokumentasi untuk PkgTemplates.jl Template Dan GitHubActionsuntuk detail lebih lanjut tentang penyesuaian .yml mengajukan. Lihat juga dokumentasi Tindakan GitHub, dan khususnya dokumentasi sintaksis alur kerja, untuk detail lebih lanjut tentang apa yang dimaksud .yml (Berhati-hatilah, dokumen-dokumen ini cukup panjang dan mungkin tidak terlalu berguna bagi kebanyakan orang dalam menjalankan dan menjalankan proses CI. Untuk gambaran umum yang lebih mudah diakses .yml file, pertimbangkan untuk membaca panduan ini untuk membuat dan menguji Python.)

Sekali kita dorong .github/workflows/CI.yml ke GitHub, kapan pun cabangnya main didorong ke atau permintaan tarik (PR) dibuka atau didorong, pengujian paket kami akan dijalankan. Inilah inti dari CI: terus memastikan perubahan yang kita buat pada kode kita terintegrasi dengan baik dengan basis kode (yaitu tidak merusak sesuatu). Dengan menjalankan pengujian terhadap PR, kami dapat yakin bahwa perubahan yang dilakukan tidak merusak fungsionalitas yang ada.

Satu hal keren tentang GitHub Actions adalah GitHub menyediakan lencana/ikon status yang dapat Anda tampilkan di README paket Anda. Lencana ini memberi tahu semua orang

1. bahwa paket Anda diperiksa secara teratur dan
2. apakah status paket Anda saat ini lolos pengujian tersebut.

Dengan kata lain, lencana ini adalah cara yang baik untuk meningkatkan keyakinan bahwa rencana Anda layak digunakan. Anda dapat menambahkan lencana ini ke README rencana Anda dengan menambahkan sesuatu seperti markup berikut:

[![CI](https://github.com/username/Averages.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/username/Averages.jl/actions/workflows/CI.yml)

Dan akan muncul tampilan seperti berikut:

Dalam postingan ini, kita mempelajari cara menambahkan pengujian ke paket Julia kita sendiri. Kami juga mempelajari cara mengaktifkan CI menggunakan GitHub Actions untuk menjalankan pengujian terhadap perubahan kode guna memastikan paket kami masih berfungsi dengan baik.

Seberapa sulitkah saat pertama kali Anda menyiapkan CI? Apakah Anda punya saran untuk pemula? Beri tahu kami di komentar di bawah!

]]>

Terkait