drone/registry/tests/maven/README.md

Gitness Maven Registry Conformance Tests

This package contains conformance tests for the Maven registry functionality in Gitness, ensuring compliance with Maven repository specifications and validating the correct behavior of the Gitness Maven registry implementation.

Test Suites

1. OCI (Docker) Registry Conformance Tests

These tests validate compliance with the OCI Distribution Specification.

Functionality Tested:

• Content management (push/pull)
• Content discovery
• Cross-repository mounting
• Blob operations
• Tag operations

Test Status: All enabled and functioning

2. Maven Registry Conformance Tests

These tests validate compliance with Maven repository specifications.

Test Categories

The test suite is organized into several categories, each focusing on specific aspects of Maven registry functionality:

Category	Status	Details
Basic Download	✅ Enabled	Artifact download, basic functionality
Basic Upload	✅ Enabled	Simple artifact upload operations
Content Discovery	✅ Enabled	Basic artifact discovery and listing
Error Handling	✅ Enabled	Validation of error responses and edge cases

Enabled Test Details

Basic Download Tests

• should download an artifact: Verifies ability to download previously uploaded JAR files
  • Tests GET operations with proper content type handling
  • Verifies content integrity is maintained

Basic Upload Tests

• should upload an artifact: Validates JAR files can be uploaded to the repository
  • Tests PUT operations with application/java-archive content type
  • Verifies 201 Created status code on successful upload

Content Discovery Tests

• should find artifacts by version: Tests artifact lookup by specific version
  • Ensures properly versioned artifacts can be located
  • Validates correct content is returned
• should find POM files: Tests POM file discovery and retrieval
  • Ensures Maven build descriptors can be located
  • Verifies correct content is returned
• should handle non-existent artifacts: Verifies 404 responses for missing artifacts
  • Tests proper error handling for non-existent files

Error Handling Tests

• should reject invalid artifact path: Verifies proper handling of malformed paths
  • Tests 500 error response with appropriate error message
• should reject invalid version format: Tests validation of Maven version format
  • Ensures non-compliant version strings are rejected with 404
• should reject invalid groupId: Tests validation of groupId format
  • Verifies rejection of path traversal attempts with 404
• should reject unauthorized access: Tests authentication requirements
  • Ensures 401 Unauthorized response with invalid credentials
• should reject access to non-existent space: Tests space/namespace validation
  • Verifies 500 error response when accessing non-existent spaces
• should handle invalid POM XML: Tests POM content validation
  • Verifies rejecting malformed POM files
• should handle mismatched content type: Tests content type validation
  • Ensures content type headers match actual content

Current Status: 12 tests passing, 0 tests skipped, 100% success rate

Running Tests

The Maven conformance tests are integrated into the main Gitness Makefile and can be run in two different modes:

1. Standard Test Mode

This mode starts a new Gitness server instance, runs the tests, and then shuts down the server:

# Run both OCI and Maven conformance tests
make ar-conformance-test

2. Hot Test Mode

This mode runs tests against an already running Gitness server, which is useful for development and debugging:

# Run tests against an already running Gitness server
make ar-hot-conformance-test

3. Running Individual Test Categories

You can run specific test categories using the Go test command with filters:

# Run only download tests
cd registry/tests/maven
go test -v -run "TestMavenConformance/Download"

# Run only upload tests
go test -v -run "TestMavenConformance/Upload"

Configuration

The test environment is automatically set up by the test scripts, with no manual configuration required in most cases.

Automatic Setup

The setup process includes:

• Authentication with the Gitness server using admin credentials
• Creating unique test spaces with timestamp-based names
• Creating Maven registries with proper configuration
• Setting all required environment variables

Environment Variables

The following environment variables can be used to customize the test behavior:

Variable	Description	Default
REGISTRY_ROOT_URL	Base URL of the Gitness server	http://localhost:3000
REGISTRY_USERNAME	Username for authentication	admin@gitness.io
REGISTRY_PASSWORD	Password or token for authentication	Generated automatically
REGISTRY_NAMESPACE	Space/namespace for testing	Generated automatically
REGISTRY_NAME	Registry name for testing	Generated automatically
DEBUG	Enable verbose logging	true

Architecture

Test Framework

The Maven conformance tests are built using the following components:

1. Ginkgo/Gomega: BDD-style test framework for structured and readable tests
2. HTTP Client: Custom HTTP client for Maven registry API interactions
3. Setup Scripts: Bash scripts for environment preparation and cleanup

Directory Structure

registry/tests/maven/
├── 00_conformance_suite_test.go  # Main test suite definition
├── 01_download_test.go          # Download functionality tests
├── 02_upload_test.go            # Upload functionality tests
├── 03_content_discovery_test.go # Content discovery tests
├── 05_error_test.go             # Error handling tests
├── config.go                    # Test configuration and helpers
├── client.go                    # HTTP client implementation
├── reporter.go                  # Test reporting functionality
└── scripts/                     # Helper scripts
    └── setup_test.sh            # Environment setup script

Test Isolation

Each test uses unique artifact names and versions to prevent conflicts between test runs. This is achieved through:

1. Timestamp-based unique identifiers
2. Context-specific naming prefixes
3. BeforeAll setup with Ordered test containers

Extending the Test Suite

Adding New Tests

To add new tests to the Maven conformance suite:

1. Create a new test file following the naming convention: XX_category_test.go
2. Import the necessary packages:

   import (
       "github.com/onsi/ginkgo/v2"
       "github.com/onsi/gomega"
   )
   

3. Define your test function using Ginkgo's BDD style:

   func testNewCategory() {
       ginkgo.Describe("New Category", func() {
           ginkgo.Context("Feature X", ginkgo.Ordered, func() {
               // Define test variables
               var artifactName string
   
               // Setup with BeforeAll
               ginkgo.BeforeAll(func() {
                   // Use unique artifact names
                   artifactName = GetUniqueArtifactName("category", timestamp)
                   // Setup code...
               })
   
               // Define test cases
               ginkgo.It("should do something", func() {
                   // Test code...
                   gomega.Expect(result).To(gomega.Equal(expected))
               })
           })
       })
   }
   

4. Add your test function to the main test suite in 00_conformance_suite_test.go

Best Practices

1. Unique Artifacts: Always use GetUniqueArtifactName() and GetUniqueVersion() to prevent test conflicts
2. Test Isolation: Use ginkgo.Ordered contexts with BeforeAll for setup
3. Error Handling: Test both success and error cases
4. Clean Code: Follow Go best practices and maintain consistent style
5. Documentation: Add clear comments explaining test purpose and expectations

Test Reports

JSON Reports

Test results are saved in maven_conformance_report.json with the following information:

{
  "timestamp": "2025-05-13T14:15:16Z",
  "summary": {
    "passed": 12,
    "failed": 0,
    "pending": 0,
    "skipped": 0,
    "total": 12
  },
  "tests": [
    {
      "name": "Download/should download an artifact",
      "status": "passed",
      "duration": 0.123
    },
    // Additional test results...
  ]
}

JUnit XML Reports

The test suite can also generate JUnit XML reports compatible with CI systems:

# Generate JUnit XML report
cd registry/tests/maven
./generate_junit_report.sh

Troubleshooting

Common Issues

1. Connection Errors

   • Ensure Gitness server is running (for hot tests)
   • Verify server URL is correct in environment variables

2. Authentication Failures

   • Check admin credentials in .local.env
   • Ensure token generation is working properly

3. Registry Not Found

   • Verify registry creation is successful
   • Check namespace/space name formatting

Debugging

Enable verbose logging by setting DEBUG=true in the environment:

DEBUG=true make ar-hot-conformance-test

License

Copyright 2023 Harness, Inc.

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

http://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.