mirror of
https://github.com/apple/pkl.git
synced 2026-01-11 14:20:35 +01:00
98 lines
3.2 KiB
Plaintext
98 lines
3.2 KiB
Plaintext
//===----------------------------------------------------------------------===//
|
|
// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// https://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
/// A template for writing tests.
|
|
///
|
|
/// To write tests, amend this module and define [facts] or [examples] (or both).
|
|
/// To run tests, evaluate the amended module.
|
|
@ModuleInfo { minPklVersion = "0.31.0" }
|
|
open module pkl.test
|
|
|
|
/// Named groups of boolean expressions that are expected to evaluate to [true].
|
|
///
|
|
/// If an expression evaluates to [false], it is reported as a test failure.
|
|
///
|
|
/// Example:
|
|
/// ```
|
|
/// // for brevity, code under test is defined here
|
|
/// function multiply(a, b) = a * b
|
|
///
|
|
/// facts {
|
|
/// ["multiply numbers"] {
|
|
/// multiply(3, 5) == 15
|
|
/// multiple(3, 0) == 1 // will be reported as a test failure
|
|
/// }
|
|
/// // more facts here
|
|
/// }
|
|
/// ```
|
|
facts: Mapping<String, Listing<Boolean>>?
|
|
|
|
/// Named groups of expressions whose results are expected to match results stored in _$filename-expected.pcf_.
|
|
///
|
|
/// If _$filename-expected.pcf_ does not exist, it is generated based on the examples' actual results.
|
|
/// After verifying the contents of this file, it should be added to version control.
|
|
///
|
|
/// If _$filename-expected.pcf_ does exist, its results are compared one-by-one to actual results.
|
|
/// If an actual result does not compare equal (according to `==`) to its expected result,
|
|
/// it is reported as a test failure, and _$filename-actual.pcf_ is generated to aid with debugging.
|
|
///
|
|
/// Example:
|
|
/// ```
|
|
/// // for brevity, code under test is defined here
|
|
/// local function createPigeon(_age) = new {
|
|
/// name = "Pigeon"
|
|
/// age = _age
|
|
/// }
|
|
///
|
|
/// examples {
|
|
/// ["create Pigeons"] {
|
|
/// createPigeon(21)
|
|
/// createPigeon(42)
|
|
/// }
|
|
/// // more examples here
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// When the above code is evaluated for the first time, the following `$filename-expected.pcf` is generated:
|
|
/// ```
|
|
/// examples {
|
|
/// ["create Pigeons"] {
|
|
/// new {
|
|
/// name = "Pigeon"
|
|
/// age = 21
|
|
/// }
|
|
/// new {
|
|
/// name = "Pigeon"
|
|
/// age = 42
|
|
/// }
|
|
/// }
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// To update expected results after making changes,
|
|
/// delete _$filename-expected.pcf_ and evaluate the test module again.
|
|
examples: Mapping<String, Listing<unknown>>?
|
|
|
|
/// Applies [fun] and returns the error thrown.
|
|
///
|
|
/// Throws if [fun] did not throw an error.
|
|
external const function catch(fun: () -> Any): String
|
|
|
|
/// Applies [fun] and returns the error thrown.
|
|
///
|
|
/// Returns [null] if [fun] did not throw an error.
|
|
external const function catchOrNull(fun: () -> Any): String?
|