GdUnit4 Action

This GitHub Action automates the execution of GdUnit4 (GDScript) and GdUnit4Net (CSharpScript) unit tests within the Godot Engine 4.x environment. It provides flexibility in configuring the Godot version, GdUnit4 version, test paths, and other parameters to suit your testing needs.

Table of Contents

• Requirements
• Quick Start
• Usage
• Configuration
• Examples
• Troubleshooting
• Performance Optimization
• Contributing
• License
• Security
• FAQ

Requirements

Godot Compatibility

• Godot 4.x (4.0.0 and above)
• Both standard and .NET versions supported
• Tested with stable, RC, and dev builds

For C# Testing

• .NET SDK 7.0 or 8.0
• Godot .NET version

System Requirements

• GitHub Actions runner (Ubuntu latest recommended)
• Git with LFS support for larger projects

Quick Start

Basic GDScript testing:

name: GdUnit4 Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: godot-gdunit-labs/gdUnit4-action@v1
        with:
          godot-version: '4.2.1'
          paths: 'res://tests'

Usage

The action can be configured using various inputs to suit your testing needs. Here's a basic usage pattern:

- uses: godot-gdunit-labs/gdUnit4-action@v1
  with:
    godot-version: '4.2.1'       # Required: Godot version to use
    paths: 'res://tests'         # Required: Test directory
    timeout: 10                  # Optional: Test timeout in minutes
    version: 'latest'            # Optional: GdUnit4 version

Configuration

Essential Parameters

Godot Configuration

.NET Configuration

Test Configuration

Reporting Configuration

Examples

Basic GDScript Testing

- uses: godot-gdunit-labs/gdUnit4-action@v1
  with:
    godot-version: '4.2.1'
    paths: 'res://tests'

Testing with Warnings threaded as Errors

- uses: godot-gdunit-labs/gdUnit4-action@v1
  with:
     godot-version: '4.2.1'
     paths: 'res://tests'
     warnings-as-errors: true  # Fail the build on test warnings

C# Testing with .NET 8.0

- uses: godot-gdunit-labs/gdUnit4-action@v1
  with:
    godot-version: '4.2.1'
    godot-net: true
    paths: 'res://tests'
    console-verbosity: 'normal'  # Optional: increase output detail

Matrix Testing

jobs:
  test:
    strategy:
      matrix:
        godot-version: ['4.1.3', '4.2.1']
        dotnet-version: ['net7.0', 'net8.0']
    steps:
      - uses: godot-gdunit-labs/gdUnit4-action@v1
        with:
          godot-version: ${{ matrix.godot-version }}
          godot-net: true
          dotnet-version: ${{ matrix.dotnet-version }}
          paths: 'res://tests'

Testing with Retries and Custom Arguments

- uses: godot-gdunit-labs/gdUnit4-action@v1
  with:
    godot-version: '4.2.1'
    paths: 'res://tests'
    retries: 3
    arguments: '--verbose --fail-fast'

Custom Project Structure

For projects with non-standard layout:

root/
  ├── MyProject/
  │   ├── src/
  │   └── tests/

- uses: godot-gdunit-labs/gdUnit4-action@v1
  with:
    godot-version: '4.2.1'
    project_dir: './MyProject/'
    paths: 'res://tests'

Troubleshooting

Common Issues

1. Test Discovery Failures

   • Ensure test paths are correct and use res:// prefix
   • Check file permissions on test directories

2. C# Test Issues

   • Verify correct .NET SDK version
   • Check Godot .NET compatibility
   • Ensure proper project structure

3. Timeout Issues

   • Increase timeout value for large test suites
   • Consider splitting tests across multiple jobs

Debug Logging

For GDScript tests, enable verbose output by adding --verbose to the arguments:

arguments: '--verbose'

For C# tests, control console output verbosity with console-verbosity (default: minimal):

godot-net: true
console-verbosity: 'normal'    # Options: quiet, minimal, normal, detailed, diagnostic
arguments: '--verbose'          # For Godot engine debug output

Performance Optimization

Caching

The action automatically caches:

• Godot binaries
• .NET packages
• Project cache

Best Practices

1. Use specific versions instead of 'latest'
2. Optimize test discovery paths
3. Implement parallel test execution where possible
4. Use appropriate timeout values

Security

Fork Considerations

When running tests from forked repositories:

1. Set publish-report: false to avoid permission issues
2. Use custom report-name for artifact identification
3. Be cautious with sensitive test data

FAQ

Q: Which Godot versions are supported?

A: All Godot 4.x versions are supported, including stable, RC, and dev builds.

Q: Can I test both GDScript and C# in the same workflow?

A: Yes, use separate jobs or matrix testing with different configurations.

Q: How do I handle flaky tests?

A: Use the retries parameter to automatically retry failed tests.

Q: How do I handle test warnings?

A: By default, warnings will be reported but won't fail the build. Use warnings-as-errors: true to treat warnings as failures.

Related Projects

• GdUnit4
• Godot Engine

Contributing

We welcome contributions! Please see our contribution guidelines for details.

You're Welcome To

• Give Feedback
• Suggest Improvements
• Report Bugs
• Join our Discord Server

License

This project is released under the MIT License.

Contributors