chore(tests): Update acceptance tests to PVE 8.1, add docs (#834)

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>

.vscode/extensions.json

@@ -1,7 +1,8 @@
 {
     "recommendations": [
         "davidanson.vscode-markdownlint",
-        "joshbolduc.commitlint",
+        "golang.go",
         "hashicorp.terraform",
+        "joshbolduc.commitlint",
     ]
 }

.vscode/launch.json

@@ -1,6 +1,16 @@
 {
     "version": "0.2.0",
     "configurations": [      
+        {
+            "name": "Debug Acceptance Tests",
+            "type": "go",
+            "request": "launch",
+            "mode": "test",
+            "program": "${workspaceFolder}/fwprovider/tests",
+            "envFile": "${workspaceFolder}/testacc.env",
+            "args": ["-test.v", "-test.timeout", "30s"]
+            
+        },
         {
             "name": "Debug Provider",
             "type": "go",

CONTRIBUTING.md

@@ -47,6 +47,27 @@ existing ones in order to target your changes.
 
 You can run all the test cases by invoking `make test`.
 
+### Acceptance tests
+
+The project has a limited set of acceptance tests which are run against a real Proxmox
+instance. These tests are developed alongside the framework-based resource and datasource implementations, and are located in the `fwprovider/tests` directory.
+
+To run the acceptance tests, you need to have a Proxmox instance available. See more details in the [Setup Proxmox for Tests](./howtos/setup-proxmox-for-tests/README.md) section.
+Create a `testacc.env` file in the project's root directory with the following contents:
+
+```env
+TF_ACC=1
+PROXMOX_VE_API_TOKEN="root@pam!<token name>=<token value>"
+PROXMOX_VE_ENDPOINT="https://<pve instance>:8006/"
+PROXMOX_VE_SSH_AGENT="true"
+PROXMOX_VE_SSH_USERNAME="root"
+```
+
+Then use `make testacc` to run the acceptance tests.
+
+> [!NOTE]
+> The acceptance tests support is still in development. Only handful of resources and data sources are covered by the tests. Some tests may require extra configuration on the Proxmox instance, and fail if the configuration is not present.
+
 ## Manual Testing
 
 You can manually test the provider by running it locally. This is useful for
@@ -72,7 +93,6 @@ testing changes to the provider before submitting a PR.
 
   ```bash
   go install .
-
   ```
 
 - Run `terraform init` in a directory containing a Terraform configuration
@@ -106,11 +126,12 @@ testing changes to the provider before submitting a PR.
 
 ## Coding conventions
 
-We expect that all code contributions have been formatted using `gofmt`. You can
-run `make fmt` to format your code.
+We expect that all code contributions have been formatted using `gofmt`.
+
+You can run `make fmt` to format your code.
+
+We also expect that all code contributions have been linted using `golangci-lint`.
 
-We also expect that all code contributions have been linted
-using `golangci-lint`.
 You can run `make lint` to lint your code.
 
 ## Commit message conventions

Makefile

@@ -87,11 +87,8 @@ test:
 
 .PHONY: testacc
 testacc:
-    # env vars required for acceptance tests
-    #   - PROXMOX_VE_ENDPOINT
-    #   - PROXMOX_VE_USERNAME
-    #   - PROXMOX_VE_PASSWORD
-	TF_ACC=1 go test ./...
+	@# explicitly add TF_ACC=1 to trigger the acceptance tests, `testacc.env` might be missing or incomplete  
+	@TF_ACC=1 env $$(cat testacc.env | xargs) go test ./...
 
 .PHONY: lint
 lint:

fwprovider/tests/datasource_version_test.go

@@ -29,13 +29,13 @@ func TestAccDatasourceVersion(t *testing.T) {
 			{
 				Config: `data "proxmox_virtual_environment_version" "test" {}`,
 				Check: resource.ComposeAggregateTestCheckFunc(
-					resource.TestCheckResourceAttr(datasourceName, "release", "8.0"),
+					resource.TestCheckResourceAttr(datasourceName, "release", "8.1"),
 					resource.TestCheckResourceAttrSet(datasourceName, "repository_id"),
 					resource.TestCheckResourceAttrWith(datasourceName, "version", func(value string) error {
-						if strings.HasPrefix(value, "8.0") {
+						if strings.HasPrefix(value, "8.1") {
 							return nil
 						}
-						return fmt.Errorf("version %s does not start with 8.0", value)
+						return fmt.Errorf("version %s does not start with 8.1", value)
 					}),
 					resource.TestCheckResourceAttrSet(datasourceName, "id"),
 				),

fwprovider/tests/resource_container_test.go

@@ -74,6 +74,7 @@ resource "proxmox_virtual_environment_container" "test_container" {
   }
 
   operating_system {
+	# TODO: this file needs to be upload to PVE first
     template_file_id = "local:vztmpl/ubuntu-23.04-standard_23.04-1_amd64.tar.zst"
     type             = "ubuntu"
   }

fwprovider/tests/resource_file_test.go

@@ -124,7 +124,7 @@ func uploadSnippetFile(t *testing.T, file *os.File) {
 	u, err := url.ParseRequestURI(endpoint)
 	require.NoError(t, err)
 
-	sshUsername := strings.Split(utils.GetAnyStringEnv("PROXMOX_VE_USERNAME"), "@")[0]
+	sshUsername := utils.GetAnyStringEnv("PROXMOX_VE_SSH_USERNAME")
 	sshAgentSocket := utils.GetAnyStringEnv("SSH_AUTH_SOCK", "PROXMOX_VE_SSH_AUTH_SOCK", "PM_VE_SSH_AUTH_SOCK")
 
 	sshClient, err := ssh.NewClient(

fwprovider/tests/resource_linux_vlan_test.go

@@ -25,7 +25,7 @@ func TestAccResourceLinuxVLAN(t *testing.T) {
 
 	accProviders := testAccMuxProviders(context.Background(), t)
 
-	iface := "enp6s18"
+	iface := "ens18"
 	vlan1 := gofakeit.Number(10, 4094)
 	customName := fmt.Sprintf("iface_%s", gofakeit.Word())
 	vlan2 := gofakeit.Number(10, 4094)

howtos/README.md

@@ -4,9 +4,9 @@ A collection of HOW-TOs for common tasks.
 
 ## Virtual Machines
 
-- [Create a VM from a Cloud Image](howtos/cloud-image/README.md)
-- [Configure a VM with Cloud-Init](howtos/cloud-init/README.md)
+- [Create a VM from a Cloud Image](./cloud-image/README.md)
+- [Configure a VM with Cloud-Init](./cloud-init/README.md)
 
 ## Contributors
 
-- [Setup VM with proxmox to run make example](howtos/setup-proxmox-for-make-example/README.md)
+- [Setup VM with proxmox to run examples and acceptance tests](./setup-proxmox-for-tests/README.md)

howtos/setup-proxmox-for-tests/README.md

@@ -1,4 +1,4 @@
-# Setup VM with proxmox to run make example
+# Setup VM with proxmox to run examples and acceptance tests
 
 ## Who
 
@@ -16,11 +16,11 @@ Be sure to install `go` and `terraform` on your system first.
 
 ## Linux (Debian/Ubuntu) with virt-manager
 
-Goal is to have a proxmox node in VM using https://virt-manager.org/ for a job. This text assumes some linux knowledge. Tested on Debian 12 bookworm and proxmox VE 8.1. For other distros, with any luck steps should be similar.
+Goal is to have a proxmox node in VM using <https://virt-manager.org/> for a job. This text assumes some linux knowledge. Tested on Debian 12 bookworm and proxmox VE 8.1. For other distros, with any luck steps should be similar.
 
 1. `sudo apt-get install virt-manager`.
 
-2. Download some proxmox image from http://download.proxmox.com/iso/, currently latest is `proxmox-ve_8.1-1.iso`.
+2. Download some proxmox image from <http://download.proxmox.com/iso/>, currently latest is `proxmox-ve_8.1-1.iso`.
 
 3. Run `virt-manager` and "create a new virtual machine", use a file you just downloaded, choose debian as a operating system, leave default network settings.
 
@@ -32,7 +32,7 @@ Goal is to have a proxmox node in VM using https://virt-manager.org/ for a job.
 
    It may look like this:
 
-   ```
+   ```txt
    root@proxmox:~# ip a
    1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
        link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
@@ -52,7 +52,7 @@ Goal is to have a proxmox node in VM using https://virt-manager.org/ for a job.
 
 7. (Optional) On **your** computer, there should be new interface created mapped to that one you see on proxmox. Again `ip a`:
 
-   ```
+   ```txt
    ...
 
    8: virbr0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
@@ -70,11 +70,11 @@ Goal is to have a proxmox node in VM using https://virt-manager.org/ for a job.
    ssh root@192.168.122.43
    ```
 
-   You can also use browser and visit console at https://192.168.122.43:8006.
+   You can also use browser and visit console at <https://192.168.122.43:8006>.
 
 9. Create `terraform.tfvars` file (it will be git ignored file) in `example` folder with credentials for you new proxmox node.
 
-   ```
+   ```txt
    # example/terraform.tfvars
    virtual_environment_username = "root@pam"
    virtual_environment_endpoint = "https://192.168.122.43:8006/"
@@ -84,4 +84,4 @@ Goal is to have a proxmox node in VM using https://virt-manager.org/ for a job.
 
 10. Now you can run `make example`.
 
-11. If you see error with proxmox_virtual_environment_file: the datastore "local" does not support content type "snippets"; supported content types are: [backup iso vztmpl], you need to enable them, see https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_file#snippets.
+11. If you see error with proxmox_virtual_environment_file: the datastore "local" does not support content type "snippets"; supported content types are: [backup iso vztmpl], you need to enable them, see <https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_file#snippets>.

proxmox/ssh/client.go

@@ -294,9 +294,9 @@ func (c *client) openNodeShell(ctx context.Context, node ProxmoxNode) (*ssh.Clie
 	sshClient, err = ssh.Dial("tcp", sshHost, sshConfig)
 	if err != nil {
 		if c.password == "" {
-			return nil, fmt.Errorf("unable to authenticate over SSH to %s. Please verify that ssh-agent is "+
+			return nil, fmt.Errorf("unable to authenticate user %q over SSH to %q. Please verify that ssh-agent is "+
 				"correctly loaded with an authorized key via 'ssh-add -L' (NOTE: configurations in ~/.ssh/config are "+
-				"not considered by golang's ssh implementation). The exact error from ssh.Dial: %w", sshHost, err)
+				"not considered by golang's ssh implementation). The exact error from ssh.Dial: %w", c.username, sshHost, err)
 		}
 
 		return nil, fmt.Errorf("failed to dial %s: %w", sshHost, err)