Make link checker work locally; make it a test

[coke]

We currently have a file called "links.txt" that is generated and then pushed out to the live site.

There is also util/test-links.sh which goes out to the site, grabs the links file, then verifies each of the links against the live file.

We should be able to verify all the internal links either against the generated HTML on disk, or against a locally running copy of the site; either way, this should probably be an xt/ test, rather than a one off script.

[AlexDaniel]

Related issue: #561

[JJ]

If we make it a test, we will have to first fix all broken links, as said in #561. Would converting util/test-links.sh to a test just work?

[coke]

No because that test is going against the live website we would need to update it so that it goes against the local running copy

[JJ]

Modify it or create a new and different version that starts up a local copy and checks links?

[coke]

Yes.

[coke]

In the past, when converting things to tests that were not 100%, we've builtin skips/todos in the test for known issues, then slowly chipped away at the list until it's clear; any new things are expected to pass, this lets us get the advantage of the test without having to fix everything immediately.

[JJ]

We do have now a test for links. Maybe we could extend it to actually check those links...

[coke]

Not the same kind of links. Your test is checking that mentions of things that look like URLs are in a pod link.

This ask is for every link tag on the site, regardess of what the source of that link looks like.

[JJ]

Related #935 #1542 #1925 #2328 #1838 (some of them might be linked already)

[JJ]

As a matter of fact, we can simply use the generated HTML source to check local links.

[finanalyst]

I have done quite a lot of work on links recently. Several types of links:

1. In primary files (under Language|Type|Programs) of the type L<.+ |https://...> - external.
2. In primary files of the type L<...|somereference> - which points to a local file.
3. In primary files of the type L<...|/routine/somereference> - points to a generated file.
4. In the generated html files of the type <a href
   The first type are tested by Pod::To::HTML. I also have tests for them. In general they are all working.

For types 2 & 3, I can write a test, but it needs to be run after the html files have all been generated because we cannot determine in advance whether they will be generated (I have found errors).

For type 3. I can write a test that looks at each html file, extract every <a href="..."> then use eg. curl to test whether the link works.

Have I missed anything?

[JJ]

My main concern is 3. 2... I don't quite like them. They are assuming something will stay in the same directory. And 3... Well, testing that their target exists is a good step, and testing HTML directly is a good patch. But it would be much better to factor out link-generation logic from htmlify.p6 and use _that_ to check them. I am trying right now to check what's happened to the link to use for #2568, and I'm down a rabbit hole... My hunch now is that it was simply set out of thin air, but I did it and, well, I don't do (usually) do that kind of things.

[finanalyst]

In reply to Coke's original Issue.

I have done some research and the results are on a new page in the wiki called Actual Tests.

Regarding all the file links-test.txt and Coke's request:

1. The file is generated by htmlify.p6 from URLs gathered.

• The URLs include a number that cannot be tested, so they are deleted by the sh script.
• The sh script uses wget to call the link targets.
• Since the links.txt file only has link targets, but no location information, even when an invalid link is found, it is a hassle to find and fix it.
• The targets are explicitly tested against docs.perl6.org, which is why the test file cannot be used for a local installation.

Suggestions

1. Because there is no location data to fix a bug, I suggest that this test be replaced entirely and the links.txt file ignored.
2. What need testing are every target of the form <a href="..."> in all the files in html/
3. The html filename needs to be kept, and when a bad response is logged, for the filename to be associated with the bad link. That will leave the problem of identifying which pod6 file the bad link originated in, but I expect most will be named similarly to the html file.
4. The problem is how to define server root against which to test, that is if it is a local installation to test against localhost:3000 (assuming the Mojolicious default), rather than docs.perl6.org.

[JJ]

I think there are two separate issues here

1. Check that all the content that was usually generated keeps being generated. That was the case with /syntax/use, for instance. It stopped being generated for some reason. I don't think that's the intent of this issue.
2. Check that all internal links end somewhere safe.
   I think we should create the test for 2. 1 is something completely different.

[JJ]

This is related to the LinkHealth module @antoniogamiz will be working on for GSoC, that's why I assign.

[coke]

Will track in new site at Raku/doc-website#72