{"id":18981406,"url":"https://github.com/awncorp/test-auto","last_synced_at":"2025-11-10T18:02:37.395Z","repository":{"id":77256575,"uuid":"210717061","full_name":"awncorp/test-auto","owner":"awncorp","description":"Test Automation, Docs Generation","archived":false,"fork":false,"pushed_at":"2020-06-06T22:08:07.000Z","size":209,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-01T11:27:31.388Z","etag":null,"topics":["automation","documentation","framework","perl","perl5","testing"],"latest_commit_sha":null,"homepage":"http://metacpan.org/release/Test-Auto/","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awncorp.png","metadata":{"files":{"readme":"README","changelog":"CHANGES","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-24T23:47:23.000Z","updated_at":"2022-07-24T21:01:42.000Z","dependencies_parsed_at":"2023-02-27T09:31:16.688Z","dependency_job_id":null,"html_url":"https://github.com/awncorp/test-auto","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awncorp%2Ftest-auto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awncorp%2Ftest-auto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awncorp%2Ftest-auto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awncorp%2Ftest-auto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awncorp","download_url":"https://codeload.github.com/awncorp/test-auto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239985746,"owners_count":19729519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","documentation","framework","perl","perl5","testing"],"created_at":"2024-11-08T16:09:45.756Z","updated_at":"2025-11-10T18:02:32.360Z","avatar_url":"https://github.com/awncorp.png","language":"Perl","readme":"NAME\n\n    Test::Auto - Test Automation\n\nABSTRACT\n\n    Test Automation, Docs Generation\n\nSYNOPSIS\n\n      #!/usr/bin/env perl\n    \n      use Test::Auto;\n      use Test::More;\n    \n      my $test = Test::Auto-\u003enew(\n        't/Test_Auto.t'\n      );\n    \n      # automation\n    \n      # my $subtests = $test-\u003esubtests-\u003estandard;\n    \n      # ...\n    \n      # done_testing;\n\nDESCRIPTION\n\n    This package aims to provide, a standard for documenting Perl 5\n    software projects, a framework writing tests, test automation, and\n    documentation generation.\n\nREASONING\n\n    This framework lets you write documentation in test files using\n    pod-like comment blocks. By using a particular set of comment blocks\n    (the specification) this framework can run certain kinds of tests\n    automatically. For example, we can automatically ensure that the\n    package the test is associated with is loadable, that the test file\n    comment blocks meet the specification, that any super-classes or\n    libraries are loadable, and that the functions, methods, and routines\n    are properly documented.\n\nLIBRARIES\n\n    This package uses type constraints from:\n\n    Test::Auto::Types\n\nSCENARIOS\n\n    This package supports the following scenarios:\n\n exports\n\n      use Test::Auto;\n      use Test::More;\n    \n      my $subtests = testauto 't/Test_Auto.t';\n    \n      # automation\n    \n      # $subtests-\u003estandard;\n    \n      # ...\n    \n      # done_testing;\n\n    This package automatically exports the testauto function which uses the\n    \"current file\" as the automated testing source.\n\nATTRIBUTES\n\n    This package has the following attributes:\n\n data\n\n      data(Data)\n\n    This attribute is read-only, accepts (Data) values, and is optional.\n\n file\n\n      file(Str)\n\n    This attribute is read-only, accepts (Str) values, and is required.\n\nFUNCTIONS\n\n    This package implements the following functions:\n\n testauto\n\n      testauto(Str $file) : Subtests\n\n    This function is exported automatically and returns a\n    Test::Auto::Subtests object for the test file given.\n\n    testauto example #1\n\n        # given: synopsis\n      \n        my $subtests = testauto 't/Test_Auto.t';\n\nMETHODS\n\n    This package implements the following methods:\n\n document\n\n      document() : Document\n\n    This method returns a Test::Auto::Document object.\n\n    document example #1\n\n        # given: synopsis\n      \n        my $document = $test-\u003edocument;\n\n parser\n\n      parser() : Parser\n\n    This method returns a Test::Auto::Parser object.\n\n    parser example #1\n\n        # given: synopsis\n      \n        my $parser = $test-\u003eparser;\n\n subtests\n\n      subtests() : Subtests\n\n    This method returns a Test::Auto::Subtests object.\n\n    subtests example #1\n\n        # given: synopsis\n      \n        my $subtests = $test-\u003esubtests;\n\nSPECIFICATION\n\n      # [required]\n    \n      =name\n      =abstract\n      =tagline\n      =includes\n      =synopsis\n      =description\n    \n      # [optional]\n    \n      =libraries\n      =inherits\n      =integrates\n      =attributes\n    \n      # [repeatable; optional]\n    \n      =scenario $name\n      =example $name\n    \n      # [repeatable; optional]\n    \n      =method $name\n      =signature $name\n      =example-$number $name # [repeatable]\n    \n      # [repeatable; optional]\n    \n      =function $name\n      =signature $name\n      =example-$number $name # [repeatable]\n    \n      # [repeatable; optional]\n    \n      =routine $name\n      =signature $name\n      =example-$number $name # [repeatable]\n    \n      # [repeatable; optional]\n    \n      =type $name\n      =type-library $name\n      =type-composite $name # [optional]\n      =type-parent $name # [optional]\n      =type-coercion-$number $name # [optional]\n      =type-example-$number $name # [repeatable]\n\n    The specification is designed to accommodate typical package\n    declarations. It is used by the parser to provide the content used in\n    the test automation and document generation. Note: when code blocks are\n    evaluated \"redefined\" warnings are now automatically disabled.\n\n name\n\n      =name\n    \n      Path::Find\n    \n      =cut\n\n    The name block should contain the package name. This is tested for\n    loadability.\n\n tagline\n\n      =tagline\n    \n      Path Finder\n    \n      =cut\n\n    The tagline block should contain a tagline for the package. This is\n    optional but if present is concatenated with the name during POD\n    generation.\n\n abstract\n\n      =abstract\n    \n      Find Paths using Heuristics\n    \n      =cut\n\n    The abstract block should contain a subtitle describing the package.\n    This is tested for existence.\n\n includes\n\n      =includes\n    \n      function: path\n      method: children\n      method: siblings\n      method: new\n    \n      =cut\n\n    The includes block should contain a list of function, method, and/or\n    routine names in the format of $type: $name. Empty lines are ignored.\n    This is tested for existence. Each function, method, and/or routine is\n    tested to be documented properly. Also, the package must recognize that\n    each exists.\n\n synopsis\n\n      =synopsis\n    \n      use Path::Find 'path';\n    \n      my $path = path; # get path using cwd\n    \n      =cut\n\n    The synopsis block should contain the normative usage of the package.\n    This is tested for existence. This block should be written in a way\n    that allows it to be evaled successfully and should return a value.\n\n description\n\n      =description\n    \n      interdum posuere lorem ipsum dolor sit amet consectetur adipiscing elit duis\n      tristique sollicitudin nibh sit amet\n    \n      =cut\n\n    The description block should contain a thorough explanation of the\n    purpose of the package. This is tested for existence.\n\n libraries\n\n      =libraries\n    \n      Types::Standard\n      Types::TypeTiny\n    \n      =cut\n\n    The libraries block should contain a list of packages, each of which is\n    itself a Type::Library. These packages are tested for loadability, and\n    to ensure they are type library classes.\n\n inherits\n\n      =inherits\n    \n      Path::Tiny\n    \n      =cut\n\n    The inherits block should contain a list of parent packages. These\n    packages are tested for loadability.\n\n integrates\n\n      =integrates\n    \n      Path::Find::Upable\n      Path::Find::Downable\n    \n      =cut\n\n    The integrates block should contain a list of packages that are\n    involved in the behavior of the main package. These packages are not\n    automatically tested.\n\n scenarios\n\n      =scenario export-path-make\n    \n      quisque egestas diam in arcu cursus euismod quis viverra nibh\n    \n      =example export-path-make\n    \n      # given: synopsis\n    \n      package main;\n    \n      use Path::Find 'path_make';\n    \n      path_make 'relpath/to/file';\n    \n      =cut\n\n    There are situation where a package can be configured in different\n    ways, especially where it exists without functions, methods or routines\n    for the purpose of configuring the environment. The scenario directive\n    can be used to automate testing and documenting package usages and\n    configurations.Describing a scenario requires two blocks, i.e. scenario\n    $name and example $name. The scenario block should contain a\n    description of the scenario and its purpose. The example block must\n    exist when documenting a method and should contain valid Perl code and\n    return a value. The block may contain a \"magic\" comment in the form of\n    given: synopsis or given: example $name which if present will include\n    the given code example(s) with the evaluation of the current block.\n    Each scenario is tested and must be recognized to exist by the main\n    package.\n\n attributes\n\n      =attributes\n    \n      cwd: ro, req, Object\n    \n      =cut\n\n    The attributes block should contain a list of package attributes in the\n    form of $name: $is, $presence, $type, where $is should be ro\n    (read-only) or rw (read-wire), and $presence should be req (required)\n    or opt (optional), and $type can be any valid Type::Tiny expression.\n    Each attribute declaration must be recognized to exist by the main\n    package and have a type which is recognized by one of the declared type\n    libraries.\n\n methods\n\n      =method children\n    \n      quis viverra nibh cras pulvinar mattis nunc sed blandit libero volutpat\n    \n      =signature children\n    \n      children() : [Object]\n    \n      =example-1 children\n    \n      # given: synopsis\n    \n      my $children = $path-\u003echildren;\n    \n      =example-2 children\n    \n      # given: synopsis\n    \n      my $filtered = $path-\u003echildren(qr/lib/);\n    \n      =cut\n\n    Describing a method requires at least three blocks, i.e. method $name,\n    signature $name, and example-1 $name. The method block should contain a\n    description of the method and its purpose. The signature block should\n    contain a method signature in the form of $signature : $return_type,\n    where $signature is a valid typed signature and $return_type is any\n    valid Type::Tiny expression. The example-$number block is a repeatable\n    block, and at least one block must exist when documenting a method. The\n    example-$number block should contain valid Perl code and return a\n    value. The block may contain a \"magic\" comment in the form of given:\n    synopsis or given: example-$number $name which if present will include\n    the given code example(s) with the evaluation of the current block.\n    Each method is tested and must be recognized to exist by the main\n    package.\n\n functions\n\n      =function path\n    \n      lectus quam id leo in vitae turpis massa sed elementum tempus egestas\n    \n      =signature children\n    \n      path() : Object\n    \n      =example-1 path\n    \n      package Test::Path::Find;\n    \n      use Path::Find;\n    \n      my $path = path;\n    \n      =cut\n\n    Describing a function requires at least three blocks, i.e. function\n    $name, signature $name, and example-1 $name. The function block should\n    contain a description of the function and its purpose. The signature\n    block should contain a function signature in the form of $signature :\n    $return_type, where $signature is a valid typed signature and\n    $return_type is any valid Type::Tiny expression. The example-$number\n    block is a repeatable block, and at least one block must exist when\n    documenting a function. The example-$number block should contain valid\n    Perl code and return a value. The block may contain a \"magic\" comment\n    in the form of given: synopsis or given: example-$number $name which if\n    present will include the given code example(s) with the evaluation of\n    the current block. Each function is tested and must be recognized to\n    exist by the main package.\n\n routines\n\n      =routine algorithms\n    \n      sed sed risus pretium quam vulputate dignissim suspendisse in est ante\n    \n      =signature algorithms\n    \n      algorithms() : Object\n    \n      =example-1 algorithms\n    \n      # given: synopsis\n    \n      $path-\u003ealgorithms\n    \n      =example-2 algorithms\n    \n      package Test::Path::Find;\n    \n      use Path::Find;\n    \n      Path::Find-\u003ealgorithms;\n    \n      =cut\n\n    Typically, a Perl subroutine is declared as a function or a method.\n    Rarely, but sometimes necessary, you will need to describe a subroutine\n    where the invocant is either a class or class instance. Describing a\n    routine requires at least three blocks, i.e. routine $name, signature\n    $name, and example-1 $name. The routine block should contain a\n    description of the routine and its purpose. The signature block should\n    contain a routine signature in the form of $signature : $return_type,\n    where $signature is a valid typed signature and $return_type is any\n    valid Type::Tiny expression. The example-$number block is a repeatable\n    block, and at least one block must exist when documenting a routine.\n    The example-$number block should contain valid Perl code and return a\n    value. The block may contain a \"magic\" comment in the form of given:\n    synopsis or given: example-$number $name which if present will include\n    the given code example(s) with the evaluation of the current block.\n    Each routine is tested and must be recognized to exist by the main\n    package.\n\n types\n\n      =type Path\n    \n        Path\n    \n      =type-parent Path\n    \n        Object\n    \n      =type-library Path\n    \n      Path::Types\n    \n      =type-composite Path\n    \n        InstanceOf[\"Path::Find\"]\n    \n      =type-coercion-1 Path\n    \n        # can coerce from Str\n    \n        './path/to/file'\n    \n      =type-example-1 Path\n    \n        require Path::Find;\n    \n        Path::Find::path('./path/to/file')\n    \n      =cut\n\n    When developing Perl programs, or type libraries, that use Type::Tiny\n    based type constraints, testing and documenting custom type constraints\n    is often overlooked. Describing a custom type constraint requires at\n    least two blocks, i.e. type $name and type-library $name. While it's\n    not strictly required, it's a good idea to also include at least one\n    type-example-1 $name. The optional type-parent block should contain the\n    name of the parent type. The type-composite block should contain a type\n    expression that represents the derived type. The type-coercion-$number\n    block is a repeatable block which is used to validate type coercion.\n    The type-coercion-$number block should contain valid Perl code and\n    return the value to be coerced. The type-example-$number block is a\n    repeatable block, and it's a good idea to have at least one block must\n    exist when documenting a type. The type-example-$number block should\n    contain valid Perl code and return a value. Each type is tested and\n    must be recognized to exist within the package specified by the\n    type-library block.\n\nAUTOMATION\n\n      $test-\u003estandard;\n\n    This is the equivalent of writing:\n\n      $test-\u003epackage;\n      $test-\u003edocument;\n      $test-\u003elibraries;\n      $test-\u003einherits;\n      $test-\u003eattributes;\n      $test-\u003emethods;\n      $test-\u003eroutines;\n      $test-\u003efunctions;\n      $test-\u003etypes;\n\n    This framework provides a set of automated subtests based on the\n    package specification, but not everything can be automated so it also\n    provides you with powerful hooks into the framework for manual testing.\n\n      my $subtests = $test-\u003esubtests;\n    \n      $subtests-\u003esynopsis(sub {\n        my ($tryable) = @_;\n    \n        ok my $result = $tryable-\u003eresult, 'result ok';\n    \n        $result; # for automated testing after the callback\n      });\n\n    The code examples documented can be automatically evaluated (evaled)\n    and returned using a callback you provide for further testing. Because\n    the code examples are returned as Test::Auto::Try objects (see\n    Data::Object::Try), this makes capturing and testing exceptions simple,\n    for example:\n\n      my $subtests = $test-\u003esubtests;\n    \n      $subtests-\u003esynopsis(sub {\n        my ($tryable) = @_;\n    \n        # catch exception thrown by the synopsis\n        $tryable-\u003ecatch('Path::Find::Error', sub {\n          return $_[0];\n        });\n        # test the exception\n        ok my $result = $tryable-\u003eresult, 'result ok';\n        ok $result-\u003eisa('Path::Find::Error'), 'exception caught';\n    \n        $result;\n      });\n\n    Additionally, another manual testing hook (with some automation) is the\n    example method. This hook evaluates (evals) a given example and returns\n    the result as a Test::Auto::Try object (see Data::Object::Try). The\n    first argument is the example ID (or number), for example:\n\n      my $subtests = $test-\u003esubtests;\n    \n      $subtests-\u003eexample(-1, 'children', 'method', sub {\n        my ($tryable) = @_;\n    \n        ok my $result = $tryable-\u003eresult, 'result ok';\n    \n        $result; # for automated testing after the callback\n      });\n\n    Finally, the lesser-used but useful manual testing hook is the scenario\n    method. This hook evaluates (evals) a documented scenario and returns\n    the result as a Test::Auto::Try object (see Data::Object::Try), for\n    example:\n\n      my $subtests = $test-\u003esubtests;\n    \n      $subtests-\u003escenario('export-path-make', sub {\n        my ($tryable) = @_;\n    \n        ok my $result = $tryable-\u003eresult, 'result ok';\n    \n        $result; # for automated testing after the callback\n      });\n\n    The test automation and document generation enabled through this\n    framework makes it easy to maintain source/test/documentation parity.\n    This also increases reusability and reduces the need for complicated\n    state and test setup.\n\nAUTHOR\n\n    Al Newkirk, awncorp@cpan.org\n\nLICENSE\n\n    Copyright (C) 2011-2019, Al Newkirk, et al.\n\n    This is free software; you can redistribute it and/or modify it under\n    the terms of the The Apache License, Version 2.0, as elucidated in the\n    \"license file\"\n    \u003chttps://github.com/iamalnewkirk/test-auto/blob/master/LICENSE\u003e.\n\nPROJECT\n\n    Wiki \u003chttps://github.com/iamalnewkirk/test-auto/wiki\u003e\n\n    Project \u003chttps://github.com/iamalnewkirk/test-auto\u003e\n\n    Initiatives \u003chttps://github.com/iamalnewkirk/test-auto/projects\u003e\n\n    Milestones \u003chttps://github.com/iamalnewkirk/test-auto/milestones\u003e\n\n    Issues \u003chttps://github.com/iamalnewkirk/test-auto/issues\u003e\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawncorp%2Ftest-auto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawncorp%2Ftest-auto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawncorp%2Ftest-auto/lists"}