copier-template-tester 2.3.0rc0
Test copier templates
Requires Python: >=3.10.11
Keywords: calcipy_template

# copier-template-tester

![./ctt-logo.png](./ctt-logo.png)

Parametrize copier templates to test for syntax errors, check the expected output, and to check against copier versions.

Note that `ctt` only tests the `copier copy` operation and doesn't check the `update` behavior and any version-specific logic that your template may contain because of how quickly those tests become complex.

## Usage

### Configuration File

When creating a copier template repository, I recommend following the nested ["subdirectory" approach](https://copier.readthedocs.io/en/latest/configuring/#subdirectory) so that the directory looks like this:

```sh
└── template_dir
│   └── {{ _copier_conf.answers_file }}.jinja
├── README.md
├── copier.yml
└── ctt.toml
```

Create a new `ctt.toml` file in the top-level directory of your copier repository. Populate the file to look like the below example.

```toml
# Specify shared data across all 'output' destinations
# Note that the copier.yml defaults are used whenever the key is not set in this file
[defaults]
project_name = "placeholder"
copyright_year = 2022

# Parametrize each output with a relative path and optionally any values to override
[output.".ctt/defaults"]

[output.".ctt/no_all"]
package_name = "testing-no-all"
include_all = false
```

#### Post tasks

Use `_post_tasks` to run tasks after the template's tasks:

```toml
[defaults]
_post_tasks = [
  "pre-commit run --all-files",
]

[output.".ctt/also-run-pytest-here"]
_post_tasks = [
  "uv run pytest",
]
```

*Note*: `_extra_tasks` is also supported, but `_post_tasks` is preferred for consistency with `_pre_tasks` and `_skip_tasks`

#### Skip template tasks

Use `_skip_tasks = true` to skip tasks defined in the template's `copier.yaml`:

```toml
[output.".ctt/fast-test"]
_skip_tasks = true
_post_tasks = ["pytest"] # only this runs
```

#### Pre tasks

Use `_pre_tasks` to run tasks before the template's tasks:

```toml
[output.".ctt/with-validation"]
_pre_tasks = ["./validate-env.sh"]
```

### Pre-Commit Hook

First, add this section to your `.pre-commit-config.yml` file:

```yaml
repos:
  - repo: https://github.com/KyleKing/copier-template-tester
    rev: main
    hooks:
      - id: copier-template-tester
```

Install and update to the latest revision:

```sh
pre-commit autoupdate
```

The run with `pre-commit`:

```sh
pre-commit run --all-files copier-template-tester
```

### pipx

You can also try `ctt` as a CLI tool by installing with `pipx`:

```sh
pipx install copier-template-tester

cd ~/your/copier/project
ctt
```

### More Examples

For more example code, see the [scripts] directory or the [tests].

## Project Status

See the `Open Issues` and/or the [CODE_TAG_SUMMARY]. For release history, see the [CHANGELOG].

## Contributing

We welcome pull requests! For your pull request to be accepted smoothly, we suggest that you first open a GitHub issue to discuss your idea. For resources on getting started with the code base, see the below documentation:

- [DEVELOPER_GUIDE]
- [STYLE_GUIDE]

## Code of Conduct

We follow the [Contributor Covenant Code of Conduct][contributor-covenant].

### Open Source Status

We try to reasonably meet most aspects of the "OpenSSF scorecard" from [Open Source Insights](https://deps.dev/pypi/copier-template-tester)

## Responsible Disclosure

If you have any security issue to report, please contact the project maintainers privately. You can reach us at [dev.act.kyle@gmail.com](mailto:dev.act.kyle@gmail.com).

## License

[LICENSE]

[changelog]: https://copier-template-tester.kyleking.me/docs/CHANGELOG
[code_tag_summary]: https://copier-template-tester.kyleking.me/docs/CODE_TAG_SUMMARY
[contributor-covenant]: https://www.contributor-covenant.org
[developer_guide]: https://copier-template-tester.kyleking.me/docs/DEVELOPER_GUIDE
[license]: https://github.com/kyleking/copier-template-tester/blob/main/LICENSE
[scripts]: https://github.com/kyleking/copier-template-tester/blob/main/scripts
[style_guide]: https://copier-template-tester.kyleking.me/docs/STYLE_GUIDE
[tests]: https://github.com/kyleking/copier-template-tester/blob/main/tests